@boneskull/bargs 0.1.1

package/dist/help.cjs

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * Help text generation for CLI applications.
+ *
+ * Generates formatted, colorized help output for both simple CLIs and
+ * command-based CLIs. Supports customizable themes, automatic URL linkification
+ * in terminals that support hyperlinks, option grouping, and automatic epilog
+ * generation from `package.json` metadata.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCommandHelp = exports.generateHelp = void 0;
+const osc_js_1 = require("./osc.cjs");
+const theme_js_1 = require("./theme.cjs");
+const version_js_1 = require("./version.cjs");
+/**
+ * URL regex pattern for matching URLs in text.
+ */
+const URL_PATTERN = /https?:\/\/[^\s<>"\])}]+/g;
+/**
+ * Linkify URLs in text if terminal supports hyperlinks. Applies URL styling.
+ */
+const linkifyText = (text, styler, stream = process.stdout) => {
+    const canLink = (0, osc_js_1.supportsHyperlinks)(stream);
+    return text.replace(URL_PATTERN, (url) => {
+        const styledUrl = styler.url(url);
+        return canLink ? (0, osc_js_1.link)(styledUrl, url) : styledUrl;
+    });
+};
+/**
+ * Generate default epilog from package.json (homepage and repository).
+ */
+const generateDefaultEpilog = (styler) => {
+    const pkgInfo = (0, version_js_1.readPackageInfoSync)();
+    const lines = [];
+    if (pkgInfo.homepage) {
+        const styledUrl = styler.url(pkgInfo.homepage);
+        const linkedUrl = (0, osc_js_1.supportsHyperlinks)()
+            ? (0, osc_js_1.link)(styledUrl, pkgInfo.homepage)
+            : styledUrl;
+        lines.push(styler.epilog(`Homepage: ${linkedUrl}`));
+    }
+    if (pkgInfo.repository) {
+        const styledUrl = styler.url(pkgInfo.repository);
+        const linkedUrl = (0, osc_js_1.supportsHyperlinks)()
+            ? (0, osc_js_1.link)(styledUrl, pkgInfo.repository)
+            : styledUrl;
+        lines.push(styler.epilog(`Repository: ${linkedUrl}`));
+    }
+    return lines;
+};
+/**
+ * Format epilog based on config. Returns empty array if epilog is disabled,
+ * custom epilog lines if provided, or default epilog from package.json.
+ */
+const formatEpilog = (config, styler) => {
+    // Explicitly disabled
+    if (config.epilog === false || config.epilog === '') {
+        return [];
+    }
+    // Custom epilog provided
+    if (typeof config.epilog === 'string') {
+        const linkified = linkifyText(config.epilog, styler);
+        return [styler.epilog(linkified)];
+    }
+    // Default: generate from package.json
+    return generateDefaultEpilog(styler);
+};
+/**
+ * Format a single positional for help usage line. Required positionals use
+ * <name>, optional use [name]. Variadic positionals append "...".
+ */
+const formatPositionalUsage = (def, index) => {
+    const name = def.name ?? `arg${index}`;
+    const isRequired = def.required || 'default' in def;
+    const isVariadic = def.type === 'variadic';
+    const displayName = isVariadic ? `${name}...` : name;
+    return isRequired ? `<${displayName}>` : `[${displayName}]`;
+};
+/**
+ * Build the positionals usage string from a schema.
+ */
+const buildPositionalsUsage = (schema) => {
+    if (!schema || schema.length === 0) {
+        return '';
+    }
+    return schema
+        .map((def, index) => formatPositionalUsage(def, index))
+        .join(' ');
+};
+/**
+ * Get type label for help display.
+ */
+const getTypeLabel = (def) => {
+    switch (def.type) {
+        case 'array':
+            return `${def.items}[]`;
+        case 'boolean':
+            return 'boolean';
+        case 'count':
+            return 'count';
+        case 'enum':
+            return def.choices.join(' | ');
+        case 'number':
+            return 'number';
+        case 'string':
+            return 'string';
+        default:
+            return 'string';
+    }
+};
+/**
+ * Format a single option for help output.
+ */
+const formatOptionHelp = (name, def, styler) => {
+    const parts = [];
+    // Build flag string: -v, --verbose
+    const shortAlias = def.aliases?.find((a) => a.length === 1);
+    const flagText = shortAlias ? `-${shortAlias}, --${name}` : `    --${name}`;
+    parts.push(`  ${styler.flag(flagText)}`);
+    // Pad to align descriptions
+    const padding = Math.max(0, 24 - flagText.length - 2);
+    parts.push(' '.repeat(padding));
+    // Description
+    if (def.description) {
+        parts.push(styler.description(def.description));
+    }
+    // Type and default
+    const typeLabel = getTypeLabel(def);
+    const suffixParts = [styler.type(`[${typeLabel}]`)];
+    if ('default' in def && def.default !== undefined) {
+        suffixParts.push(`${styler.defaultText('default:')} ${styler.defaultValue(JSON.stringify(def.default))}`);
+    }
+    parts.push('  ', suffixParts.join(' '));
+    return parts.join('');
+};
+/**
+ * Check if config has commands.
+ */
+const hasCommands = (config) => config.commands !== undefined && Object.keys(config.commands).length > 0;
+/**
+ * Generate help text for a bargs config.
+ */
+const generateHelp = (config, theme = theme_js_1.defaultTheme) => {
+    const styler = (0, theme_js_1.createStyler)(theme);
+    const lines = [];
+    // Header
+    const version = config.version ? ` v${config.version}` : '';
+    lines.push('');
+    lines.push(`${styler.scriptName(config.name)}${styler.defaultValue(version)}`);
+    if (config.description) {
+        const linkifiedDesc = linkifyText(config.description, styler);
+        lines.push(`  ${styler.description(linkifiedDesc)}`);
+    }
+    lines.push('');
+    // Build positional names for usage line
+    const posNames = [];
+    if (config.positionals && config.positionals.length > 0) {
+        for (let i = 0; i < config.positionals.length; i++) {
+            const pos = config.positionals[i];
+            const formatted = formatPositionalUsage(pos, i);
+            posNames.push(styler.positional(formatted));
+        }
+    }
+    // Usage
+    lines.push(styler.sectionHeader('USAGE'));
+    if (hasCommands(config)) {
+        const posStr = posNames.length > 0 ? ` ${posNames.join(' ')}` : '';
+        lines.push(styler.usage(`  $ ${config.name} <command> [options]${posStr}`));
+    }
+    else {
+        const posStr = posNames.length > 0 ? ` ${posNames.join(' ')}` : '';
+        lines.push(styler.usage(`  $ ${config.name} [options]${posStr}`));
+    }
+    lines.push('');
+    // Commands
+    if (hasCommands(config)) {
+        lines.push(styler.sectionHeader('COMMANDS'));
+        for (const [name, cmd] of Object.entries(config.commands)) {
+            const padding = Math.max(0, 14 - name.length);
+            lines.push(`  ${styler.command(name)}${' '.repeat(padding)}${styler.description(cmd.description)}`);
+        }
+        lines.push('');
+    }
+    // Options
+    if (config.options && Object.keys(config.options).length > 0) {
+        // Group options
+        const groups = new Map();
+        const ungrouped = [];
+        for (const [name, def] of Object.entries(config.options)) {
+            if (def.hidden) {
+                continue;
+            }
+            if (def.group) {
+                const group = groups.get(def.group) ?? [];
+                group.push({ def, name });
+                groups.set(def.group, group);
+            }
+            else {
+                ungrouped.push({ def, name });
+            }
+        }
+        // Print grouped options
+        for (const [groupName, options] of Array.from(groups.entries())) {
+            lines.push(styler.sectionHeader(groupName.toUpperCase()));
+            for (const opt of options) {
+                lines.push(formatOptionHelp(opt.name, opt.def, styler));
+            }
+            lines.push('');
+        }
+        // Print ungrouped
+        if (ungrouped.length > 0) {
+            const label = hasCommands(config) ? 'GLOBAL OPTIONS' : 'OPTIONS';
+            lines.push(styler.sectionHeader(label));
+            for (const opt of ungrouped) {
+                lines.push(formatOptionHelp(opt.name, opt.def, styler));
+            }
+            lines.push('');
+        }
+    }
+    // Positionals
+    if (config.positionals && config.positionals.length > 0) {
+        lines.push(styler.sectionHeader('POSITIONALS'));
+        for (let i = 0; i < config.positionals.length; i++) {
+            const pos = config.positionals[i];
+            const name = pos.name ?? `arg${i}`;
+            const formatted = pos.required ? `<${name}>` : `[${name}]`;
+            const padding = Math.max(0, 20 - formatted.length);
+            const desc = pos.description ?? '';
+            lines.push(`  ${styler.positional(formatted)}${' '.repeat(padding)}${styler.description(desc)}`);
+        }
+        lines.push('');
+    }
+    // Footer
+    if (hasCommands(config)) {
+        lines.push(styler.example(`Run '${config.name} <command> --help' for command-specific help.`));
+        lines.push('');
+    }
+    // Epilog
+    const epilogLines = formatEpilog(config, styler);
+    if (epilogLines.length > 0) {
+        lines.push(...epilogLines);
+        lines.push('');
+    }
+    return lines.join('\n');
+};
+exports.generateHelp = generateHelp;
+/**
+ * Generate help text for a specific command.
+ */
+const generateCommandHelp = (config, commandName, theme = theme_js_1.defaultTheme) => {
+    const styler = (0, theme_js_1.createStyler)(theme);
+    const commandsRecord = config.commands;
+    const command = commandsRecord[commandName];
+    if (!command) {
+        return `Unknown command: ${commandName}`;
+    }
+    const lines = [];
+    // Header
+    lines.push('');
+    lines.push(`  ${styler.scriptName(config.name)} ${styler.command(commandName)}`);
+    const linkifiedDesc = linkifyText(command.description, styler);
+    lines.push(`  ${styler.description(linkifiedDesc)}`);
+    lines.push('');
+    // Usage
+    lines.push(styler.sectionHeader('USAGE'));
+    const positionalsPart = buildPositionalsUsage(command.positionals);
+    const usageParts = [
+        `$ ${config.name} ${commandName}`,
+        '[options]',
+        positionalsPart,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    lines.push(styler.usage(`  ${usageParts}`));
+    lines.push('');
+    // Command options
+    if (command.options && Object.keys(command.options).length > 0) {
+        lines.push(styler.sectionHeader('OPTIONS'));
+        for (const [name, def] of Object.entries(command.options)) {
+            if (def.hidden) {
+                continue;
+            }
+            lines.push(formatOptionHelp(name, def, styler));
+        }
+        lines.push('');
+    }
+    // Global options
+    if (config.options && Object.keys(config.options).length > 0) {
+        lines.push(styler.sectionHeader('GLOBAL OPTIONS'));
+        for (const [name, def] of Object.entries(config.options)) {
+            if (def.hidden) {
+                continue;
+            }
+            lines.push(formatOptionHelp(name, def, styler));
+        }
+        lines.push('');
+    }
+    // Epilog
+    const epilogLines = formatEpilog(config, styler);
+    if (epilogLines.length > 0) {
+        lines.push(...epilogLines);
+        lines.push('');
+    }
+    return lines.join('\n');
+};
+exports.generateCommandHelp = generateCommandHelp;
+//# sourceMappingURL=help.js.map

package/dist/help.cjs.map

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

package/dist/help.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Help text generation for CLI applications.
+ *
+ * Generates formatted, colorized help output for both simple CLIs and
+ * command-based CLIs. Supports customizable themes, automatic URL linkification
+ * in terminals that support hyperlinks, option grouping, and automatic epilog
+ * generation from `package.json` metadata.
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfig, BargsConfigWithCommands, CommandConfigInput, OptionsSchema, PositionalsSchema } from "./types.cjs";
+import { type Theme } from "./theme.cjs";
+/**
+ * Generate help text for a bargs config.
+ */
+export declare const generateHelp: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TCommands extends Record<string, CommandConfigInput> | undefined = undefined>(config: BargsConfig<TOptions, TPositionals, TCommands>, theme?: Theme) => string;
+/**
+ * Generate help text for a specific command.
+ */
+export declare const generateCommandHelp: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, commandName: string, theme?: Theme) => string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAElB,aAAa,EAEb,iBAAiB,EAClB,oBAAmB;AAGpB,OAAO,EAIL,KAAK,KAAK,EACX,oBAAmB;AAyKpB;;GAEG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB,EAC1D,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,SAAS,GAAG,SAAS,EAE5E,QAAQ,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,QAAO,KAAoB,KAC1B,MA2HF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,aAAa,MAAM,EACnB,QAAO,KAAoB,KAC1B,MAgEF,CAAC"}

