@boneskull/bargs 0.1.1

package/dist/parser.js

@@ -0,0 +1,285 @@
+/**
+ * Low-level argument parsing logic wrapping Node.js `util.parseArgs()`.
+ *
+ * Handles the transformation of CLI arguments into typed values by:
+ *
+ * - Building `parseArgs` configuration from bargs option schemas
+ * - Coercing parsed string values to their declared types (number, enum, etc.)
+ * - Processing positional arguments including variadic rest args
+ * - Running handler functions (sync or async) after successful parsing
+ * - Supporting both simple CLIs and command-based CLIs with subcommand dispatch
+ *
+ * @packageDocumentation
+ */
+import { parseArgs } from 'node:util';
+import { BargsError, HelpError } from "./errors.js";
+/**
+ * Check if a value is a thenable (Promise-like). Uses duck-typing for
+ * cross-realm compatibility.
+ */
+const isThenable = (value) => value !== null &&
+    typeof value === 'object' &&
+    typeof value.then === 'function';
+/**
+ * Run a handler or array of handlers synchronously. Throws if any handler
+ * returns a thenable.
+ */
+export const runSyncHandlers = (handler, result) => {
+    const handlers = Array.isArray(handler) ? handler : [handler];
+    for (const h of handlers) {
+        const maybePromise = h(result);
+        if (isThenable(maybePromise)) {
+            throw new BargsError('Handler returned a thenable. Use bargsAsync() for async handlers.');
+        }
+    }
+};
+/**
+ * Run a handler or array of handlers sequentially (async).
+ */
+export const runHandlers = async (handler, result) => {
+    const handlers = Array.isArray(handler) ? handler : [handler];
+    for (const h of handlers) {
+        await h(result);
+    }
+};
+/**
+ * Build parseArgs options config from our options schema.
+ */
+const buildParseArgsConfig = (schema) => {
+    const config = {};
+    for (const [name, def] of Object.entries(schema)) {
+        const opt = {
+            type: def.type === 'boolean' ? 'boolean' : 'string',
+        };
+        // First single-char alias becomes short option
+        const shortAlias = def.aliases?.find((a) => a.length === 1);
+        if (shortAlias) {
+            opt.short = shortAlias;
+        }
+        // Arrays need multiple: true
+        if (def.type === 'array') {
+            opt.multiple = true;
+        }
+        config[name] = opt;
+    }
+    return config;
+};
+/**
+ * Coerce parsed values to their expected types.
+ */
+const coerceValues = (values, schema) => {
+    const result = {};
+    for (const [name, def] of Object.entries(schema)) {
+        let value = values[name];
+        // Apply default if undefined
+        if (value === undefined && 'default' in def) {
+            value = def.default;
+        }
+        // Type coercion
+        if (value !== undefined) {
+            switch (def.type) {
+                case 'array':
+                    if (def.items === 'number' && Array.isArray(value)) {
+                        result[name] = value.map((v) => (typeof v === 'string' ? Number(v) : v));
+                    }
+                    else {
+                        result[name] = value;
+                    }
+                    break;
+                case 'count':
+                    // Count options count occurrences
+                    result[name] = typeof value === 'number' ? value : value ? 1 : 0;
+                    break;
+                case 'enum': {
+                    const enumValue = value;
+                    if (value !== undefined && !def.choices.includes(enumValue)) {
+                        throw new Error(`Invalid value for --${name}: "${enumValue}". Must be one of: ${def.choices.join(', ')}`);
+                    }
+                    result[name] = value;
+                    break;
+                }
+                case 'number':
+                    result[name] = typeof value === 'string' ? Number(value) : value;
+                    break;
+                default:
+                    result[name] = value;
+            }
+        }
+        else {
+            result[name] = value;
+        }
+    }
+    return result;
+};
+/**
+ * Coerce positional values.
+ *
+ * Note: Schema validation (variadic last, required order) is done upfront by
+ * validateConfig in bargs.ts.
+ */
+const coercePositionals = (positionals, schema) => {
+    const result = [];
+    for (let i = 0; i < schema.length; i++) {
+        const def = schema[i];
+        const value = positionals[i];
+        if (def.type === 'variadic') {
+            // Rest of positionals - def is narrowed to VariadicPositional here
+            const variadicDef = def;
+            const rest = positionals.slice(i);
+            if (variadicDef.items === 'number') {
+                result.push(rest.map(Number));
+            }
+            else {
+                result.push(rest);
+            }
+            break;
+        }
+        if (value !== undefined) {
+            if (def.type === 'number') {
+                result.push(Number(value));
+            }
+            else if (def.type === 'enum') {
+                // Validate enum choice
+                if (!def.choices.includes(value)) {
+                    throw new Error(`Invalid value for positional ${i}: "${value}". Must be one of: ${def.choices.join(', ')}`);
+                }
+                result.push(value);
+            }
+            else {
+                result.push(value);
+            }
+        }
+        else if ('default' in def && def.default !== undefined) {
+            result.push(def.default);
+        }
+        else if (def.required) {
+            throw new Error(`Missing required positional argument at position ${i}`);
+        }
+        else {
+            result.push(undefined);
+        }
+    }
+    return result;
+};
+/**
+ * Parse arguments for a simple CLI (no commands). This is synchronous - it only
+ * parses, does not run handlers.
+ */
+export const parseSimple = (config) => {
+    const { args = process.argv.slice(2), options: optionsSchema = {}, positionals: positionalsSchema = [], } = config;
+    // Build parseArgs config
+    const parseArgsOptions = buildParseArgsConfig(optionsSchema);
+    // Parse with Node.js util.parseArgs
+    const { positionals, values } = parseArgs({
+        allowPositionals: positionalsSchema.length > 0,
+        args,
+        options: parseArgsOptions,
+        strict: true,
+    });
+    // Coerce and apply defaults
+    const coercedValues = coerceValues(values, optionsSchema);
+    const coercedPositionals = coercePositionals(positionals, positionalsSchema);
+    return {
+        command: undefined,
+        positionals: coercedPositionals,
+        values: coercedValues,
+    };
+};
+/**
+ * Core command parsing logic (sync, no handler execution). Returns the parsed
+ * result and the handler to run.
+ */
+const parseCommandsCore = (config) => {
+    const { args = process.argv.slice(2), commands, defaultHandler, options: globalOptions = {}, } = config;
+    const commandsRecord = commands;
+    // Find command name (first non-flag argument)
+    const commandIndex = args.findIndex((arg) => !arg.startsWith('-'));
+    const commandName = commandIndex >= 0 ? args[commandIndex] : undefined;
+    const remainingArgs = commandName
+        ? [...args.slice(0, commandIndex), ...args.slice(commandIndex + 1)]
+        : args;
+    // No command specified
+    if (!commandName) {
+        if (typeof defaultHandler === 'string') {
+            // Use named default command (recursive)
+            return parseCommandsCore({
+                ...config,
+                args: [defaultHandler, ...args],
+                defaultHandler: undefined,
+            });
+        }
+        else if (typeof defaultHandler === 'function' ||
+            Array.isArray(defaultHandler)) {
+            // Parse global options only
+            const parseArgsOptions = buildParseArgsConfig(globalOptions);
+            const { values } = parseArgs({
+                allowPositionals: false,
+                args: remainingArgs,
+                options: parseArgsOptions,
+                strict: true,
+            });
+            const coercedValues = coerceValues(values, globalOptions);
+            const result = {
+                command: undefined,
+                positionals: [],
+                values: coercedValues,
+            };
+            return {
+                handler: defaultHandler,
+                result,
+            };
+        }
+        else {
+            throw new HelpError('No command specified.');
+        }
+    }
+    // Find command config
+    const command = commandsRecord[commandName];
+    if (!command) {
+        throw new HelpError(`Unknown command: ${commandName}`);
+    }
+    // Merge global and command options
+    const commandOptions = command.options ?? {};
+    const mergedOptionsSchema = { ...globalOptions, ...commandOptions };
+    const commandPositionals = command.positionals ?? [];
+    // Build parseArgs config
+    const parseArgsOptions = buildParseArgsConfig(mergedOptionsSchema);
+    // Parse
+    const { positionals, values } = parseArgs({
+        allowPositionals: commandPositionals.length > 0,
+        args: remainingArgs,
+        options: parseArgsOptions,
+        strict: true,
+    });
+    // Coerce
+    const coercedValues = coerceValues(values, mergedOptionsSchema);
+    const coercedPositionals = coercePositionals(positionals, commandPositionals);
+    const result = {
+        command: commandName,
+        positionals: coercedPositionals,
+        values: coercedValues,
+    };
+    return { handler: command.handler, result };
+};
+/**
+ * Parse arguments for a command-based CLI (sync). Throws if any handler returns
+ * a thenable.
+ */
+export const parseCommandsSync = (config) => {
+    const { handler, result } = parseCommandsCore(config);
+    if (handler) {
+        runSyncHandlers(handler, result);
+    }
+    return result;
+};
+/**
+ * Parse arguments for a command-based CLI (async).
+ */
+export const parseCommandsAsync = async (config) => {
+    const { handler, result } = parseCommandsCore(config);
+    if (handler) {
+        await runHandlers(handler, result);
+    }
+    return result;
+};
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

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

