@boneskull/bargs 0.1.1

package/dist/theme.d.cts

@@ -0,0 +1,227 @@
+/**
+ * Theming system for colorized help output.
+ *
+ * Provides ANSI color codes, built-in themes (default, mono, ocean, warm), and
+ * utilities for creating custom themes. Each theme defines colors for semantic
+ * elements like flags, commands, descriptions, and section headers. Themes can
+ * be customized by overriding individual color properties.
+ *
+ * @packageDocumentation
+ */
+import { stripVTControlCharacters } from 'node:util';
+/**
+ * Strip all ANSI escape codes from a string.
+ */
+export declare const stripAnsi: typeof stripVTControlCharacters;
+/**
+ * A bargs color theme. All color properties are optional and fall back to the
+ * default theme.
+ */
+export interface Theme {
+    colors?: Partial<ThemeColors>;
+}
+/**
+ * Color codes for each semantic element in help output. Empty string means no
+ * color (passthrough).
+ */
+export interface ThemeColors {
+    /** Command names (e.g., "init", "build") */
+    command: string;
+    /** The "default: " label text */
+    defaultText: string;
+    /** Default value annotations (e.g., "false", ""hello"") */
+    defaultValue: string;
+    /** Description text for options/commands */
+    description: string;
+    /** Epilog text (homepage, repository) */
+    epilog: string;
+    /** Example code/commands */
+    example: string;
+    /** Flag names (e.g., "--verbose", "-v") */
+    flag: string;
+    /** Positional argument names (e.g., "<file>") */
+    positional: string;
+    /** CLI name shown in header (e.g., "myapp") */
+    scriptName: string;
+    /** Section headers (e.g., "USAGE", "OPTIONS") */
+    sectionHeader: string;
+    /** Type annotations (e.g., "[string]", "[number]") */
+    type: string;
+    /** URL text (for linkified URLs) */
+    url: string;
+    /** Usage line text */
+    usage: string;
+}
+/**
+ * Theme input - either a theme name or a custom Theme object.
+ */
+export type ThemeInput = keyof typeof themes | Theme;
+/**
+ * Internal resolved theme with all colors defined.
+ */
+interface ResolvedTheme {
+    colors: ThemeColors;
+}
+/**
+ * ANSI escape codes for building custom themes.
+ *
+ * Includes text styles (bold, italic, underline, etc.), foreground colors,
+ * bright foreground colors, background colors, and bright background colors.
+ */
+export declare const ansi: {
+    readonly bgBlack: "\u001B[40m";
+    readonly bgBlue: "\u001B[44m";
+    readonly bgBrightBlack: "\u001B[100m";
+    readonly bgBrightBlue: "\u001B[104m";
+    readonly bgBrightCyan: "\u001B[106m";
+    readonly bgBrightGreen: "\u001B[102m";
+    readonly bgBrightMagenta: "\u001B[105m";
+    readonly bgBrightRed: "\u001B[101m";
+    readonly bgBrightWhite: "\u001B[107m";
+    readonly bgBrightYellow: "\u001B[103m";
+    readonly bgCyan: "\u001B[46m";
+    readonly bgGreen: "\u001B[42m";
+    readonly bgMagenta: "\u001B[45m";
+    readonly bgRed: "\u001B[41m";
+    readonly bgWhite: "\u001B[47m";
+    readonly bgYellow: "\u001B[43m";
+    readonly black: "\u001B[30m";
+    readonly blue: "\u001B[34m";
+    readonly bold: "\u001B[1m";
+    readonly brightBlack: "\u001B[90m";
+    readonly brightBlue: "\u001B[94m";
+    readonly brightCyan: "\u001B[96m";
+    readonly brightGreen: "\u001B[92m";
+    readonly brightMagenta: "\u001B[95m";
+    readonly brightRed: "\u001B[91m";
+    readonly brightWhite: "\u001B[97m";
+    readonly brightYellow: "\u001B[93m";
+    readonly cyan: "\u001B[36m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly hidden: "\u001B[8m";
+    readonly inverse: "\u001B[7m";
+    readonly italic: "\u001B[3m";
+    readonly magenta: "\u001B[35m";
+    readonly red: "\u001B[31m";
+    readonly reset: "\u001B[0m";
+    readonly strikethrough: "\u001B[9m";
+    readonly underline: "\u001B[4m";
+    readonly white: "\u001B[37m";
+    readonly yellow: "\u001B[33m";
+};
+/**
+ * Built-in themes.
+ */
+export declare const themes: {
+    /** Default colorful theme */
+    readonly default: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: string;
+            readonly defaultValue: string;
+            readonly description: string;
+            readonly epilog: string;
+            readonly example: string;
+            readonly flag: string;
+            readonly positional: string;
+            readonly scriptName: string;
+            readonly sectionHeader: string;
+            readonly type: string;
+            readonly url: string;
+            readonly usage: string;
+        };
+    };
+    /** No colors (monochrome) */
+    readonly mono: {
+        readonly colors: {
+            readonly command: "";
+            readonly defaultText: "";
+            readonly defaultValue: "";
+            readonly description: "";
+            readonly epilog: "";
+            readonly example: "";
+            readonly flag: "";
+            readonly positional: "";
+            readonly scriptName: "";
+            readonly sectionHeader: "";
+            readonly type: "";
+            readonly url: "";
+            readonly usage: "";
+        };
+    };
+    /** Ocean theme - blues and greens (bright) */
+    readonly ocean: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: "\u001B[34m";
+            readonly defaultValue: "\u001B[32m";
+            readonly description: "\u001B[37m";
+            readonly epilog: "\u001B[34m";
+            readonly example: string;
+            readonly flag: "\u001B[96m";
+            readonly positional: "\u001B[92m";
+            readonly scriptName: string;
+            readonly sectionHeader: "\u001B[94m";
+            readonly type: "\u001B[36m";
+            readonly url: "\u001B[96m";
+            readonly usage: "\u001B[37m";
+        };
+    };
+    /** Warm theme - reds and yellows */
+    readonly warm: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: string;
+            readonly defaultValue: "\u001B[93m";
+            readonly description: "\u001B[37m";
+            readonly epilog: string;
+            readonly example: string;
+            readonly flag: "\u001B[93m";
+            readonly positional: "\u001B[91m";
+            readonly scriptName: string;
+            readonly sectionHeader: "\u001B[31m";
+            readonly type: "\u001B[33m";
+            readonly url: "\u001B[93m";
+            readonly usage: "\u001B[37m";
+        };
+    };
+};
+/**
+ * Default theme export for convenience.
+ */
+export declare const defaultTheme: ResolvedTheme;
+/**
+ * Resolve a theme input to a fully resolved Theme with all colors defined.
+ * Missing colors fall back to the default theme.
+ */
+export declare const getTheme: (input: ThemeInput) => ResolvedTheme;
+/**
+ * Style function that wraps text with ANSI codes.
+ */
+export type StyleFn = (text: string) => string;
+/**
+ * Styler object with methods for each semantic element.
+ */
+export interface Styler {
+    command: StyleFn;
+    defaultText: StyleFn;
+    defaultValue: StyleFn;
+    description: StyleFn;
+    epilog: StyleFn;
+    example: StyleFn;
+    flag: StyleFn;
+    positional: StyleFn;
+    scriptName: StyleFn;
+    sectionHeader: StyleFn;
+    type: StyleFn;
+    url: StyleFn;
+    usage: StyleFn;
+}
+/**
+ * Create a Styler from a Theme. If the theme has missing colors, they fall back
+ * to the default theme.
+ */
+export declare const createStyler: (theme: Theme) => Styler;
+export {};
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,SAAS,iCAA2B,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,MAAM,GAAG,KAAK,CAAC;AAErD;;GAEG;AACH,UAAU,aAAa;IACrB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCP,CAAC;AAqBX;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB,6BAA6B;;;8BA/GpB,MAAM;kCAEF,MAAM;mCAEL,MAAM;kCAEP,MAAM;6BAEX,MAAM;8BAEL,MAAM;2BAET,MAAM;iCAEA,MAAM;iCAEN,MAAM;oCAEH,MAAM;2BAEf,MAAM;0BAEP,MAAM;4BAEJ,MAAM;;;IA4Fb,6BAA6B;;;;;;;;;;;;;;;;;;IAmB7B,8CAA8C;;;;;;;;;;;;;;;;;;IAmB9C,oCAAoC;;;;;;;;;;;;;;;;;;CAkBY,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,aAA8B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,aAQ5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAkBD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,MAiB3C,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Theming system for colorized help output.
+ *
+ * Provides ANSI color codes, built-in themes (default, mono, ocean, warm), and
+ * utilities for creating custom themes. Each theme defines colors for semantic
+ * elements like flags, commands, descriptions, and section headers. Themes can
+ * be customized by overriding individual color properties.
+ *
+ * @packageDocumentation
+ */
+import { stripVTControlCharacters } from 'node:util';
+/**
+ * Strip all ANSI escape codes from a string.
+ */
+export declare const stripAnsi: typeof stripVTControlCharacters;
+/**
+ * A bargs color theme. All color properties are optional and fall back to the
+ * default theme.
+ */
+export interface Theme {
+    colors?: Partial<ThemeColors>;
+}
+/**
+ * Color codes for each semantic element in help output. Empty string means no
+ * color (passthrough).
+ */
+export interface ThemeColors {
+    /** Command names (e.g., "init", "build") */
+    command: string;
+    /** The "default: " label text */
+    defaultText: string;
+    /** Default value annotations (e.g., "false", ""hello"") */
+    defaultValue: string;
+    /** Description text for options/commands */
+    description: string;
+    /** Epilog text (homepage, repository) */
+    epilog: string;
+    /** Example code/commands */
+    example: string;
+    /** Flag names (e.g., "--verbose", "-v") */
+    flag: string;
+    /** Positional argument names (e.g., "<file>") */
+    positional: string;
+    /** CLI name shown in header (e.g., "myapp") */
+    scriptName: string;
+    /** Section headers (e.g., "USAGE", "OPTIONS") */
+    sectionHeader: string;
+    /** Type annotations (e.g., "[string]", "[number]") */
+    type: string;
+    /** URL text (for linkified URLs) */
+    url: string;
+    /** Usage line text */
+    usage: string;
+}
+/**
+ * Theme input - either a theme name or a custom Theme object.
+ */
+export type ThemeInput = keyof typeof themes | Theme;
+/**
+ * Internal resolved theme with all colors defined.
+ */
+interface ResolvedTheme {
+    colors: ThemeColors;
+}
+/**
+ * ANSI escape codes for building custom themes.
+ *
+ * Includes text styles (bold, italic, underline, etc.), foreground colors,
+ * bright foreground colors, background colors, and bright background colors.
+ */
+export declare const ansi: {
+    readonly bgBlack: "\u001B[40m";
+    readonly bgBlue: "\u001B[44m";
+    readonly bgBrightBlack: "\u001B[100m";
+    readonly bgBrightBlue: "\u001B[104m";
+    readonly bgBrightCyan: "\u001B[106m";
+    readonly bgBrightGreen: "\u001B[102m";
+    readonly bgBrightMagenta: "\u001B[105m";
+    readonly bgBrightRed: "\u001B[101m";
+    readonly bgBrightWhite: "\u001B[107m";
+    readonly bgBrightYellow: "\u001B[103m";
+    readonly bgCyan: "\u001B[46m";
+    readonly bgGreen: "\u001B[42m";
+    readonly bgMagenta: "\u001B[45m";
+    readonly bgRed: "\u001B[41m";
+    readonly bgWhite: "\u001B[47m";
+    readonly bgYellow: "\u001B[43m";
+    readonly black: "\u001B[30m";
+    readonly blue: "\u001B[34m";
+    readonly bold: "\u001B[1m";
+    readonly brightBlack: "\u001B[90m";
+    readonly brightBlue: "\u001B[94m";
+    readonly brightCyan: "\u001B[96m";
+    readonly brightGreen: "\u001B[92m";
+    readonly brightMagenta: "\u001B[95m";
+    readonly brightRed: "\u001B[91m";
+    readonly brightWhite: "\u001B[97m";
+    readonly brightYellow: "\u001B[93m";
+    readonly cyan: "\u001B[36m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly hidden: "\u001B[8m";
+    readonly inverse: "\u001B[7m";
+    readonly italic: "\u001B[3m";
+    readonly magenta: "\u001B[35m";
+    readonly red: "\u001B[31m";
+    readonly reset: "\u001B[0m";
+    readonly strikethrough: "\u001B[9m";
+    readonly underline: "\u001B[4m";
+    readonly white: "\u001B[37m";
+    readonly yellow: "\u001B[33m";
+};
+/**
+ * Built-in themes.
+ */
+export declare const themes: {
+    /** Default colorful theme */
+    readonly default: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: string;
+            readonly defaultValue: string;
+            readonly description: string;
+            readonly epilog: string;
+            readonly example: string;
+            readonly flag: string;
+            readonly positional: string;
+            readonly scriptName: string;
+            readonly sectionHeader: string;
+            readonly type: string;
+            readonly url: string;
+            readonly usage: string;
+        };
+    };
+    /** No colors (monochrome) */
+    readonly mono: {
+        readonly colors: {
+            readonly command: "";
+            readonly defaultText: "";
+            readonly defaultValue: "";
+            readonly description: "";
+            readonly epilog: "";
+            readonly example: "";
+            readonly flag: "";
+            readonly positional: "";
+            readonly scriptName: "";
+            readonly sectionHeader: "";
+            readonly type: "";
+            readonly url: "";
+            readonly usage: "";
+        };
+    };
+    /** Ocean theme - blues and greens (bright) */
+    readonly ocean: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: "\u001B[34m";
+            readonly defaultValue: "\u001B[32m";
+            readonly description: "\u001B[37m";
+            readonly epilog: "\u001B[34m";
+            readonly example: string;
+            readonly flag: "\u001B[96m";
+            readonly positional: "\u001B[92m";
+            readonly scriptName: string;
+            readonly sectionHeader: "\u001B[94m";
+            readonly type: "\u001B[36m";
+            readonly url: "\u001B[96m";
+            readonly usage: "\u001B[37m";
+        };
+    };
+    /** Warm theme - reds and yellows */
+    readonly warm: {
+        readonly colors: {
+            readonly command: string;
+            readonly defaultText: string;
+            readonly defaultValue: "\u001B[93m";
+            readonly description: "\u001B[37m";
+            readonly epilog: string;
+            readonly example: string;
+            readonly flag: "\u001B[93m";
+            readonly positional: "\u001B[91m";
+            readonly scriptName: string;
+            readonly sectionHeader: "\u001B[31m";
+            readonly type: "\u001B[33m";
+            readonly url: "\u001B[93m";
+            readonly usage: "\u001B[37m";
+        };
+    };
+};
+/**
+ * Default theme export for convenience.
+ */
+export declare const defaultTheme: ResolvedTheme;
+/**
+ * Resolve a theme input to a fully resolved Theme with all colors defined.
+ * Missing colors fall back to the default theme.
+ */
+export declare const getTheme: (input: ThemeInput) => ResolvedTheme;
+/**
+ * Style function that wraps text with ANSI codes.
+ */
+export type StyleFn = (text: string) => string;
+/**
+ * Styler object with methods for each semantic element.
+ */
+export interface Styler {
+    command: StyleFn;
+    defaultText: StyleFn;
+    defaultValue: StyleFn;
+    description: StyleFn;
+    epilog: StyleFn;
+    example: StyleFn;
+    flag: StyleFn;
+    positional: StyleFn;
+    scriptName: StyleFn;
+    sectionHeader: StyleFn;
+    type: StyleFn;
+    url: StyleFn;
+    usage: StyleFn;
+}
+/**
+ * Create a Styler from a Theme. If the theme has missing colors, they fall back
+ * to the default theme.
+ */
+export declare const createStyler: (theme: Theme) => Styler;
+export {};
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,SAAS,iCAA2B,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,MAAM,GAAG,KAAK,CAAC;AAErD;;GAEG;AACH,UAAU,aAAa;IACrB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCP,CAAC;AAqBX;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB,6BAA6B;;;8BA/GpB,MAAM;kCAEF,MAAM;mCAEL,MAAM;kCAEP,MAAM;6BAEX,MAAM;8BAEL,MAAM;2BAET,MAAM;iCAEA,MAAM;iCAEN,MAAM;oCAEH,MAAM;2BAEf,MAAM;0BAEP,MAAM;4BAEJ,MAAM;;;IA4Fb,6BAA6B;;;;;;;;;;;;;;;;;;IAmB7B,8CAA8C;;;;;;;;;;;;;;;;;;IAmB9C,oCAAoC;;;;;;;;;;;;;;;;;;CAkBY,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,aAA8B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,aAQ5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAkBD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,MAiB3C,CAAC"}

