burgee 0.0.0 → 0.2.0

package/dist/commander-error.d.ts

@@ -0,0 +1,10 @@
+/** commander's error classes, byte-for-byte in shape: `code`, `exitCode`, `nestedError`. */
+export declare class CommanderError extends Error {
+    code: string;
+    exitCode: number;
+    nestedError: unknown;
+    constructor(exitCode: number, code: string, message?: string);
+}
+export declare class InvalidArgumentError extends CommanderError {
+    constructor(message?: string);
+}

package/dist/commander-error.js

@@ -0,0 +1,20 @@
+export class CommanderError extends Error {
+    code;
+    exitCode;
+    nestedError;
+    constructor(exitCode, code, message) {
+        super(message);
+        Error.captureStackTrace(this, this.constructor);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.exitCode = exitCode;
+        this.nestedError = undefined;
+    }
+}
+export class InvalidArgumentError extends CommanderError {
+    constructor(message) {
+        super(1, 'commander.invalidArgument', message);
+        Error.captureStackTrace(this, this.constructor);
+        this.name = this.constructor.name;
+    }
+}

package/dist/commander-help.d.ts

@@ -0,0 +1,67 @@
+import { type Argument } from './commander-argument.js';
+import type { Command } from './commander-command.js';
+import type { Option } from './commander-option.js';
+export interface HelpContext {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+}
+/** Methods are static in style so a subclass, or plain functions via `configureHelp`, can override them. */
+export declare class Help {
+    helpWidth: number | undefined;
+    minWidthToWrap: number;
+    sortSubcommands: boolean;
+    sortOptions: boolean;
+    showGlobalOptions: boolean;
+    /** Called after `configureHelp` overrides are applied and just before `formatHelp`. */
+    prepareContext(contextOptions: HelpContext): void;
+    visibleCommands(cmd: Command): Command[];
+    compareOptions(a: Option, b: Option): number;
+    visibleOptions(cmd: Command): Option[];
+    visibleGlobalOptions(cmd: Command): Option[];
+    visibleArguments(cmd: Command): Argument[];
+    subcommandTerm(cmd: Command): string;
+    optionTerm(option: Option): string;
+    argumentTerm(argument: Argument): string;
+    longestSubcommandTermLength(cmd: Command, helper: Help): number;
+    longestOptionTermLength(cmd: Command, helper: Help): number;
+    longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
+    longestArgumentTermLength(cmd: Command, helper: Help): number;
+    commandUsage(cmd: Command): string;
+    commandDescription(cmd: Command): string;
+    /** Summary, falling back to description for backwards compatibility. */
+    subcommandDescription(cmd: Command): string;
+    optionDescription(option: Option): string;
+    argumentDescription(argument: Argument): string;
+    formatItemList(heading: string, items: string[], helper: Help): string[];
+    /** Groups in order of first appearance among all items; members in order of the visible items. */
+    groupItems<T>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
+    formatHelp(cmd: Command, helper: Help): string;
+    /** Width ignoring ANSI escapes, for padding and wrapping. */
+    displayWidth(str: string): number;
+    styleTitle(str: string): string;
+    styleUsage(str: string): string;
+    styleCommandDescription(str: string): string;
+    styleOptionDescription(str: string): string;
+    styleSubcommandDescription(str: string): string;
+    styleArgumentDescription(str: string): string;
+    styleDescriptionText(str: string): string;
+    styleOptionTerm(str: string): string;
+    styleSubcommandTerm(str: string): string;
+    styleArgumentTerm(str: string): string;
+    styleOptionText(str: string): string;
+    styleArgumentText(str: string): string;
+    styleSubcommandText(str: string): string;
+    styleCommandText(str: string): string;
+    padWidth(cmd: Command, helper: Help): number;
+    /** Manually wrapped text: a line break followed by whitespace. */
+    preformatted(str: string): boolean;
+    /**
+     * Pad the term and wrap the description, indenting the following lines:
+     *   TTT  DDD DDDD
+     *        DD DDD
+     */
+    formatItem(term: string, termWidth: number, description: string, helper: Help): string;
+    /** Wrap at whitespace, preserving existing line breaks; skipped below `minWidthToWrap`. */
+    boxWrap(str: string, width: number): string;
+}

package/dist/commander-help.js