package/dist/theme.cjs

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStyler = exports.getTheme = exports.defaultTheme = exports.themes = exports.ansi = exports.stripAnsi = void 0;
+const node_util_1 = require("node:util");
+/**
+ * Strip all ANSI escape codes from a string.
+ */
+exports.stripAnsi = node_util_1.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.
+ */
+exports.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: exports.ansi.bold,
+    defaultText: exports.ansi.dim,
+    defaultValue: exports.ansi.white,
+    description: exports.ansi.white,
+    epilog: exports.ansi.dim,
+    example: exports.ansi.white + exports.ansi.dim,
+    flag: exports.ansi.brightCyan,
+    positional: exports.ansi.magenta,
+    scriptName: exports.ansi.bold,
+    sectionHeader: exports.ansi.brightMagenta,
+    type: exports.ansi.magenta,
+    url: exports.ansi.cyan,
+    usage: exports.ansi.cyan,
+};
+/**
+ * Built-in themes.
+ */
+exports.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: exports.ansi.bold + exports.ansi.brightCyan,
+            defaultText: exports.ansi.blue,
+            defaultValue: exports.ansi.green,
+            description: exports.ansi.white,
+            epilog: exports.ansi.blue,
+            example: exports.ansi.dim + exports.ansi.white,
+            flag: exports.ansi.brightCyan,
+            positional: exports.ansi.brightGreen,
+            scriptName: exports.ansi.bold + exports.ansi.brightBlue,
+            sectionHeader: exports.ansi.brightBlue,
+            type: exports.ansi.cyan,
+            url: exports.ansi.brightCyan,
+            usage: exports.ansi.white,
+        },
+    },
+    /** Warm theme - reds and yellows */
+    warm: {
+        colors: {
+            command: exports.ansi.bold + exports.ansi.yellow,
+            defaultText: exports.ansi.dim + exports.ansi.yellow,
+            defaultValue: exports.ansi.brightYellow,
+            description: exports.ansi.white,
+            epilog: exports.ansi.dim + exports.ansi.yellow,
+            example: exports.ansi.white + exports.ansi.dim,
+            flag: exports.ansi.brightYellow,
+            positional: exports.ansi.brightRed,
+            scriptName: exports.ansi.bold + exports.ansi.red,
+            sectionHeader: exports.ansi.red,
+            type: exports.ansi.yellow,
+            url: exports.ansi.brightYellow,
+            usage: exports.ansi.white,
+        },
+    },
+};
+/**
+ * Default theme export for convenience.
+ */
+exports.defaultTheme = exports.themes.default;
+/**
+ * Resolve a theme input to a fully resolved Theme with all colors defined.
+ * Missing colors fall back to the default theme.
+ */
+const getTheme = (input) => {
+    if (typeof input === 'string') {
+        return exports.themes[input];
+    }
+    // Merge with defaults for partial themes
+    return {
+        colors: { ...defaultColors, ...input.colors },
+    };
+};
+exports.getTheme = getTheme;
+/**
+ * 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.
+ */
+const createStyler = (theme) => {
+    const resolved = (0, exports.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),
+    };
+};
+exports.createStyler = createStyler;
+//# sourceMappingURL=theme.js.map

package/dist/theme.cjs.map

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