zod-args-parser 1.1.0 → 1.2.0

package/src/help-message/{print-help-message.ts → format-cli.ts}

@@ -1,47 +1,39 @@
 import { getCliMetadata } from "../metadata/get-cli-metadata.js";
-import { noColors, printColors } from "./colors.js";
-import { printPreparedArguments } from "./print-arguments.js";
-import { printOptions } from "./print-options.js";
-import { printSubcommands } from "./print-subcommands.js";
-import { concat, indent, ln, print, println } from "./utils.js";
+import { concat, indent, ln } from "../utils.js";
+import { formatHelpMsgArguments } from "./format-arguments.js";
+import { formatHelpMsgOptions } from "./format-options.js";
+import { formatHelpMsgCommands } from "./format-subcommands.js";
+import { helpMsgStyles } from "./styles.js";
 
-import type { Cli, PrintHelpOpt, Subcommand } from "../types.js";
+import type { Cli, HelpMsgStyle, Subcommand } from "../types.js";
 
-export function printCliHelp(params: [Cli, ...Subcommand[]], printConfig: PrintHelpOpt = {}) {
-  printConfig.colors ??= true;
-
-  const c = printConfig.colors ? printColors : noColors;
+export function formatCliHelpMsg(params: readonly [Cli, ...Subcommand[]], style?: Partial<HelpMsgStyle>): string {
+  const c = helpMsgStyles.default;
+  if (style) Object.assign(c, style);
 
   const metadata = getCliMetadata(params);
 
-  if (printConfig.customColors) {
-    Object.assign(c, printConfig.customColors);
-  }
+  const formatTitle = (title: string) => c.title(` ${title.toUpperCase()}`);
 
-  /** Print a styled title */
-  const printTitle = (title: string) => {
-    print(c.title(` ${title.toUpperCase()} `));
-  };
+  let msg = "";
 
-  // Print CLI usage
+  // CLI usage
   const usage =
     metadata.usage ||
     concat(
       c.punctuation("$"),
-      metadata.name,
+      c.description(metadata.name),
       metadata.subcommands.length ? c.command("[command]") : "",
       metadata.options.length ? c.option("[options]") : "",
       metadata.arguments.length || metadata.allowPositional ? c.argument("<arguments>") : "",
     );
-  printTitle("Usage");
-  println();
-  println(indent(2), usage, ln(1));
+  msg += formatTitle("Usage") + ln(1);
+  msg += indent(2) + usage + ln(2);
 
-  // Print CLI description
+  // CLI description
   if (metadata.description) {
-    printTitle("Description");
-    println();
-    println(indent(2), c.description(metadata.description), ln(1));
+    msg += formatTitle("Description") + ln(1);
+    msg += indent(2) + c.description(metadata.description) + ln(2);
   }
 
   let longest = 0;
@@ -76,35 +68,34 @@ export function printCliHelp(params: [Cli, ...Subcommand[]], printConfig: PrintH
 
   // Prepare CLI arguments
   const argsMetadata = metadata.arguments;
-
   const longestArgTitle = argsMetadata.reduce((acc, arg) => (arg.name.length > acc ? arg.name.length : acc), 0);
-
   if (longestArgTitle > longest) {
     longest = longestArgTitle;
   }
 
-  // Print CLI options
-  printOptions(optionsMetadata, c, longest);
+  // CLI options
+  msg += formatHelpMsgOptions(optionsMetadata, c, longest);
 
-  // Print CLI commands
-  printSubcommands(subcommandsMetadata, c, longest);
+  // CLI commands
+  msg += formatHelpMsgCommands(subcommandsMetadata, c, longest);
 
-  // Print CLI arguments
-  printPreparedArguments(argsMetadata, c, longest);
+  // CLI arguments
+  msg += formatHelpMsgArguments(argsMetadata, c, longest);
 
-  // Print CLI example
+  // CLI example
   if (metadata.example) {
-    printTitle("Example");
-    println();
+    msg += formatTitle("Example");
+    msg += ln(1);
     const normalizeExample = metadata.example.replace(/\n/g, "\n" + indent(3));
-    println(indent(2), c.example(normalizeExample), ln(1));
+    msg += concat(indent(2), c.example(normalizeExample), ln(2));
   }
-}
 
-export function printSubcommandHelp(subcommand: Subcommand, printConfig: PrintHelpOpt = {}, cliName = "") {
-  printConfig.colors ??= true;
+  return msg;
+}
 
-  const c = printConfig.colors ? printColors : noColors;
+export function formatSubcommandHelpMsg(subcommand: Subcommand, printStyle?: Partial<HelpMsgStyle>, cliName = "") {
+  const c = helpMsgStyles.default;
+  if (printStyle) Object.assign(c, printStyle);
 
   const usage =
     subcommand.usage ||
@@ -116,11 +107,15 @@ export function printSubcommandHelp(subcommand: Subcommand, printConfig: PrintHe
       subcommand.arguments?.length || subcommand.allowPositional ? c.argument("<arguments>") : "",
     );
 
-  const asCli: Cli = {
-    cliName,
-    usage,
-    ...subcommand,
-  };
+  const asCli: Cli = { cliName, usage, ...subcommand };
+
+  return formatCliHelpMsg([asCli], c);
+}
+
+export function printCliHelp(params: readonly [Cli, ...Subcommand[]], style?: Partial<HelpMsgStyle>) {
+  console.log(formatCliHelpMsg(params, style));
+}
 
-  printCliHelp([asCli], printConfig);
+export function printSubcommandHelp(subcommand: Subcommand, style?: Partial<HelpMsgStyle>, cliName = "") {
+  console.log(formatSubcommandHelpMsg(subcommand, style, cliName));
 }

package/src/help-message/{print-options.ts → format-options.ts}

@@ -1,14 +1,12 @@
-import { indent, print, println } from "./utils.js";
+import { concat, indent, ln } from "../utils.js";
 
-import type { PrintHelpColors } from "./colors.js";
-import type { OptionMetadata } from "../types.js";
+import type { OptionMetadata } from "../metadata/metadata-types.js";
+import type { HelpMsgStyle } from "../types.js";
 
-export function printOptions(optionsMetadata: OptionMetadata[], c: PrintHelpColors, longest: number) {
-  if (!optionsMetadata.length) return;
+export function formatHelpMsgOptions(optionsMetadata: OptionMetadata[], c: HelpMsgStyle, longest: number): string {
+  if (!optionsMetadata.length) return "";
 
-  print(c.title(" OPTIONS "));
-
-  println();
+  let msg = c.title(" OPTIONS") + ln(1);
 
   for (const metadata of optionsMetadata) {
     const names = metadata.aliasesAsArgs.concat([metadata.nameAsArg]);
@@ -21,20 +19,24 @@ export function printOptions(optionsMetadata: OptionMetadata[], c: PrintHelpColo
 
     const coloredNames = names.map(name => c.option(name)).join(c.punctuation(", "));
 
-    println(
-      indent(2),
-      coloredNames,
+    msg += concat(
+      indent(2) + coloredNames,
       c.placeholder(metadata.placeholder),
       indent(spacing),
       c.description(normalizeDesc),
-      defaultStr ? c.default(defaultStr) : metadata.optional ? c.optional("(optional)") : "",
+      (defaultStr ? c.default(defaultStr) : metadata.optional ? c.optional("(optional)") : "") + ln(1),
     );
 
     if (metadata.example) {
       const normalizeExample = metadata.example.replace(/\n/g, "\n" + indent(longest + 17));
-      println(indent(longest + 6), c.punctuation("└") + c.exampleTitle("Example:"), c.example(normalizeExample));
+      msg += concat(
+        indent(longest + 6) + c.punctuation("└") + c.exampleTitle("Example:"),
+        c.example(normalizeExample) + ln(1),
+      );
     }
   }
 
-  println();
+  msg += ln(1);
+
+  return msg;
 }

package/src/help-message/format-subcommands.ts

@@ -0,0 +1,37 @@
+import { concat, indent, ln } from "../utils.js";
+
+import type { SubcommandMetadata } from "../metadata/metadata-types.js";
+import type { HelpMsgStyle } from "../types.js";
+
+export function formatHelpMsgCommands(
+  subcommandsMetadata: SubcommandMetadata[],
+  c: HelpMsgStyle,
+  longest: number,
+): string {
+  if (!subcommandsMetadata.length) return "";
+
+  let msg = c.title(" COMMANDS") + ln(1);
+
+  for (const metadata of subcommandsMetadata) {
+    const names = metadata.aliases.concat([metadata.name]);
+    const placeholder =
+      metadata.placeholder || (metadata.options.length ? "[options]" : metadata.allowPositional ? "<args>" : " ");
+    const normalizeDesc = metadata.description.replace(/\n/g, "\n" + indent(longest + 7) + c.punctuation("└"));
+
+    const optLength = names.join(", ").length + placeholder.length;
+    const spacing = longest + 1 - optLength;
+
+    const coloredNames = names.map(name => c.command(name)).join(c.punctuation(", "));
+
+    msg += concat(
+      indent(2) + coloredNames,
+      c.placeholder(placeholder),
+      indent(spacing),
+      c.description(normalizeDesc) + ln(1),
+    );
+  }
+
+  msg += ln(1);
+
+  return msg;
+}

package/src/help-message/styles.ts

@@ -0,0 +1,120 @@
+import chalk from "chalk";
+import type { HelpMsgStyle } from "../types.js";
+
+export const helpMsgStyles = Object.freeze({
+  default: {
+    title: chalk.bold.blue,
+    description: chalk.white,
+    default: chalk.dim.italic,
+    optional: chalk.dim.italic,
+    exampleTitle: chalk.yellow,
+    example: chalk.dim,
+    command: chalk.yellow,
+    option: chalk.cyan,
+    argument: chalk.green,
+    placeholder: chalk.hex("#FF9800"),
+    punctuation: chalk.white.dim,
+  },
+  dracula: {
+    title: chalk.bold.hex("#BD93F9"),
+    description: chalk.hex("#F8F8F2"),
+    default: chalk.italic.hex("#6272A4"),
+    optional: chalk.italic.hex("#6272A4"),
+    exampleTitle: chalk.hex("#FFB86C"),
+    example: chalk.hex("#6272A4"),
+    command: chalk.hex("#50FA7B"),
+    option: chalk.hex("#8BE9FD"),
+    argument: chalk.hex("#FF79C6"),
+    placeholder: chalk.hex("#F1FA8C"),
+    punctuation: chalk.hex("#6272A4"),
+  },
+  solarizedDark: {
+    title: chalk.bold.hex("#268BD2"),
+    description: chalk.hex("#93A1A1"),
+    default: chalk.italic.hex("#586E75"),
+    optional: chalk.italic.hex("#586E75"),
+    exampleTitle: chalk.hex("#B58900"),
+    example: chalk.hex("#586E75"),
+    command: chalk.hex("#2AA198"),
+    option: chalk.hex("#268BD2"),
+    argument: chalk.hex("#859900"),
+    placeholder: chalk.hex("#CB4B16"),
+    punctuation: chalk.hex("#657B83"),
+  },
+  nord: {
+    title: chalk.bold.hex("#81A1C1"),
+    description: chalk.hex("#D8DEE9"),
+    default: chalk.italic.hex("#4C566A"),
+    optional: chalk.italic.hex("#4C566A"),
+    exampleTitle: chalk.hex("#EBCB8B"),
+    example: chalk.hex("#4C566A"),
+    command: chalk.hex("#A3BE8C"),
+    option: chalk.hex("#88C0D0"),
+    argument: chalk.hex("#BF616A"),
+    placeholder: chalk.hex("#D08770"),
+    punctuation: chalk.hex("#4C566A"),
+  },
+  html: {
+    title: (...str) => `<span style="color: #89dceb; font-weight: bold;">${escapeHTML(str.join(" "))}</span>`,
+    description: (...str) => `<span style="color: #cdd6e8;">${escapeHTML(str.join(" "))}</span>`,
+    default: (...str) => `<span style="color: #6c7086; font-style: italic;">${escapeHTML(str.join(" "))}</span>`,
+    optional: (...str) => `<span style="color: #6c7086; font-style: italic;">${escapeHTML(str.join(" "))}</span>`,
+    exampleTitle: (...str) => `<span style="color: #f9e2af;">${escapeHTML(str.join(" "))}</span>`,
+    example: (...str) => `<span style="color: #6c7086;">${escapeHTML(str.join(" "))}</span>`,
+    command: (...str) => `<span style="color: #f9e2af;">${escapeHTML(str.join(" "))}</span>`,
+    option: (...str) => `<span style="color: #17b85d;">${escapeHTML(str.join(" "))}</span>`,
+    argument: (...str) => `<span style="color: #00ff00;">${escapeHTML(str.join(" "))}</span>`,
+    placeholder: (...str) => `<span style="color: #db9518;">${escapeHTML(str.join(" "))}</span>`,
+    punctuation: (...str) => `<span style="color: #6c7086;">${escapeHTML(str.join(" "))}</span>`,
+  },
+  gruvboxDark: {
+    title: chalk.bold.hex("#FABD2F"),
+    description: chalk.hex("#EBDBB2"),
+    default: chalk.italic.hex("#928374"),
+    optional: chalk.italic.hex("#928374"),
+    exampleTitle: chalk.hex("#FE8019"),
+    example: chalk.hex("#928374"),
+    command: chalk.hex("#B8BB26"),
+    option: chalk.hex("#83A598"),
+    argument: chalk.hex("#D3869B"),
+    placeholder: chalk.hex("#FB4934"),
+    punctuation: chalk.hex("#928374"),
+  },
+  monokai: {
+    title: chalk.bold.hex("#AE81FF"),
+    description: chalk.hex("#F8F8F2"),
+    default: chalk.italic.hex("#75715E"),
+    optional: chalk.italic.hex("#75715E"),
+    exampleTitle: chalk.hex("#FD971F"),
+    example: chalk.hex("#75715E"),
+    command: chalk.hex("#A6E22E"),
+    option: chalk.hex("#66D9EF"),
+    argument: chalk.hex("#F92672"),
+    placeholder: chalk.hex("#E6DB74"),
+    punctuation: chalk.hex("#75715E"),
+  },
+  oneDark: {
+    title: chalk.bold.hex("#61AFEF"),
+    description: chalk.hex("#ABB2BF"),
+    default: chalk.italic.hex("#5C6370"),
+    optional: chalk.italic.hex("#5C6370"),
+    exampleTitle: chalk.hex("#E5C07B"),
+    example: chalk.hex("#5C6370"),
+    command: chalk.hex("#98C379"),
+    option: chalk.hex("#56B6C2"),
+    argument: chalk.hex("#E06C75"),
+    placeholder: chalk.hex("#C678DD"),
+    punctuation: chalk.hex("#5C6370"),
+  },
+  get noColors() {
+    return new Proxy(this.default, {
+      get() {
+        return (...str: string[]) => str.join(" ");
+      },
+    });
+  },
+}) satisfies Record<string, HelpMsgStyle>;
+
+function escapeHTML(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/src/index.ts

@@ -1,63 +1,56 @@
 import type {
-  ActionFn,
+  ActionsFn,
   Argument,
+  CheckArgumentsOptional,
+  CheckDuplicatedArguments,
   CheckDuplicatedOptions,
   Cli,
   Option,
   Prettify,
   Subcommand,
-  UnSafeParseResult,
 } from "./types.js";
 
-/**
- * - Insures that there is no extra keys in `obj` compared to `shape`
- * - Also checks objects in arrays useful for the keys `options` and `arguments`
- */
-type Exact<Obj extends object, Shape extends object> = {
-  [K in keyof Obj]: K extends keyof Shape
-    ? Obj[K] extends infer ObjArr extends object[]
-      ? Required<Shape>[K] extends infer ShapeArr extends object[]
-        ? ExactObjArr<ObjArr, ShapeArr[number]>
-        : Obj[K]
-      : Obj[K]
-    : never;
-};
-
-/** - Insures that there is no extra keys in `obj` compared to `shape` */
-type ExactKeys<T extends object, U extends object> = { [K in keyof T]: K extends keyof U ? T[K] : never };
-
-/** - Insures that there is no extra keys in the objects in an array compared to `shape` */
-type ExactObjArr<ObjArr extends object[], ShapeObj extends object> = {
-  [K in keyof ObjArr]: ExactKeys<ObjArr[K], ShapeObj>;
-};
-
 /**
  * - Insures that there are no duplicated options
- * - Disallow extra keys
+ * - Insures that there are no duplicated arguments
+ * - Insures that only the last argument is optional
+ * - Insures no optional arguments are allowed when `allowPositional` is enabled
  */
-type CliInput<T extends Cli> = CheckDuplicatedOptions<T> extends T ? Exact<T, Cli> : CheckDuplicatedOptions<T>;
-
-export function createCli<const T extends Cli>(input: CliInput<T>) {
-  const setAction = (action: (res: UnSafeParseResult<[T]>) => void) => {
+type CheckCliSubcommandInput<T extends Cli | Subcommand> =
+  CheckDuplicatedOptions<T> extends infer Err extends string
+    ? Err
+    : CheckDuplicatedArguments<T> extends infer Err extends string
+      ? Err
+      : CheckArgumentsOptional<T> extends infer Err extends string
+        ? Err
+        : T;
+
+export function createCli<const T extends Cli>(input: CheckCliSubcommandInput<T>) {
+  const setAction = (action: (res: any) => any) => {
+    if (typeof input === "string") return;
     input.action = action;
   };
 
-  return Object.assign(input, { setAction }) as Prettify<CliInput<T> & ActionFn<T>>;
+  const setPreValidationHook = (hook: (ctx: any) => any) => {
+    if (typeof input === "string") return;
+    input.preValidation = hook;
+  };
+
+  return Object.assign(input, { setAction, setPreValidationHook }) as Prettify<typeof input & ActionsFn<T>>;
 }
 
-/**
- * - Insures that there are no duplicated options
- * - Disallow extra keys
- */
-type SubcommandInput<T extends Subcommand> =
-  CheckDuplicatedOptions<T> extends T ? Exact<T, Subcommand> : CheckDuplicatedOptions<T>;
+export function createSubcommand<const T extends Subcommand>(input: CheckCliSubcommandInput<T>) {
+  const setAction = (action: (res: any) => any) => {
+    if (typeof input === "string") return;
+    input.action = action as T["action"];
+  };
 
-export function createSubcommand<const T extends Subcommand>(input: SubcommandInput<T>) {
-  const setAction = (action: (res: UnSafeParseResult<[T]>) => void) => {
-    input.action = action;
+  const setPreValidationHook = (hook: (ctx: any) => any) => {
+    if (typeof input === "string") return;
+    input.preValidation = hook;
   };
 
-  return Object.assign(input, { setAction }) as Prettify<SubcommandInput<T> & ActionFn<T>>;
+  return Object.assign(input, { setAction, setPreValidationHook }) as Prettify<typeof input & ActionsFn<T>>;
 }
 
 /** - Insures that there are no duplicated options */
@@ -68,14 +61,26 @@ export function createOptions<const T extends [Option, ...Option[]]>(options: Ch
   return options;
 }
 
-export function createArguments<const T extends [Argument, ...Argument[]]>(args: T) {
+/** - Insures that only the last argument is optional */
+type CheckArgumentsInput<T extends Argument[]> =
+  CheckArgumentsOptional<{ arguments: T }> extends infer Err extends string ? Err : T;
+
+export function createArguments<const T extends [Argument, ...Argument[]]>(args: CheckArgumentsInput<T>) {
   return args;
 }
 
-export { printCliHelp, printSubcommandHelp } from "./help-message/print-help-message.js";
+export {
+  formatCliHelpMsg,
+  printCliHelp,
+  formatSubcommandHelpMsg,
+  printSubcommandHelp,
+} from "./help-message/format-cli.js";
+export { helpMsgStyles } from "./help-message/styles.js";
+
+export { unsafeParse as parse, unsafeParseAsync as parseAsync } from "./parser/unsafe-parse.js";
+export { safeParse, safeParseAsync } from "./parser/safe-parse.js";
 
-export { parse } from "./parser/parse.js";
-export { safeParse } from "./parser/safe-parse.js";
+export { isOptionalSchema, schemaDefaultValue, stringToArray, stringToSet } from "./zod-utils.js";
 
 export { generateBashAutocompleteScript } from "./autocomplete-scripts/bash-autocomplete-script.js";
 export { generatePowerShellAutocompleteScript } from "./autocomplete-scripts/powershell-autocomplete-script.js";
@@ -89,3 +94,4 @@ export { getSubcommandsMetadata } from "./metadata/get-subcommands-metadata.js";
 export { generateMarkdown } from "./markdown/generate-markdown.js";
 
 export type * from "./types.js";
+export type * from "./metadata/metadata-types.js";

package/src/markdown/generate-markdown.ts

@@ -1,6 +1,7 @@
 import { getCliMetadata } from "../metadata/get-cli-metadata.js";
 
-import type { ArgumentMetadata, Cli, OptionMetadata, Subcommand, SubcommandMetadata } from "../types.js";
+import type { ArgumentMetadata, OptionMetadata, SubcommandMetadata } from "../metadata/metadata-types.js";
+import type { Cli, Subcommand } from "../types.js";
 
 export function generateMarkdown(...params: [Cli, ...Subcommand[]]): string {
   const metadata = getCliMetadata(params);

package/src/metadata/get-arguments-metadata.ts

@@ -1,6 +1,7 @@
-import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zodUtils.js";
+import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utils.js";
 
-import type { Argument, ArgumentMetadata } from "../types.js";
+import type { Argument } from "../types.js";
+import type { ArgumentMetadata } from "./metadata-types.js";
 
 export function getArgumentsMetadata(args: Argument[]): ArgumentMetadata[] {
   const outputMetadata: ArgumentMetadata[] = [];

package/src/metadata/get-cli-metadata.ts

@@ -1,16 +1,16 @@
-import { getOptionsMetadata } from "./get-options-metadata.js";
 import { getArgumentsMetadata } from "./get-arguments-metadata.js";
+import { getOptionsMetadata } from "./get-options-metadata.js";
 import { getSubcommandsMetadata } from "./get-subcommands-metadata.js";
 
-import type { Cli, CliMetadata, Subcommand } from "../types.js";
+import type { Cli, Subcommand } from "../types.js";
+import type { CliMetadata } from "./metadata-types.js";
 
-export function getCliMetadata(inputData: [Cli, ...Subcommand[]]): CliMetadata {
+export function getCliMetadata(inputData: readonly [Cli, ...Subcommand[]]): CliMetadata {
   const [cli, ...subcommands] = inputData;
 
   const outputMetadata: CliMetadata = {
     name: cli.cliName,
     description: cli.description ?? "",
-    placeholder: cli.placeholder ?? "",
     usage: cli.usage ?? "",
     example: cli.example ?? "",
     allowPositional: cli.allowPositional ?? false,

package/src/metadata/get-options-metadata.ts

@@ -1,7 +1,8 @@
-import { transformOptionToArg } from "../utils.js";
-import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zodUtils.js";
+import { transformOptionToArg } from "../parser/parse/parser-helpers.js";
+import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utils.js";
 
-import type { Option, OptionMetadata } from "../types.js";
+import type { Option } from "../types.js";
+import type { OptionMetadata } from "./metadata-types.js";
 
 export function getOptionsMetadata(options: Option[]): OptionMetadata[] {
   const outputMetadata: OptionMetadata[] = [];

package/src/metadata/get-subcommands-metadata.ts

@@ -1,7 +1,8 @@
 import { getArgumentsMetadata } from "./get-arguments-metadata.js";
 import { getOptionsMetadata } from "./get-options-metadata.js";
 
-import type { Subcommand, SubcommandMetadata } from "../types.js";
+import type { Subcommand } from "../types.js";
+import type { SubcommandMetadata } from "./metadata-types.js";
 
 export function getSubcommandsMetadata(subcommands: Subcommand[]): SubcommandMetadata[] {
   const outputMetadata: SubcommandMetadata[] = [];

package/src/metadata/metadata-types.ts

@@ -0,0 +1,114 @@
+import type { Schema } from "../types.js";
+
+export interface CliMetadata {
+  /** The name of the cli program. */
+  readonly name: string;
+
+  /** - The description of the cli program. Empty string if not provided */
+  readonly description: string;
+
+  /** - The usage of the cli program. Empty string if not provided */
+  readonly usage: string;
+
+  /** - The example of the cli program. Empty string if not provided */
+  readonly example: string;
+
+  /** - Whether the cli program allows positional arguments. */
+  readonly allowPositional: boolean;
+
+  /** - The options of the cli program. Empty array if not provided */
+  readonly options: OptionMetadata[];
+
+  /** - The arguments of the cli program. Empty array if not provided */
+  readonly arguments: ArgumentMetadata[];
+
+  /** - The subcommands of the cli program. Empty array if not provided */
+  readonly subcommands: SubcommandMetadata[];
+}
+
+export interface SubcommandMetadata {
+  /** The subcommand name. */
+  readonly name: string;
+
+  /** - The aliases of the subcommand. Empty array if not provided */
+  readonly aliases: string[];
+
+  /** - The description of the subcommand. Empty string if not provided */
+  readonly description: string;
+
+  /** - The placeholder of the subcommand. Empty string if not provided */
+  readonly placeholder: string;
+
+  /** - The usage of the subcommand. Empty string if not provided */
+  readonly usage: string;
+
+  /** - The example of the subcommand. Empty string if not provided */
+  readonly example: string;
+
+  /** - Whether the subcommand allows positional arguments. */
+  readonly allowPositional: boolean;
+
+  /** - The options of the subcommand. Empty array if not provided */
+  readonly options: OptionMetadata[];
+
+  /** - The arguments of the subcommand. Empty array if not provided */
+  readonly arguments: ArgumentMetadata[];
+}
+
+export interface OptionMetadata {
+  /** The option name in camelCase. E.g. `optionName` */
+  readonly name: string;
+
+  /** The option name in kebab-case. E.g. `--option-name` */
+  readonly nameAsArg: string;
+
+  /** - The aliases of the option in camelCase. Empty array if not provided. E.g. `[aliasName, ...]` */
+  readonly aliases: string[];
+
+  /** - The aliases of the option in kebab-case. Empty array if not provided. E.g. `[--alias-name, ...]` */
+  readonly aliasesAsArgs: string[];
+
+  /** - The description of the option. Empty string if not provided */
+  readonly description: string;
+
+  /** - The placeholder of the option. Empty string if not provided */
+  readonly placeholder: string;
+
+  /** - The example of the option. Empty string if not provided */
+  readonly example: string;
+
+  /** - The default value of the option. */
+  readonly defaultValue: unknown;
+
+  /** - The default value of the option as string. */
+  readonly defaultValueAsString: string;
+
+  /** - Whether the option is optional. */
+  readonly optional: boolean;
+
+  /** - The zod type of the option. */
+  readonly type: Schema;
+}
+
+export interface ArgumentMetadata {
+  /** The argument name. */
+  readonly name: string;
+
+  /** - The description of the argument. Empty string if not provided */
+  readonly description: string;
+
+  /** - The example of the argument. Empty string if not provided */
+  readonly example: string;
+
+  /** - The default value of the argument. */
+  readonly defaultValue: unknown;
+
+  /** - The default value of the argument as string. */
+  readonly defaultValueAsString: string;
+
+  /** - Whether the argument is optional. */
+  readonly optional: boolean;
+
+  /** - The zod type of the argument. */
+  readonly type: Schema;
+}