@@ -0,0 +1,319 @@
+import { stripVTControlCharacters } from 'node:util';
+import { humanReadableArgName } from './commander-argument.js';
+export class Help {
+    helpWidth = undefined;
+    minWidthToWrap = 40;
+    sortSubcommands = false;
+    sortOptions = false;
+    showGlobalOptions = false;
+    prepareContext(contextOptions) {
+        this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
+    }
+    visibleCommands(cmd) {
+        const visibleCommands = cmd.commands.filter((sub) => !sub._hidden);
+        const helpCommand = cmd._getHelpCommand();
+        if (helpCommand && !helpCommand._hidden)
+            visibleCommands.push(helpCommand);
+        if (this.sortSubcommands)
+            visibleCommands.sort((a, b) => a.name().localeCompare(b.name()));
+        return visibleCommands;
+    }
+    compareOptions(a, b) {
+        const getSortKey = (option) => option.short ? option.short.replace(/^-/, '') : (option.long ?? '').replace(/^--/, '');
+        return getSortKey(a).localeCompare(getSortKey(b));
+    }
+    visibleOptions(cmd) {
+        const visibleOptions = cmd.options.filter((option) => !option.hidden);
+        const helpOption = cmd._getHelpOption();
+        if (helpOption && !helpOption.hidden) {
+            const removeShort = helpOption.short && cmd._findOption(helpOption.short);
+            const removeLong = helpOption.long && cmd._findOption(helpOption.long);
+            if (!removeShort && !removeLong)
+                visibleOptions.push(helpOption);
+            else if (helpOption.long && !removeLong)
+                visibleOptions.push(cmd.createOption(helpOption.long, helpOption.description));
+            else if (helpOption.short && !removeShort)
+                visibleOptions.push(cmd.createOption(helpOption.short, helpOption.description));
+        }
+        if (this.sortOptions)
+            visibleOptions.sort(this.compareOptions);
+        return visibleOptions;
+    }
+    visibleGlobalOptions(cmd) {
+        if (!this.showGlobalOptions)
+            return [];
+        const globalOptions = [];
+        for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+            globalOptions.push(...ancestorCmd.options.filter((option) => !option.hidden));
+        }
+        if (this.sortOptions)
+            globalOptions.sort(this.compareOptions);
+        return globalOptions;
+    }
+    visibleArguments(cmd) {
+        if (cmd._argsDescription) {
+            for (const argument of cmd.registeredArguments) {
+                argument.description = argument.description || cmd._argsDescription[argument.name()] || '';
+            }
+        }
+        if (cmd.registeredArguments.find((argument) => argument.description))
+            return cmd.registeredArguments;
+        return [];
+    }
+    subcommandTerm(cmd) {
+        const args = cmd.registeredArguments.map((arg) => humanReadableArgName(arg)).join(' ');
+        return (cmd._name +
+            (cmd._aliases[0] ? `|${cmd._aliases[0]}` : '') +
+            (cmd.options.length ? ' [options]' : '') +
+            (args ? ` ${args}` : ''));
+    }
+    optionTerm(option) {
+        return option.flags;
+    }
+    argumentTerm(argument) {
+        return argument.name();
+    }
+    longestSubcommandTermLength(cmd, helper) {
+        return helper
+            .visibleCommands(cmd)
+            .reduce((max, command) => Math.max(max, this.displayWidth(helper.styleSubcommandTerm(helper.subcommandTerm(command)))), 0);
+    }
+    longestOptionTermLength(cmd, helper) {
+        return helper
+            .visibleOptions(cmd)
+            .reduce((max, option) => Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option)))), 0);
+    }
+    longestGlobalOptionTermLength(cmd, helper) {
+        return helper
+            .visibleGlobalOptions(cmd)
+            .reduce((max, option) => Math.max(max, this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option)))), 0);
+    }
+    longestArgumentTermLength(cmd, helper) {
+        return helper
+            .visibleArguments(cmd)
+            .reduce((max, argument) => Math.max(max, this.displayWidth(helper.styleArgumentTerm(helper.argumentTerm(argument)))), 0);
+    }
+    commandUsage(cmd) {
+        let cmdName = cmd._name;
+        if (cmd._aliases[0])
+            cmdName = `${cmdName}|${cmd._aliases[0]}`;
+        let ancestorCmdNames = '';
+        for (let ancestorCmd = cmd.parent; ancestorCmd; ancestorCmd = ancestorCmd.parent) {
+            ancestorCmdNames = `${ancestorCmd.name()} ${ancestorCmdNames}`;
+        }
+        return `${ancestorCmdNames}${cmdName} ${cmd.usage()}`;
+    }
+    commandDescription(cmd) {
+        return cmd.description();
+    }
+    subcommandDescription(cmd) {
+        return cmd.summary() || cmd.description();
+    }
+    optionDescription(option) {
+        const extraInfo = [];
+        if (option.argChoices) {
+            extraInfo.push(`choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
+        }
+        if (option.defaultValue !== undefined) {
+            const showDefault = option.required || option.optional || (option.isBoolean() && typeof option.defaultValue === 'boolean');
+            if (showDefault)
+                extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
+        }
+        if (option.presetArg !== undefined && option.optional)
+            extraInfo.push(`preset: ${JSON.stringify(option.presetArg)}`);
+        if (option.envVar !== undefined)
+            extraInfo.push(`env: ${option.envVar}`);
+        if (extraInfo.length > 0) {
+            const extraDescription = `(${extraInfo.join(', ')})`;
+            return option.description ? `${option.description} ${extraDescription}` : extraDescription;
+        }
+        return option.description;
+    }
+    argumentDescription(argument) {
+        const extraInfo = [];
+        if (argument.argChoices) {
+            extraInfo.push(`choices: ${argument.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
+        }
+        if (argument.defaultValue !== undefined) {
+            extraInfo.push(`default: ${argument.defaultValueDescription || JSON.stringify(argument.defaultValue)}`);
+        }
+        if (extraInfo.length > 0) {
+            const extraDescription = `(${extraInfo.join(', ')})`;
+            return argument.description ? `${argument.description} ${extraDescription}` : extraDescription;
+        }
+        return argument.description;
+    }
+    formatItemList(heading, items, helper) {
+        if (items.length === 0)
+            return [];
+        return [helper.styleTitle(heading), ...items, ''];
+    }
+    groupItems(unsortedItems, visibleItems, getGroup) {
+        const result = new Map();
+        for (const item of unsortedItems) {
+            const group = getGroup(item);
+            if (!result.has(group))
+                result.set(group, []);
+        }
+        for (const item of visibleItems) {
+            const group = getGroup(item);
+            const members = result.get(group);
+            if (members === undefined)
+                result.set(group, [item]);
+            else
+                members.push(item);
+        }
+        return result;
+    }
+    formatHelp(cmd, helper) {
+        const termWidth = helper.padWidth(cmd, helper);
+        const helpWidth = helper.helpWidth ?? 80;
+        const callFormatItem = (term, description) => helper.formatItem(term, termWidth, description, helper);
+        let output = [`${helper.styleTitle('Usage:')} ${helper.styleUsage(helper.commandUsage(cmd))}`, ''];
+        const commandDescription = helper.commandDescription(cmd);
+        if (commandDescription.length > 0) {
+            output = output.concat([helper.boxWrap(helper.styleCommandDescription(commandDescription), helpWidth), '']);
+        }
+        const argumentList = helper
+            .visibleArguments(cmd)
+            .map((argument) => callFormatItem(helper.styleArgumentTerm(helper.argumentTerm(argument)), helper.styleArgumentDescription(helper.argumentDescription(argument))));
+        output = output.concat(this.formatItemList('Arguments:', argumentList, helper));
+        const optionGroups = this.groupItems(cmd.options, helper.visibleOptions(cmd), (option) => option.helpGroupHeading ?? 'Options:');
+        for (const [group, options] of optionGroups) {
+            const optionList = options.map((option) => callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option))));
+            output = output.concat(this.formatItemList(group, optionList, helper));
+        }
+        if (helper.showGlobalOptions) {
+            const globalOptionList = helper
+                .visibleGlobalOptions(cmd)
+                .map((option) => callFormatItem(helper.styleOptionTerm(helper.optionTerm(option)), helper.styleOptionDescription(helper.optionDescription(option))));
+            output = output.concat(this.formatItemList('Global Options:', globalOptionList, helper));
+        }
+        const commandGroups = this.groupItems(cmd.commands, helper.visibleCommands(cmd), (sub) => sub.helpGroup() || 'Commands:');
+        for (const [group, commands] of commandGroups) {
+            const commandList = commands.map((sub) => callFormatItem(helper.styleSubcommandTerm(helper.subcommandTerm(sub)), helper.styleSubcommandDescription(helper.subcommandDescription(sub))));
+            output = output.concat(this.formatItemList(group, commandList, helper));
+        }
+        return output.join('\n');
+    }
+    displayWidth(str) {
+        return stripVTControlCharacters(str).length;
+    }
+    styleTitle(str) {
+        return str;
+    }
+    styleUsage(str) {
+        return str
+            .split(' ')
+            .map((word) => {
+            if (word === '[options]')
+                return this.styleOptionText(word);
+            if (word === '[command]')
+                return this.styleSubcommandText(word);
+            if (word[0] === '[' || word[0] === '<')
+                return this.styleArgumentText(word);
+            return this.styleCommandText(word);
+        })
+            .join(' ');
+    }
+    styleCommandDescription(str) {
+        return this.styleDescriptionText(str);
+    }
+    styleOptionDescription(str) {
+        return this.styleDescriptionText(str);
+    }
+    styleSubcommandDescription(str) {
+        return this.styleDescriptionText(str);
+    }
+    styleArgumentDescription(str) {
+        return this.styleDescriptionText(str);
+    }
+    styleDescriptionText(str) {
+        return str;
+    }
+    styleOptionTerm(str) {
+        return this.styleOptionText(str);
+    }
+    styleSubcommandTerm(str) {
+        return str
+            .split(' ')
+            .map((word) => {
+            if (word === '[options]')
+                return this.styleOptionText(word);
+            if (word[0] === '[' || word[0] === '<')
+                return this.styleArgumentText(word);
+            return this.styleSubcommandText(word);
+        })
+            .join(' ');
+    }
+    styleArgumentTerm(str) {
+        return this.styleArgumentText(str);
+    }
+    styleOptionText(str) {
+        return str;
+    }
+    styleArgumentText(str) {
+        return str;
+    }
+    styleSubcommandText(str) {
+        return str;
+    }
+    styleCommandText(str) {
+        return str;
+    }
+    padWidth(cmd, helper) {
+        return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
+    }
+    preformatted(str) {
+        return /\n[^\S\r\n]/.test(str);
+    }
+    formatItem(term, termWidth, description, helper) {
+        const itemIndent = 2;
+        const itemIndentStr = ' '.repeat(itemIndent);
+        if (!description)
+            return itemIndentStr + term;
+        const paddedTerm = term.padEnd(termWidth + term.length - helper.displayWidth(term));
+        const spacerWidth = 2;
+        const helpWidth = this.helpWidth ?? 80;
+        const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+        let formattedDescription;
+        if (remainingWidth < this.minWidthToWrap || helper.preformatted(description)) {
+            formattedDescription = description;
+        }
+        else {
+            const wrappedDescription = helper.boxWrap(description, remainingWidth);
+            formattedDescription = wrappedDescription.replace(/\n/g, `\n${' '.repeat(termWidth + spacerWidth)}`);
+        }
+        return itemIndentStr + paddedTerm + ' '.repeat(spacerWidth) + formattedDescription.replace(/\n/g, `\n${itemIndentStr}`);
+    }
+    boxWrap(str, width) {
+        if (width < this.minWidthToWrap)
+            return str;
+        const rawLines = str.split(/\r\n|\n/);
+        const chunkPattern = /[\s]*[^\s]+/g;
+        const wrappedLines = [];
+        for (const line of rawLines) {
+            const chunks = line.match(chunkPattern);
+            if (chunks === null) {
+                wrappedLines.push('');
+                continue;
+            }
+            let sumChunks = [chunks.shift() ?? ''];
+            let sumWidth = this.displayWidth(sumChunks[0] ?? '');
+            for (const chunk of chunks) {
+                const visibleWidth = this.displayWidth(chunk);
+                if (sumWidth + visibleWidth <= width) {
+                    sumChunks.push(chunk);
+                    sumWidth += visibleWidth;
+                    continue;
+                }
+                wrappedLines.push(sumChunks.join(''));
+                const nextChunk = chunk.trimStart();
+                sumChunks = [nextChunk];
+                sumWidth = this.displayWidth(nextChunk);
+            }
+            wrappedLines.push(sumChunks.join(''));
+        }
+        return wrappedLines.join('\n');
+    }
+}