package/dist/theme.js

@@ -0,0 +1,198 @@
+/**
+ * Theming system for colorized help output.
+ *
+ * Provides ANSI color codes, built-in themes (default, mono, ocean, warm), and
+ * utilities for creating custom themes. Each theme defines colors for semantic
+ * elements like flags, commands, descriptions, and section headers. Themes can
+ * be customized by overriding individual color properties.
+ *
+ * @packageDocumentation
+ */
+import { stripVTControlCharacters } from 'node:util';
+/**
+ * Strip all ANSI escape codes from a string.
+ */
+export const stripAnsi = stripVTControlCharacters;
+/**
+ * ANSI escape codes for building custom themes.
+ *
+ * Includes text styles (bold, italic, underline, etc.), foreground colors,
+ * bright foreground colors, background colors, and bright background colors.
+ */
+export const ansi = {
+    bgBlack: '\x1b[40m',
+    bgBlue: '\x1b[44m',
+    bgBrightBlack: '\x1b[100m',
+    bgBrightBlue: '\x1b[104m',
+    bgBrightCyan: '\x1b[106m',
+    bgBrightGreen: '\x1b[102m',
+    bgBrightMagenta: '\x1b[105m',
+    bgBrightRed: '\x1b[101m',
+    bgBrightWhite: '\x1b[107m',
+    bgBrightYellow: '\x1b[103m',
+    bgCyan: '\x1b[46m',
+    bgGreen: '\x1b[42m',
+    bgMagenta: '\x1b[45m',
+    bgRed: '\x1b[41m',
+    bgWhite: '\x1b[47m',
+    bgYellow: '\x1b[43m',
+    black: '\x1b[30m',
+    blue: '\x1b[34m',
+    bold: '\x1b[1m',
+    brightBlack: '\x1b[90m',
+    brightBlue: '\x1b[94m',
+    brightCyan: '\x1b[96m',
+    brightGreen: '\x1b[92m',
+    brightMagenta: '\x1b[95m',
+    brightRed: '\x1b[91m',
+    brightWhite: '\x1b[97m',
+    brightYellow: '\x1b[93m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    hidden: '\x1b[8m',
+    inverse: '\x1b[7m',
+    italic: '\x1b[3m',
+    magenta: '\x1b[35m',
+    red: '\x1b[31m',
+    reset: '\x1b[0m',
+    strikethrough: '\x1b[9m',
+    underline: '\x1b[4m',
+    white: '\x1b[37m',
+    yellow: '\x1b[33m',
+};
+/**
+ * Default color values used when theme colors are not specified.
+ */
+const defaultColors = {
+    command: ansi.bold,
+    defaultText: ansi.dim,
+    defaultValue: ansi.white,
+    description: ansi.white,
+    epilog: ansi.dim,
+    example: ansi.white + ansi.dim,
+    flag: ansi.brightCyan,
+    positional: ansi.magenta,
+    scriptName: ansi.bold,
+    sectionHeader: ansi.brightMagenta,
+    type: ansi.magenta,
+    url: ansi.cyan,
+    usage: ansi.cyan,
+};
+/**
+ * Built-in themes.
+ */
+export const themes = {
+    /** Default colorful theme */
+    default: {
+        colors: { ...defaultColors },
+    },
+    /** No colors (monochrome) */
+    mono: {
+        colors: {
+            command: '',
+            defaultText: '',
+            defaultValue: '',
+            description: '',
+            epilog: '',
+            example: '',
+            flag: '',
+            positional: '',
+            scriptName: '',
+            sectionHeader: '',
+            type: '',
+            url: '',
+            usage: '',
+        },
+    },
+    /** Ocean theme - blues and greens (bright) */
+    ocean: {
+        colors: {
+            command: ansi.bold + ansi.brightCyan,
+            defaultText: ansi.blue,
+            defaultValue: ansi.green,
+            description: ansi.white,
+            epilog: ansi.blue,
+            example: ansi.dim + ansi.white,
+            flag: ansi.brightCyan,
+            positional: ansi.brightGreen,
+            scriptName: ansi.bold + ansi.brightBlue,
+            sectionHeader: ansi.brightBlue,
+            type: ansi.cyan,
+            url: ansi.brightCyan,
+            usage: ansi.white,
+        },
+    },
+    /** Warm theme - reds and yellows */
+    warm: {
+        colors: {
+            command: ansi.bold + ansi.yellow,
+            defaultText: ansi.dim + ansi.yellow,
+            defaultValue: ansi.brightYellow,
+            description: ansi.white,
+            epilog: ansi.dim + ansi.yellow,
+            example: ansi.white + ansi.dim,
+            flag: ansi.brightYellow,
+            positional: ansi.brightRed,
+            scriptName: ansi.bold + ansi.red,
+            sectionHeader: ansi.red,
+            type: ansi.yellow,
+            url: ansi.brightYellow,
+            usage: ansi.white,
+        },
+    },
+};
+/**
+ * Default theme export for convenience.
+ */
+export const defaultTheme = themes.default;
+/**
+ * Resolve a theme input to a fully resolved Theme with all colors defined.
+ * Missing colors fall back to the default theme.
+ */
+export const getTheme = (input) => {
+    if (typeof input === 'string') {
+        return themes[input];
+    }
+    // Merge with defaults for partial themes
+    return {
+        colors: { ...defaultColors, ...input.colors },
+    };
+};
+/**
+ * ANSI reset code.
+ */
+const RESET = '\x1b[0m';
+/**
+ * Create a style function from a color code. Returns passthrough if color is
+ * empty.
+ */
+const makeStyleFn = (color) => {
+    if (!color) {
+        return (text) => text;
+    }
+    return (text) => `${color}${text}${RESET}`;
+};
+/**
+ * Create a Styler from a Theme. If the theme has missing colors, they fall back
+ * to the default theme.
+ */
+export const createStyler = (theme) => {
+    const resolved = getTheme(theme);
+    return {
+        command: makeStyleFn(resolved.colors.command),
+        defaultText: makeStyleFn(resolved.colors.defaultText),
+        defaultValue: makeStyleFn(resolved.colors.defaultValue),
+        description: makeStyleFn(resolved.colors.description),
+        epilog: makeStyleFn(resolved.colors.epilog),
+        example: makeStyleFn(resolved.colors.example),
+        flag: makeStyleFn(resolved.colors.flag),
+        positional: makeStyleFn(resolved.colors.positional),
+        scriptName: makeStyleFn(resolved.colors.scriptName),
+        sectionHeader: makeStyleFn(resolved.colors.sectionHeader),
+        type: makeStyleFn(resolved.colors.type),
+        url: makeStyleFn(resolved.colors.url),
+        usage: makeStyleFn(resolved.colors.usage),
+    };
+};
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"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"}

package/dist/types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * TypeScript type definitions for the bargs CLI argument parser.
+ *
+ * Defines all public interfaces and types including:
+ *
+ * - Option definitions (`StringOption`, `BooleanOption`, `EnumOption`, etc.)
+ * - Positional definitions (`StringPositional`, `VariadicPositional`, etc.)
+ * - Schema types (`OptionsSchema`, `PositionalsSchema`)
+ * - Configuration types (`BargsConfig`, `BargsConfigWithCommands`)
+ * - Command types (`CommandConfig`, `CommandConfigInput`)
+ * - Type inference utilities (`InferOptions`, `InferPositionals`)
+ * - Result types (`BargsResult`)
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map