pxnpm 5.0.0 → 6.0.1

package/dist/node_modules/jackspeak/dist/commonjs/index.js

@@ -0,0 +1,1010 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jack = exports.Jack = exports.isConfigOption = exports.isConfigType = void 0;
+const node_util_1 = require("node:util");
+const parse_args_js_1 = require("./parse-args.js");
+// it's a tiny API, just cast it inline, it's fine
+//@ts-ignore
+const cliui_1 = __importDefault(require("@isaacs/cliui"));
+const node_path_1 = require("node:path");
+const width = Math.min((process && process.stdout && process.stdout.columns) || 80, 80);
+// indentation spaces from heading level
+const indent = (n) => (n - 1) * 2;
+const toEnvKey = (pref, key) => {
+    return [pref, key.replace(/[^a-zA-Z0-9]+/g, ' ')]
+        .join(' ')
+        .trim()
+        .toUpperCase()
+        .replace(/ /g, '_');
+};
+const toEnvVal = (value, delim = '\n') => {
+    const str = typeof value === 'string' ? value
+        : typeof value === 'boolean' ?
+            value ? '1'
+                : '0'
+            : typeof value === 'number' ? String(value)
+                : Array.isArray(value) ?
+                    value.map((v) => toEnvVal(v)).join(delim)
+                    : /* c8 ignore start */ undefined;
+    if (typeof str !== 'string') {
+        throw new Error(`could not serialize value to environment: ${JSON.stringify(value)}`);
+    }
+    /* c8 ignore stop */
+    return str;
+};
+const fromEnvVal = (env, type, multiple, delim = '\n') => (multiple ?
+    env ? env.split(delim).map(v => fromEnvVal(v, type, false))
+        : []
+    : type === 'string' ? env
+        : type === 'boolean' ? env === '1'
+            : +env.trim());
+const isConfigType = (t) => typeof t === 'string' &&
+    (t === 'string' || t === 'number' || t === 'boolean');
+exports.isConfigType = isConfigType;
+const undefOrType = (v, t) => v === undefined || typeof v === t;
+const undefOrTypeArray = (v, t) => v === undefined || (Array.isArray(v) && v.every(x => typeof x === t));
+const isValidOption = (v, vo) => Array.isArray(v) ? v.every(x => isValidOption(x, vo)) : vo.includes(v);
+// print the value type, for error message reporting
+const valueType = (v) => typeof v === 'string' ? 'string'
+    : typeof v === 'boolean' ? 'boolean'
+        : typeof v === 'number' ? 'number'
+            : Array.isArray(v) ?
+                joinTypes([...new Set(v.map(v => valueType(v)))]) + '[]'
+                : `${v.type}${v.multiple ? '[]' : ''}`;
+const joinTypes = (types) => types.length === 1 && typeof types[0] === 'string' ?
+    types[0]
+    : `(${types.join('|')})`;
+const isValidValue = (v, type, multi) => {
+    if (multi) {
+        if (!Array.isArray(v))
+            return false;
+        return !v.some((v) => !isValidValue(v, type, false));
+    }
+    if (Array.isArray(v))
+        return false;
+    return typeof v === type;
+};
+const isConfigOption = (o, type, multi) => !!o &&
+    typeof o === 'object' &&
+    (0, exports.isConfigType)(o.type) &&
+    o.type === type &&
+    undefOrType(o.short, 'string') &&
+    undefOrType(o.description, 'string') &&
+    undefOrType(o.hint, 'string') &&
+    undefOrType(o.validate, 'function') &&
+    (o.type === 'boolean' ?
+        o.validOptions === undefined
+        : undefOrTypeArray(o.validOptions, o.type)) &&
+    (o.default === undefined || isValidValue(o.default, type, multi)) &&
+    !!o.multiple === multi;
+exports.isConfigOption = isConfigOption;
+function num(o = {}) {
+    const { default: def, validate: val, validOptions, ...rest } = o;
+    if (def !== undefined && !isValidValue(def, 'number', false)) {
+        throw new TypeError('invalid default value', {
+            cause: {
+                found: def,
+                wanted: 'number',
+            },
+        });
+    }
+    if (!undefOrTypeArray(validOptions, 'number')) {
+        throw new TypeError('invalid validOptions', {
+            cause: {
+                found: validOptions,
+                wanted: 'number[]',
+            },
+        });
+    }
+    const validate = val ?
+        val
+        : undefined;
+    return {
+        ...rest,
+        default: def,
+        validate,
+        validOptions,
+        type: 'number',
+        multiple: false,
+    };
+}
+function numList(o = {}) {
+    const { default: def, validate: val, validOptions, ...rest } = o;
+    if (def !== undefined && !isValidValue(def, 'number', true)) {
+        throw new TypeError('invalid default value', {
+            cause: {
+                found: def,
+                wanted: 'number[]',
+            },
+        });
+    }
+    if (!undefOrTypeArray(validOptions, 'number')) {
+        throw new TypeError('invalid validOptions', {
+            cause: {
+                found: validOptions,
+                wanted: 'number[]',
+            },
+        });
+    }
+    const validate = val ?
+        val
+        : undefined;
+    return {
+        ...rest,
+        default: def,
+        validate,
+        validOptions,
+        type: 'number',
+        multiple: true,
+    };
+}
+function opt(o = {}) {
+    const { default: def, validate: val, validOptions, ...rest } = o;
+    if (def !== undefined && !isValidValue(def, 'string', false)) {
+        throw new TypeError('invalid default value', {
+            cause: {
+                found: def,
+                wanted: 'string',
+            },
+        });
+    }
+    if (!undefOrTypeArray(validOptions, 'string')) {
+        throw new TypeError('invalid validOptions', {
+            cause: {
+                found: validOptions,
+                wanted: 'string[]',
+            },
+        });
+    }
+    const validate = val ?
+        val
+        : undefined;
+    return {
+        ...rest,
+        default: def,
+        validate,
+        validOptions,
+        type: 'string',
+        multiple: false,
+    };
+}
+function optList(o = {}) {
+    const { default: def, validate: val, validOptions, ...rest } = o;
+    if (def !== undefined && !isValidValue(def, 'string', true)) {
+        throw new TypeError('invalid default value', {
+            cause: {
+                found: def,
+                wanted: 'string[]',
+            },
+        });
+    }
+    if (!undefOrTypeArray(validOptions, 'string')) {
+        throw new TypeError('invalid validOptions', {
+            cause: {
+                found: validOptions,
+                wanted: 'string[]',
+            },
+        });
+    }
+    const validate = val ?
+        val
+        : undefined;
+    return {
+        ...rest,
+        default: def,
+        validate,
+        validOptions,
+        type: 'string',
+        multiple: true,
+    };
+}
+function flag(o = {}) {
+    const { hint, default: def, validate: val, ...rest } = o;
+    delete rest.validOptions;
+    if (def !== undefined && !isValidValue(def, 'boolean', false)) {
+        throw new TypeError('invalid default value');
+    }
+    const validate = val ?
+        val
+        : undefined;
+    if (hint !== undefined) {
+        throw new TypeError('cannot provide hint for flag');
+    }
+    return {
+        ...rest,
+        default: def,
+        validate,
+        type: 'boolean',
+        multiple: false,
+    };
+}
+function flagList(o = {}) {
+    const { hint, default: def, validate: val, ...rest } = o;
+    delete rest.validOptions;
+    if (def !== undefined && !isValidValue(def, 'boolean', true)) {
+        throw new TypeError('invalid default value');
+    }
+    const validate = val ?
+        val
+        : undefined;
+    if (hint !== undefined) {
+        throw new TypeError('cannot provide hint for flag list');
+    }
+    return {
+        ...rest,
+        default: def,
+        validate,
+        type: 'boolean',
+        multiple: true,
+    };
+}
+const toParseArgsOptionsConfig = (options) => {
+    const c = {};
+    for (const longOption in options) {
+        const config = options[longOption];
+        /* c8 ignore start */
+        if (!config) {
+            throw new Error('config must be an object: ' + longOption);
+        }
+        /* c8 ignore start */
+        if ((0, exports.isConfigOption)(config, 'number', true)) {
+            c[longOption] = {
+                type: 'string',
+                multiple: true,
+                default: config.default?.map(c => String(c)),
+            };
+        }
+        else if ((0, exports.isConfigOption)(config, 'number', false)) {
+            c[longOption] = {
+                type: 'string',
+                multiple: false,
+                default: config.default === undefined ?
+                    undefined
+                    : String(config.default),
+            };
+        }
+        else {
+            const conf = config;
+            c[longOption] = {
+                type: conf.type,
+                multiple: !!conf.multiple,
+                default: conf.default,
+            };
+        }
+        const clo = c[longOption];
+        if (typeof config.short === 'string') {
+            clo.short = config.short;
+        }
+        if (config.type === 'boolean' &&
+            !longOption.startsWith('no-') &&
+            !options[`no-${longOption}`]) {
+            c[`no-${longOption}`] = {
+                type: 'boolean',
+                multiple: config.multiple,
+            };
+        }
+    }
+    return c;
+};
+const isHeading = (r) => r.type === 'heading';
+const isDescription = (r) => r.type === 'description';
+/**
+ * Class returned by the {@link jack} function and all configuration
+ * definition methods.  This is what gets chained together.
+ */
+class Jack {
+    #configSet;
+    #shorts;
+    #options;
+    #fields = [];
+    #env;
+    #envPrefix;
+    #allowPositionals;
+    #usage;
+    #usageMarkdown;
+    constructor(options = {}) {
+        this.#options = options;
+        this.#allowPositionals = options.allowPositionals !== false;
+        this.#env =
+            this.#options.env === undefined ? process.env : this.#options.env;
+        this.#envPrefix = options.envPrefix;
+        // We need to fib a little, because it's always the same object, but it
+        // starts out as having an empty config set.  Then each method that adds
+        // fields returns `this as Jack<C & { ...newConfigs }>`
+        this.#configSet = Object.create(null);
+        this.#shorts = Object.create(null);
+    }
+    /**
+     * Set the default value (which will still be overridden by env or cli)
+     * as if from a parsed config file. The optional `source` param, if
+     * provided, will be included in error messages if a value is invalid or
+     * unknown.
+     */
+    setConfigValues(values, source = '') {
+        try {
+            this.validate(values);
+        }
+        catch (er) {
+            const e = er;
+            if (source && e && typeof e === 'object') {
+                if (e.cause && typeof e.cause === 'object') {
+                    Object.assign(e.cause, { path: source });
+                }
+                else {
+                    e.cause = { path: source };
+                }
+            }
+            throw e;
+        }
+        for (const [field, value] of Object.entries(values)) {
+            const my = this.#configSet[field];
+            // already validated, just for TS's benefit
+            /* c8 ignore start */
+            if (!my) {
+                throw new Error('unexpected field in config set: ' + field, {
+                    cause: { found: field },
+                });
+            }
+            /* c8 ignore stop */
+            my.default = value;
+        }
+        return this;
+    }
+    /**
+     * Parse a string of arguments, and return the resulting
+     * `{ values, positionals }` object.
+     *
+     * If an {@link JackOptions#envPrefix} is set, then it will read default
+     * values from the environment, and write the resulting values back
+     * to the environment as well.
+     *
+     * Environment values always take precedence over any other value, except
+     * an explicit CLI setting.
+     */
+    parse(args = process.argv) {
+        this.loadEnvDefaults();
+        const p = this.parseRaw(args);
+        this.applyDefaults(p);
+        this.writeEnv(p);
+        return p;
+    }
+    loadEnvDefaults() {
+        if (this.#envPrefix) {
+            for (const [field, my] of Object.entries(this.#configSet)) {
+                const ek = toEnvKey(this.#envPrefix, field);
+                const env = this.#env[ek];
+                if (env !== undefined) {
+                    my.default = fromEnvVal(env, my.type, !!my.multiple, my.delim);
+                }
+            }
+        }
+    }
+    applyDefaults(p) {
+        for (const [field, c] of Object.entries(this.#configSet)) {
+            if (c.default !== undefined && !(field in p.values)) {
+                //@ts-ignore
+                p.values[field] = c.default;
+            }
+        }
+    }
+    /**
+     * Only parse the command line arguments passed in.
+     * Does not strip off the `node script.js` bits, so it must be just the
+     * arguments you wish to have parsed.
+     * Does not read from or write to the environment, or set defaults.
+     */
+    parseRaw(args) {
+        if (args === process.argv) {
+            args = args.slice(process._eval !== undefined ? 1 : 2);
+        }
+        const options = toParseArgsOptionsConfig(this.#configSet);
+        const result = (0, parse_args_js_1.parseArgs)({
+            args,
+            options,
+            // always strict, but using our own logic
+            strict: false,
+            allowPositionals: this.#allowPositionals,
+            tokens: true,
+        });
+        const p = {
+            values: {},
+            positionals: [],
+        };
+        for (const token of result.tokens) {
+            if (token.kind === 'positional') {
+                p.positionals.push(token.value);
+                if (this.#options.stopAtPositional ||
+                    this.#options.stopAtPositionalTest?.(token.value)) {
+                    p.positionals.push(...args.slice(token.index + 1));
+                    break;
+                }
+            }
+            else if (token.kind === 'option') {
+                let value = undefined;
+                if (token.name.startsWith('no-')) {
+                    const my = this.#configSet[token.name];
+                    const pname = token.name.substring('no-'.length);
+                    const pos = this.#configSet[pname];
+                    if (pos &&
+                        pos.type === 'boolean' &&
+                        (!my ||
+                            (my.type === 'boolean' && !!my.multiple === !!pos.multiple))) {
+                        value = false;
+                        token.name = pname;
+                    }
+                }
+                const my = this.#configSet[token.name];
+                if (!my) {
+                    throw new Error(`Unknown option '${token.rawName}'. ` +
+                        `To specify a positional argument starting with a '-', ` +
+                        `place it at the end of the command after '--', as in ` +
+                        `'-- ${token.rawName}'`, {
+                        cause: {
+                            found: token.rawName + (token.value ? `=${token.value}` : ''),
+                        },
+                    });
+                }
+                if (value === undefined) {
+                    if (token.value === undefined) {
+                        if (my.type !== 'boolean') {
+                            throw new Error(`No value provided for ${token.rawName}, expected ${my.type}`, {
+                                cause: {
+                                    name: token.rawName,
+                                    wanted: valueType(my),
+                                },
+                            });
+                        }
+                        value = true;
+                    }
+                    else {
+                        if (my.type === 'boolean') {
+                            throw new Error(`Flag ${token.rawName} does not take a value, received '${token.value}'`, { cause: { found: token } });
+                        }
+                        if (my.type === 'string') {
+                            value = token.value;
+                        }
+                        else {
+                            value = +token.value;
+                            if (value !== value) {
+                                throw new Error(`Invalid value '${token.value}' provided for ` +
+                                    `'${token.rawName}' option, expected number`, {
+                                    cause: {
+                                        name: token.rawName,
+                                        found: token.value,
+                                        wanted: 'number',
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+                if (my.multiple) {
+                    const pv = p.values;
+                    const tn = pv[token.name] ?? [];
+                    pv[token.name] = tn;
+                    tn.push(value);
+                }
+                else {
+                    const pv = p.values;
+                    pv[token.name] = value;
+                }
+            }
+        }
+        for (const [field, value] of Object.entries(p.values)) {
+            const valid = this.#configSet[field]?.validate;
+            const validOptions = this.#configSet[field]?.validOptions;
+            let cause;
+            if (validOptions && !isValidOption(value, validOptions)) {
+                cause = { name: field, found: value, validOptions: validOptions };
+            }
+            if (valid && !valid(value)) {
+                cause = cause || { name: field, found: value };
+            }
+            if (cause) {
+                throw new Error(`Invalid value provided for --${field}: ${JSON.stringify(value)}`, { cause });
+            }
+        }
+        return p;
+    }
+    /**
+     * do not set fields as 'no-foo' if 'foo' exists and both are bools
+     * just set foo.
+     */
+    #noNoFields(f, val, s = f) {
+        if (!f.startsWith('no-') || typeof val !== 'boolean')
+            return;
+        const yes = f.substring('no-'.length);
+        // recurse so we get the core config key we care about.
+        this.#noNoFields(yes, val, s);
+        if (this.#configSet[yes]?.type === 'boolean') {
+            throw new Error(`do not set '${s}', instead set '${yes}' as desired.`, { cause: { found: s, wanted: yes } });
+        }
+    }
+    /**
+     * Validate that any arbitrary object is a valid configuration `values`
+     * object.  Useful when loading config files or other sources.
+     */
+    validate(o) {
+        if (!o || typeof o !== 'object') {
+            throw new Error('Invalid config: not an object', {
+                cause: { found: o },
+            });
+        }
+        const opts = o;
+        for (const field in o) {
+            const value = opts[field];
+            /* c8 ignore next - for TS */
+            if (value === undefined)
+                continue;
+            this.#noNoFields(field, value);
+            const config = this.#configSet[field];
+            if (!config) {
+                throw new Error(`Unknown config option: ${field}`, {
+                    cause: { found: field },
+                });
+            }
+            if (!isValidValue(value, config.type, !!config.multiple)) {
+                throw new Error(`Invalid value ${valueType(value)} for ${field}, expected ${valueType(config)}`, {
+                    cause: {
+                        name: field,
+                        found: value,
+                        wanted: valueType(config),
+                    },
+                });
+            }
+            let cause;
+            if (config.validOptions &&
+                !isValidOption(value, config.validOptions)) {
+                cause = {
+                    name: field,
+                    found: value,
+                    validOptions: config.validOptions,
+                };
+            }
+            if (config.validate && !config.validate(value)) {
+                cause = cause || { name: field, found: value };
+            }
+            if (cause) {
+                throw new Error(`Invalid config value for ${field}: ${value}`, {
+                    cause,
+                });
+            }
+        }
+    }
+    writeEnv(p) {
+        if (!this.#env || !this.#envPrefix)
+            return;
+        for (const [field, value] of Object.entries(p.values)) {
+            const my = this.#configSet[field];
+            this.#env[toEnvKey(this.#envPrefix, field)] = toEnvVal(value, my?.delim);
+        }
+    }
+    /**
+     * Add a heading to the usage output banner
+     */
+    heading(text, level, { pre = false } = {}) {
+        if (level === undefined) {
+            level = this.#fields.some(r => isHeading(r)) ? 2 : 1;
+        }
+        this.#fields.push({ type: 'heading', text, level, pre });
+        return this;
+    }
+    /**
+     * Add a long-form description to the usage output at this position.
+     */
+    description(text, { pre } = {}) {
+        this.#fields.push({ type: 'description', text, pre });
+        return this;
+    }
+    /**
+     * Add one or more number fields.
+     */
+    num(fields) {
+        return this.#addFields(fields, num);
+    }
+    /**
+     * Add one or more multiple number fields.
+     */
+    numList(fields) {
+        return this.#addFields(fields, numList);
+    }
+    /**
+     * Add one or more string option fields.
+     */
+    opt(fields) {
+        return this.#addFields(fields, opt);
+    }
+    /**
+     * Add one or more multiple string option fields.
+     */
+    optList(fields) {
+        return this.#addFields(fields, optList);
+    }
+    /**
+     * Add one or more flag fields.
+     */
+    flag(fields) {
+        return this.#addFields(fields, flag);
+    }
+    /**
+     * Add one or more multiple flag fields.
+     */
+    flagList(fields) {
+        return this.#addFields(fields, flagList);
+    }
+    /**
+     * Generic field definition method. Similar to flag/flagList/number/etc,
+     * but you must specify the `type` (and optionally `multiple` and `delim`)
+     * fields on each one, or Jack won't know how to define them.
+     */
+    addFields(fields) {
+        const next = this;
+        for (const [name, field] of Object.entries(fields)) {
+            this.#validateName(name, field);
+            next.#fields.push({
+                type: 'config',
+                name,
+                value: field,
+            });
+        }
+        Object.assign(next.#configSet, fields);
+        return next;
+    }
+    #addFields(fields, fn) {
+        const next = this;
+        Object.assign(next.#configSet, Object.fromEntries(Object.entries(fields).map(([name, field]) => {
+            this.#validateName(name, field);
+            const option = fn(field);
+            next.#fields.push({
+                type: 'config',
+                name,
+                value: option,
+            });
+            return [name, option];
+        })));
+        return next;
+    }
+    #validateName(name, field) {
+        if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(name)) {
+            throw new TypeError(`Invalid option name: ${name}, ` +
+                `must be '-' delimited ASCII alphanumeric`);
+        }
+        if (this.#configSet[name]) {
+            throw new TypeError(`Cannot redefine option ${field}`);
+        }
+        if (this.#shorts[name]) {
+            throw new TypeError(`Cannot redefine option ${name}, already ` +
+                `in use for ${this.#shorts[name]}`);
+        }
+        if (field.short) {
+            if (!/^[a-zA-Z0-9]$/.test(field.short)) {
+                throw new TypeError(`Invalid ${name} short option: ${field.short}, ` +
+                    'must be 1 ASCII alphanumeric character');
+            }
+            if (this.#shorts[field.short]) {
+                throw new TypeError(`Invalid ${name} short option: ${field.short}, ` +
+                    `already in use for ${this.#shorts[field.short]}`);
+            }
+            this.#shorts[field.short] = name;
+            this.#shorts[name] = name;
+        }
+    }
+    /**
+     * Return the usage banner for the given configuration
+     */
+    usage() {
+        if (this.#usage)
+            return this.#usage;
+        let headingLevel = 1;
+        const ui = (0, cliui_1.default)({ width });
+        const first = this.#fields[0];
+        let start = first?.type === 'heading' ? 1 : 0;
+        if (first?.type === 'heading') {
+            ui.div({
+                padding: [0, 0, 0, 0],
+                text: normalize(first.text),
+            });
+        }
+        ui.div({ padding: [0, 0, 0, 0], text: 'Usage:' });
+        if (this.#options.usage) {
+            ui.div({
+                text: this.#options.usage,
+                padding: [0, 0, 0, 2],
+            });
+        }
+        else {
+            const cmd = (0, node_path_1.basename)(String(process.argv[1]));
+            const shortFlags = [];
+            const shorts = [];
+            const flags = [];
+            const opts = [];
+            for (const [field, config] of Object.entries(this.#configSet)) {
+                if (config.short) {
+                    if (config.type === 'boolean')
+                        shortFlags.push(config.short);
+                    else
+                        shorts.push([config.short, config.hint || field]);
+                }
+                else {
+                    if (config.type === 'boolean')
+                        flags.push(field);
+                    else
+                        opts.push([field, config.hint || field]);
+                }
+            }
+            const sf = shortFlags.length ? ' -' + shortFlags.join('') : '';
+            const so = shorts.map(([k, v]) => ` --${k}=<${v}>`).join('');
+            const lf = flags.map(k => ` --${k}`).join('');
+            const lo = opts.map(([k, v]) => ` --${k}=<${v}>`).join('');
+            const usage = `${cmd}${sf}${so}${lf}${lo}`.trim();
+            ui.div({
+                text: usage,
+                padding: [0, 0, 0, 2],
+            });
+        }
+        ui.div({ padding: [0, 0, 0, 0], text: '' });
+        const maybeDesc = this.#fields[start];
+        if (maybeDesc && isDescription(maybeDesc)) {
+            const print = normalize(maybeDesc.text, maybeDesc.pre);
+            start++;
+            ui.div({ padding: [0, 0, 0, 0], text: print });
+            ui.div({ padding: [0, 0, 0, 0], text: '' });
+        }
+        const { rows, maxWidth } = this.#usageRows(start);
+        // every heading/description after the first gets indented by 2
+        // extra spaces.
+        for (const row of rows) {
+            if (row.left) {
+                // If the row is too long, don't wrap it
+                // Bump the right-hand side down a line to make room
+                const configIndent = indent(Math.max(headingLevel, 2));
+                if (row.left.length > maxWidth - 3) {
+                    ui.div({ text: row.left, padding: [0, 0, 0, configIndent] });
+                    ui.div({ text: row.text, padding: [0, 0, 0, maxWidth] });
+                }
+                else {
+                    ui.div({
+                        text: row.left,
+                        padding: [0, 1, 0, configIndent],
+                        width: maxWidth,
+                    }, { padding: [0, 0, 0, 0], text: row.text });
+                }
+                if (row.skipLine) {
+                    ui.div({ padding: [0, 0, 0, 0], text: '' });
+                }
+            }
+            else {
+                if (isHeading(row)) {
+                    const { level } = row;
+                    headingLevel = level;
+                    // only h1 and h2 have bottom padding
+                    // h3-h6 do not
+                    const b = level <= 2 ? 1 : 0;
+                    ui.div({ ...row, padding: [0, 0, b, indent(level)] });
+                }
+                else {
+                    ui.div({ ...row, padding: [0, 0, 1, indent(headingLevel + 1)] });
+                }
+            }
+        }
+        return (this.#usage = ui.toString());
+    }
+    /**
+     * Return the usage banner markdown for the given configuration
+     */
+    usageMarkdown() {
+        if (this.#usageMarkdown)
+            return this.#usageMarkdown;
+        const out = [];
+        let headingLevel = 1;
+        const first = this.#fields[0];
+        let start = first?.type === 'heading' ? 1 : 0;
+        if (first?.type === 'heading') {
+            out.push(`# ${normalizeOneLine(first.text)}`);
+        }
+        out.push('Usage:');
+        if (this.#options.usage) {
+            out.push(normalizeMarkdown(this.#options.usage, true));
+        }
+        else {
+            const cmd = (0, node_path_1.basename)(String(process.argv[1]));
+            const shortFlags = [];
+            const shorts = [];
+            const flags = [];
+            const opts = [];
+            for (const [field, config] of Object.entries(this.#configSet)) {
+                if (config.short) {
+                    if (config.type === 'boolean')
+                        shortFlags.push(config.short);
+                    else
+                        shorts.push([config.short, config.hint || field]);
+                }
+                else {
+                    if (config.type === 'boolean')
+                        flags.push(field);
+                    else
+                        opts.push([field, config.hint || field]);
+                }
+            }
+            const sf = shortFlags.length ? ' -' + shortFlags.join('') : '';
+            const so = shorts.map(([k, v]) => ` --${k}=<${v}>`).join('');
+            const lf = flags.map(k => ` --${k}`).join('');
+            const lo = opts.map(([k, v]) => ` --${k}=<${v}>`).join('');
+            const usage = `${cmd}${sf}${so}${lf}${lo}`.trim();
+            out.push(normalizeMarkdown(usage, true));
+        }
+        const maybeDesc = this.#fields[start];
+        if (maybeDesc && isDescription(maybeDesc)) {
+            out.push(normalizeMarkdown(maybeDesc.text, maybeDesc.pre));
+            start++;
+        }
+        const { rows } = this.#usageRows(start);
+        // heading level in markdown is number of # ahead of text
+        for (const row of rows) {
+            if (row.left) {
+                out.push('#'.repeat(headingLevel + 1) +
+                    ' ' +
+                    normalizeOneLine(row.left, true));
+                if (row.text)
+                    out.push(normalizeMarkdown(row.text));
+            }
+            else if (isHeading(row)) {
+                const { level } = row;
+                headingLevel = level;
+                out.push(`${'#'.repeat(headingLevel)} ${normalizeOneLine(row.text, row.pre)}`);
+            }
+            else {
+                out.push(normalizeMarkdown(row.text, !!row.pre));
+            }
+        }
+        return (this.#usageMarkdown = out.join('\n\n') + '\n');
+    }
+    #usageRows(start) {
+        // turn each config type into a row, and figure out the width of the
+        // left hand indentation for the option descriptions.
+        let maxMax = Math.max(12, Math.min(26, Math.floor(width / 3)));
+        let maxWidth = 8;
+        let prev = undefined;
+        const rows = [];
+        for (const field of this.#fields.slice(start)) {
+            if (field.type !== 'config') {
+                if (prev?.type === 'config')
+                    prev.skipLine = true;
+                prev = undefined;
+                field.text = normalize(field.text, !!field.pre);
+                rows.push(field);
+                continue;
+            }
+            const { value } = field;
+            const desc = value.description || '';
+            const mult = value.multiple ? 'Can be set multiple times' : '';
+            const opts = value.validOptions?.length ?
+                `Valid options:${value.validOptions.map(v => ` ${JSON.stringify(v)}`)}`
+                : '';
+            const dmDelim = desc.includes('\n') ? '\n\n' : '\n';
+            const extra = [opts, mult].join(dmDelim).trim();
+            const text = (normalize(desc) + dmDelim + extra).trim();
+            const hint = value.hint ||
+                (value.type === 'number' ? 'n'
+                    : value.type === 'string' ? field.name
+                        : undefined);
+            const short = !value.short ? ''
+                : value.type === 'boolean' ? `-${value.short} `
+                    : `-${value.short}<${hint}> `;
+            const left = value.type === 'boolean' ?
+                `${short}--${field.name}`
+                : `${short}--${field.name}=<${hint}>`;
+            const row = { text, left, type: 'config' };
+            if (text.length > width - maxMax) {
+                row.skipLine = true;
+            }
+            if (prev && left.length > maxMax)
+                prev.skipLine = true;
+            prev = row;
+            const len = left.length + 4;
+            if (len > maxWidth && len < maxMax) {
+                maxWidth = len;
+            }
+            rows.push(row);
+        }
+        return { rows, maxWidth };
+    }
+    /**
+     * Return the configuration options as a plain object
+     */
+    toJSON() {
+        return Object.fromEntries(Object.entries(this.#configSet).map(([field, def]) => [
+            field,
+            {
+                type: def.type,
+                ...(def.multiple ? { multiple: true } : {}),
+                ...(def.delim ? { delim: def.delim } : {}),
+                ...(def.short ? { short: def.short } : {}),
+                ...(def.description ?
+                    { description: normalize(def.description) }
+                    : {}),
+                ...(def.validate ? { validate: def.validate } : {}),
+                ...(def.validOptions ? { validOptions: def.validOptions } : {}),
+                ...(def.default !== undefined ? { default: def.default } : {}),
+                ...(def.hint ? { hint: def.hint } : {}),
+            },
+        ]));
+    }
+    /**
+     * Custom printer for `util.inspect`
+     */
+    [node_util_1.inspect.custom](_, options) {
+        return `Jack ${(0, node_util_1.inspect)(this.toJSON(), options)}`;
+    }
+}
+exports.Jack = Jack;
+// Unwrap and un-indent, so we can wrap description
+// strings however makes them look nice in the code.
+const normalize = (s, pre = false) => {
+    if (pre)
+        // prepend a ZWSP to each line so cliui doesn't strip it.
+        return s
+            .split('\n')
+            .map(l => `\u200b${l}`)
+            .join('\n');
+    return s
+        .split(/^\s*```\s*$/gm)
+        .map((s, i) => {
+        if (i % 2 === 1) {
+            if (!s.trim()) {
+                return `\`\`\`\n\`\`\`\n`;
+            }
+            // outdent the ``` blocks, but preserve whitespace otherwise.
+            const split = s.split('\n');
+            // throw out the \n at the start and end
+            split.pop();
+            split.shift();
+            const si = split.reduce((shortest, l) => {
+                /* c8 ignore next */
+                const ind = l.match(/^\s*/)?.[0] ?? '';
+                if (ind.length)
+                    return Math.min(ind.length, shortest);
+                else
+                    return shortest;
+            }, Infinity);
+            /* c8 ignore next */
+            const i = isFinite(si) ? si : 0;
+            return ('\n```\n' +
+                split.map(s => `\u200b${s.substring(i)}`).join('\n') +
+                '\n```\n');
+        }
+        return (s
+            // remove single line breaks, except for lists
+            .replace(/([^\n])\n[ \t]*([^\n])/g, (_, $1, $2) => !/^[-*]/.test($2) ? `${$1} ${$2}` : `${$1}\n${$2}`)
+            // normalize mid-line whitespace
+            .replace(/([^\n])[ \t]+([^\n])/g, '$1 $2')
+            // two line breaks are enough
+            .replace(/\n{3,}/g, '\n\n')
+            // remove any spaces at the start of a line
+            .replace(/\n[ \t]+/g, '\n')
+            .trim());
+    })
+        .join('\n');
+};
+// normalize for markdown printing, remove leading spaces on lines
+const normalizeMarkdown = (s, pre = false) => {
+    const n = normalize(s, pre).replace(/\\/g, '\\\\');
+    return pre ?
+        `\`\`\`\n${n.replace(/\u200b/g, '')}\n\`\`\``
+        : n.replace(/\n +/g, '\n').trim();
+};
+const normalizeOneLine = (s, pre = false) => {
+    const n = normalize(s, pre)
+        .replace(/[\s\u200b]+/g, ' ')
+        .trim();
+    return pre ? `\`${n}\`` : n;
+};
+/**
+ * Main entry point. Create and return a {@link Jack} object.
+ */
+const jack = (options = {}) => new Jack(options);
+exports.jack = jack;
+//# sourceMappingURL=index.js.map