package/dist/commander-option.d.ts

@@ -0,0 +1,58 @@
+import { type ParseArg } from './commander-argument.js';
+export declare class Option {
+    flags: string;
+    description: string;
+    required: boolean;
+    optional: boolean;
+    variadic: boolean;
+    mandatory: boolean;
+    short: string | undefined;
+    long: string | undefined;
+    negate: boolean;
+    defaultValue: unknown;
+    defaultValueDescription: string | undefined;
+    presetArg: unknown;
+    envVar: string | undefined;
+    parseArg: ParseArg | undefined;
+    hidden: boolean;
+    argChoices: string[] | undefined;
+    conflictsWith: string[];
+    implied: Record<string, unknown> | undefined;
+    helpGroupHeading: string | undefined;
+    constructor(flags: string, description?: string);
+    default(value: unknown, description?: string): this;
+    /** Value used when the option appears without an option-argument. `parseArg` still runs. */
+    preset(arg: unknown): this;
+    conflicts(names: string | string[]): this;
+    /** Values implied for other options when this one is set and they are not. `parseArg` does not run on them. */
+    implies(impliedOptionValues: string | Record<string, unknown>): this;
+    env(name: string): this;
+    argParser(fn?: ParseArg): this;
+    makeOptionMandatory(mandatory?: boolean): this;
+    hideHelp(hide?: boolean): this;
+    _collectValue(value: unknown, previous: unknown): unknown[];
+    choices(values: readonly string[]): this;
+    name(): string;
+    /** camelCase key used on the options object; `--no-foo` shares `foo` with `--foo`. */
+    attributeName(): string;
+    helpGroup(heading: string): this;
+    is(arg: string): boolean;
+    /** Options are one of boolean, negated, required-argument or optional-argument. */
+    isBoolean(): boolean;
+}
+/**
+ * `--build` and `--no-build` share one value. This works out which of the pair a
+ * value (probably) came from, so implied values are only applied for the right one.
+ */
+export declare class DualOptions {
+    positiveOptions: Map<string, Option>;
+    negativeOptions: Map<string, Option>;
+    dualOptions: Set<string>;
+    constructor(options: Option[]);
+    valueFromOption(value: unknown, option: Option): boolean;
+}
+/** Split `'-m,--mixed <value>'` into its short and long flags, failing noisily on anything else. */
+export declare function splitOptionFlags(flags: string): {
+    shortFlag: string | undefined;
+    longFlag: string | undefined;
+};