package/dist/help.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Help text generation for CLI applications.
+ *
+ * Generates formatted, colorized help output for both simple CLIs and
+ * command-based CLIs. Supports customizable themes, automatic URL linkification
+ * in terminals that support hyperlinks, option grouping, and automatic epilog
+ * generation from `package.json` metadata.
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfig, BargsConfigWithCommands, CommandConfigInput, OptionsSchema, PositionalsSchema } from "./types.js";
+import { type Theme } from "./theme.js";
+/**
+ * Generate help text for a bargs config.
+ */
+export declare const generateHelp: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TCommands extends Record<string, CommandConfigInput> | undefined = undefined>(config: BargsConfig<TOptions, TPositionals, TCommands>, theme?: Theme) => string;
+/**
+ * Generate help text for a specific command.
+ */
+export declare const generateCommandHelp: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, commandName: string, theme?: Theme) => string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAElB,aAAa,EAEb,iBAAiB,EAClB,mBAAmB;AAGpB,OAAO,EAIL,KAAK,KAAK,EACX,mBAAmB;AAyKpB;;GAEG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB,EAC1D,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,SAAS,GAAG,SAAS,EAE5E,QAAQ,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,QAAO,KAAoB,KAC1B,MA2HF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,aAAa,MAAM,EACnB,QAAO,KAAoB,KAC1B,MAgEF,CAAC"}