package/dist/commander-option.js

@@ -0,0 +1,164 @@
+import { InvalidArgumentError } from './commander-error.js';
+export class Option {
+    flags;
+    description;
+    required;
+    optional;
+    variadic;
+    mandatory = false;
+    short;
+    long;
+    negate = false;
+    defaultValue = undefined;
+    defaultValueDescription = undefined;
+    presetArg = undefined;
+    envVar = undefined;
+    parseArg = undefined;
+    hidden = false;
+    argChoices = undefined;
+    conflictsWith = [];
+    implied = undefined;
+    helpGroupHeading = undefined;
+    constructor(flags, description) {
+        this.flags = flags;
+        this.description = description || '';
+        this.required = flags.includes('<');
+        this.optional = flags.includes('[');
+        this.variadic = /\w\.\.\.[>\]]$/.test(flags);
+        const { shortFlag, longFlag } = splitOptionFlags(flags);
+        this.short = shortFlag;
+        this.long = longFlag;
+        if (this.long)
+            this.negate = this.long.startsWith('--no-');
+    }
+    default(value, description) {
+        this.defaultValue = value;
+        this.defaultValueDescription = description;
+        return this;
+    }
+    preset(arg) {
+        this.presetArg = arg;
+        return this;
+    }
+    conflicts(names) {
+        this.conflictsWith = this.conflictsWith.concat(names);
+        return this;
+    }
+    implies(impliedOptionValues) {
+        const newImplied = typeof impliedOptionValues === 'string' ? { [impliedOptionValues]: true } : impliedOptionValues;
+        this.implied = Object.assign(this.implied ?? {}, newImplied);
+        return this;
+    }
+    env(name) {
+        this.envVar = name;
+        return this;
+    }
+    argParser(fn) {
+        this.parseArg = fn;
+        return this;
+    }
+    makeOptionMandatory(mandatory = true) {
+        this.mandatory = !!mandatory;
+        return this;
+    }
+    hideHelp(hide = true) {
+        this.hidden = !!hide;
+        return this;
+    }
+    _collectValue(value, previous) {
+        if (previous === this.defaultValue || !Array.isArray(previous))
+            return [value];
+        previous.push(value);
+        return previous;
+    }
+    choices(values) {
+        this.argChoices = values.slice();
+        this.parseArg = (arg, previous) => {
+            if (!this.argChoices?.includes(arg)) {
+                throw new InvalidArgumentError(`Allowed choices are ${this.argChoices?.join(', ')}.`);
+            }
+            return this.variadic ? this._collectValue(arg, previous) : arg;
+        };
+        return this;
+    }
+    name() {
+        if (this.long)
+            return this.long.replace(/^--/, '');
+        return (this.short ?? '').replace(/^-/, '');
+    }
+    attributeName() {
+        return camelcase(this.negate ? this.name().replace(/^no-/, '') : this.name());
+    }
+    helpGroup(heading) {
+        this.helpGroupHeading = heading;
+        return this;
+    }
+    is(arg) {
+        return this.short === arg || this.long === arg;
+    }
+    isBoolean() {
+        return !this.required && !this.optional && !this.negate;
+    }
+}
+export class DualOptions {
+    positiveOptions = new Map();
+    negativeOptions = new Map();
+    dualOptions = new Set();
+    constructor(options) {
+        for (const option of options) {
+            (option.negate ? this.negativeOptions : this.positiveOptions).set(option.attributeName(), option);
+        }
+        for (const key of this.negativeOptions.keys()) {
+            if (this.positiveOptions.has(key))
+                this.dualOptions.add(key);
+        }
+    }
+    valueFromOption(value, option) {
+        const optionKey = option.attributeName();
+        if (!this.dualOptions.has(optionKey))
+            return true;
+        const preset = this.negativeOptions.get(optionKey)?.presetArg;
+        const negativeValue = preset !== undefined ? preset : false;
+        return option.negate === (negativeValue === value);
+    }
+}
+function camelcase(str) {
+    return str.split('-').reduce((acc, word) => acc + (word[0] ?? '').toUpperCase() + word.slice(1));
+}
+export function splitOptionFlags(flags) {
+    let shortFlag;
+    let longFlag;
+    const shortFlagExp = /^-[^-]$/;
+    const longFlagExp = /^--[^-]/;
+    const flagParts = flags.split(/[ |,]+/).concat('guard');
+    const head = () => flagParts[0] ?? '';
+    if (shortFlagExp.test(head()))
+        shortFlag = flagParts.shift();
+    if (longFlagExp.test(head()))
+        longFlag = flagParts.shift();
+    if (!shortFlag && shortFlagExp.test(head()))
+        shortFlag = flagParts.shift();
+    if (!shortFlag && longFlagExp.test(head())) {
+        shortFlag = longFlag;
+        longFlag = flagParts.shift();
+    }
+    if (head().startsWith('-')) {
+        const unsupportedFlag = head();
+        const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;
+        if (/^-[^-][^-]/.test(unsupportedFlag)) {
+            throw new Error(`${baseError}
+- a short flag is a single dash and a single character
+  - either use a single dash and a single character (for a short flag)
+  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`);
+        }
+        if (shortFlagExp.test(unsupportedFlag))
+            throw new Error(`${baseError}\n- too many short flags`);
+        if (longFlagExp.test(unsupportedFlag))
+            throw new Error(`${baseError}\n- too many long flags`);
+        throw new Error(`${baseError}\n- unrecognised flag format`);
+    }
+    if (shortFlag === undefined && longFlag === undefined) {
+        throw new Error(`option creation failed due to no flags found in '${flags}'.`);
+    }
+    return { shortFlag, longFlag };
+}

package/dist/commander-suggest.d.ts

@@ -0,0 +1,2 @@
+/** Close matches, restricted to the same number of edits, as `\n(Did you mean …?)`. */
+export declare function suggestSimilar(word: string, candidates: string[] | undefined): string;