burgee 0.3.0 → 0.4.0

package/dist/{commander-error.js → commander/error.js}

@@ -1,3 +1,4 @@
+/** commander's error classes, byte-for-byte in shape: `code`, `exitCode`, `nestedError`. */
 export class CommanderError extends Error {
     code;
     exitCode;
@@ -18,3 +19,4 @@ export class InvalidArgumentError extends CommanderError {
         this.name = this.constructor.name;
     }
 }
+//# sourceMappingURL=error.js.map

package/dist/{commander-help.d.ts → commander/help.d.ts}

@@ -1,6 +1,6 @@
-import { type Argument } from './commander-argument.js';
-import type { Command } from './commander-command.js';
-import type { Option } from './commander-option.js';
+import { type Argument } from './argument.js';
+import type { Command } from './command.js';
+import type { Option } from './option.js';
 export interface HelpContext {
     error?: boolean;
     helpWidth?: number;

package/dist/{commander-help.js → commander/help.js}

@@ -1,11 +1,13 @@
 import { stripVTControlCharacters } from 'node:util';
-import { humanReadableArgName } from './commander-argument.js';
+import { humanReadableArgName } from './argument.js';
+/** Methods are static in style so a subclass, or plain functions via `configureHelp`, can override them. */
 export class Help {
     helpWidth = undefined;
     minWidthToWrap = 40;
     sortSubcommands = false;
     sortOptions = false;
     showGlobalOptions = false;
+    /** Called after `configureHelp` overrides are applied and just before `formatHelp`. */
     prepareContext(contextOptions) {
         this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
     }
@@ -26,6 +28,7 @@ export class Help {
         const visibleOptions = cmd.options.filter((option) => !option.hidden);
         const helpOption = cmd._getHelpOption();
         if (helpOption && !helpOption.hidden) {
+            // Historical: hide the built-in help flags a user option already took.
             const removeShort = helpOption.short && cmd._findOption(helpOption.short);
             const removeLong = helpOption.long && cmd._findOption(helpOption.long);
             if (!removeShort && !removeLong)
@@ -51,6 +54,7 @@ export class Help {
         return globalOptions;
     }
     visibleArguments(cmd) {
+        // Side effect: apply the legacy descriptions before the arguments are displayed.
         if (cmd._argsDescription) {
             for (const argument of cmd.registeredArguments) {
                 argument.description = argument.description || cmd._argsDescription[argument.name()] || '';
@@ -106,6 +110,7 @@ export class Help {
     commandDescription(cmd) {
         return cmd.description();
     }
+    /** Summary, falling back to description for backwards compatibility. */
     subcommandDescription(cmd) {
         return cmd.summary() || cmd.description();
     }
@@ -115,6 +120,7 @@ export class Help {
             extraInfo.push(`choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
         }
         if (option.defaultValue !== undefined) {
+            // Defaults for boolean and negated are more for the programmer than the end user.
             const showDefault = option.required || option.optional || (option.isBoolean() && typeof option.defaultValue === 'boolean');
             if (showDefault)
                 extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
@@ -148,6 +154,7 @@ export class Help {
             return [];
         return [helper.styleTitle(heading), ...items, ''];
     }
+    /** Groups in order of first appearance among all items; members in order of the visible items. */
     groupItems(unsortedItems, visibleItems, getGroup) {
         const result = new Map();
         for (const item of unsortedItems) {
@@ -196,6 +203,7 @@ export class Help {
         }
         return output.join('\n');
     }
+    /** Width ignoring ANSI escapes, for padding and wrapping. */
     displayWidth(str) {
         return stripVTControlCharacters(str).length;
     }
@@ -203,6 +211,7 @@ export class Help {
         return str;
     }
     styleUsage(str) {
+        // Assume the default usage shape: command subcommand [options] [command] <foo> [bar]
         return str
             .split(' ')
             .map((word) => {
@@ -264,9 +273,15 @@ export class Help {
     padWidth(cmd, helper) {
         return Math.max(helper.longestOptionTermLength(cmd, helper), helper.longestGlobalOptionTermLength(cmd, helper), helper.longestSubcommandTermLength(cmd, helper), helper.longestArgumentTermLength(cmd, helper));
     }
+    /** Manually wrapped text: a line break followed by whitespace. */
     preformatted(str) {
         return /\n[^\S\r\n]/.test(str);
     }
+    /**
+     * Pad the term and wrap the description, indenting the following lines:
+     *   TTT  DDD DDDD
+     *        DD DDD
+     */
     formatItem(term, termWidth, description, helper) {
         const itemIndent = 2;
         const itemIndentStr = ' '.repeat(itemIndent);
@@ -286,6 +301,7 @@ export class Help {
         }
         return itemIndentStr + paddedTerm + ' '.repeat(spacerWidth) + formattedDescription.replace(/\n/g, `\n${itemIndentStr}`);
     }
+    /** Wrap at whitespace, preserving existing line breaks; skipped below `minWidthToWrap`. */
     boxWrap(str, width) {
         if (width < this.minWidthToWrap)
             return str;
@@ -317,3 +333,4 @@ export class Help {
         return wrappedLines.join('\n');
     }
 }
+//# sourceMappingURL=help.js.map

package/dist/{commander-option.d.ts → commander/option.d.ts}

@@ -1,4 +1,4 @@
-import { type ParseArg } from './commander-argument.js';
+import { type ParseArg } from './argument.js';
 export declare class Option {
     flags: string;
     description: string;

package/dist/{commander-option.js → commander/option.js}

@@ -1,4 +1,5 @@
-import { InvalidArgumentError } from './commander-error.js';
+import {} from './argument.js';
+import { InvalidArgumentError } from './error.js';
 export class Option {
     flags;
     description;
@@ -24,6 +25,7 @@ export class Option {
         this.description = description || '';
         this.required = flags.includes('<');
         this.optional = flags.includes('[');
+        // `<value,...>` describes custom splitting of one argument, not a variadic option.
         this.variadic = /\w\.\.\.[>\]]$/.test(flags);
         const { shortFlag, longFlag } = splitOptionFlags(flags);
         this.short = shortFlag;
@@ -36,6 +38,7 @@ export class Option {
         this.defaultValueDescription = description;
         return this;
     }
+    /** Value used when the option appears without an option-argument. `parseArg` still runs. */
     preset(arg) {
         this.presetArg = arg;
         return this;
@@ -44,6 +47,7 @@ export class Option {
         this.conflictsWith = this.conflictsWith.concat(names);
         return this;
     }
+    /** Values implied for other options when this one is set and they are not. `parseArg` does not run on them. */
     implies(impliedOptionValues) {
         const newImplied = typeof impliedOptionValues === 'string' ? { [impliedOptionValues]: true } : impliedOptionValues;
         this.implied = Object.assign(this.implied ?? {}, newImplied);
@@ -86,6 +90,7 @@ export class Option {
             return this.long.replace(/^--/, '');
         return (this.short ?? '').replace(/^-/, '');
     }
+    /** camelCase key used on the options object; `--no-foo` shares `foo` with `--foo`. */
     attributeName() {
         return camelcase(this.negate ? this.name().replace(/^no-/, '') : this.name());
     }
@@ -96,10 +101,15 @@ export class Option {
     is(arg) {
         return this.short === arg || this.long === arg;
     }
+    /** Options are one of boolean, negated, required-argument or optional-argument. */
     isBoolean() {
         return !this.required && !this.optional && !this.negate;
     }
 }
+/**
+ * `--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 class DualOptions {
     positiveOptions = new Map();
     negativeOptions = new Map();
@@ -125,6 +135,7 @@ export class DualOptions {
 function camelcase(str) {
     return str.split('-').reduce((acc, word) => acc + (word[0] ?? '').toUpperCase() + word.slice(1));
 }
+/** Split `'-m,--mixed <value>'` into its short and long flags, failing noisily on anything else. */
 export function splitOptionFlags(flags) {
     let shortFlag;
     let longFlag;
@@ -136,8 +147,10 @@ export function splitOptionFlags(flags) {
         shortFlag = flagParts.shift();
     if (longFlagExp.test(head()))
         longFlag = flagParts.shift();
+    // Long then short. Rarely used but fine.
     if (!shortFlag && shortFlagExp.test(head()))
         shortFlag = flagParts.shift();
+    // Two long flags, like '--ws, --workspace': the supported way to have a shortish flag.
     if (!shortFlag && longFlagExp.test(head())) {
         shortFlag = longFlag;
         longFlag = flagParts.shift();
@@ -162,3 +175,4 @@ export function splitOptionFlags(flags) {
     }
     return { shortFlag, longFlag };
 }
+//# sourceMappingURL=option.js.map

package/dist/commander.d.ts

@@ -3,14 +3,14 @@
  * dependency on commander itself). Graded by commander's own suite; see
  * `.sdlc/intents/commander-compat/design.md` and `npm run compat`.
  */
-import { Argument } from './commander-argument.js';
-import { Command } from './commander-command.js';
-import { Option } from './commander-option.js';
-export { Argument, humanReadableArgName } from './commander-argument.js';
-export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HookEvent, type HookListener, type OutputConfiguration, type OutputContext, type ParseOptions, } from './commander-command.js';
-export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander-error.js';
-export { Help, type HelpContext } from './commander-help.js';
-export { DualOptions, Option } from './commander-option.js';
+import { Argument } from './commander/argument.js';
+import { Command } from './commander/command.js';
+import { Option } from './commander/option.js';
+export { Argument, humanReadableArgName } from './commander/argument.js';
+export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HookEvent, type HookListener, type OutputConfiguration, type OutputContext, type ParseOptions, } from './commander/command.js';
+export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander/error.js';
+export { Help, type HelpContext } from './commander/help.js';
+export { DualOptions, Option } from './commander/option.js';
 /** The root command, for programs that never construct their own. */
 export declare const program: Command;
 export declare const createCommand: (name?: string) => Command;

package/dist/commander.js

@@ -1,11 +1,11 @@
-import { Argument } from './commander-argument.js';
-import { Command } from './commander-command.js';
-import { Option } from './commander-option.js';
-export { Argument, humanReadableArgName } from './commander-argument.js';
-export { Command, useColor, } from './commander-command.js';
-export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander-error.js';
-export { Help } from './commander-help.js';
-export { DualOptions, Option } from './commander-option.js';
+import { Argument } from './commander/argument.js';
+import { Command } from './commander/command.js';
+import { Option } from './commander/option.js';
+export { Argument, humanReadableArgName } from './commander/argument.js';
+export { Command, useColor, } from './commander/command.js';
+export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander/error.js';
+export { Help } from './commander/help.js';
+export { DualOptions, Option } from './commander/option.js';
 export const program = new Command();
 export const createCommand = (name) => new Command(name);
 export const createOption = (flags, description) => new Option(flags, description);

package/dist/completions.js

@@ -14,7 +14,9 @@ function children(manifest, at) {
         .map((c) => nodeOf(manifest, c));
 }
 function nodeOf(manifest, c) {
-    const visible = Object.fromEntries(Object.entries(c.options).filter(([, spec]) => spec.hidden !== true));
+    const visible = Object.fromEntries(Object.entries(c.options)
+        .filter(([, spec]) => spec.hidden !== true)
+        .map(([name, spec]) => [name, spec.type === 'boolean' ? { ...spec, negatable: true } : spec]));
     const isRoot = c.path.length === manifest.rootPath.length;
     return {
         path: c.path.slice(manifest.rootPath.length),
@@ -40,7 +42,11 @@ function walk(root) {
     return out;
 }
 const sq = (s) => `'${s.replaceAll("'", "'\\''")}'`;
-const flags = (name, spec) => (spec.short === undefined ? [`--${kebab(name)}`] : [`-${spec.short}`, `--${kebab(name)}`]);
+const flags = (name, spec) => {
+    const long = `--${kebab(name)}`;
+    const spellings = spec.short === undefined ? [long] : [`-${spec.short}`, long];
+    return spec.negatable === true ? [...spellings, `--no-${kebab(name)}`] : spellings;
+};
 const takesValue = (spec) => spec.type !== 'boolean';
 const fname = (program, path) => `_${[program, ...path].join('_').replaceAll(/[^A-Za-z0-9_]/g, '_')}`;
 function bashCase(program, node) {
@@ -141,8 +147,13 @@ function fish(program, root) {
         const cond = sq(fishCondition(node));
         for (const c of node.children)
             lines.push(`complete -c ${program} -n ${cond} -f -a ${c.path[c.path.length - 1] ?? ''} -d ${sq(c.description)}`);
-        for (const [name, spec] of Object.entries(node.options))
-            lines.push(fishOption(program, cond, name, spec));
+        for (const [name, spec] of Object.entries(node.options)) {
+            lines.push(fishOption(program, cond, kebab(name), spec));
+            if (spec.negatable === true) {
+                const { short: _short, ...unshort } = spec;
+                lines.push(fishOption(program, cond, `no-${kebab(name)}`, unshort));
+            }
+        }
     }
     return `# ${program} completion for fish, generated by burgee — never runs ${program} on TAB.
 # Install: ${program} completion fish > ~/.config/fish/completions/${program}.fish

package/dist/execute.js

@@ -8,7 +8,7 @@ import { serveMcp } from './mcp.js';
 import { camel, kebab } from './names.js';
 import { nearestPackage } from './pkg.js';
 import { ConfigError, explain, resolve as resolveLayers } from './precedence.js';
-import { commandSchemaOf, schemaOf, summaryOf } from './schema.js';
+import { commandSchemaOf, machineJson, schemaOf, summaryOf } from './schema.js';
 import { checkDefinition, checkRelations, coerce, UsageError } from './validate.js';
 function helpFields(c) {
     const node = {};
@@ -116,6 +116,7 @@ function render(value) {
     }
     return String(value);
 }
+const NO = 'no-';
 function toParseConfig(specs, withConfig) {
     const config = { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' }, explain: { type: 'string' } };
     if (withConfig) {
@@ -128,11 +129,28 @@ function toParseConfig(specs, withConfig) {
             ...(spec.short === undefined ? {} : { short: spec.short }),
             ...(spec.multiple === true ? { multiple: true } : {}),
         };
+        if (spec.type === 'boolean')
+            config[`${NO}${kebab(name)}`] = { type: 'boolean' };
     }
     return config;
 }
-function canonical(values) {
-    return Object.fromEntries(Object.entries(values).map(([k, v]) => [camel(k), v]));
+function canonical(values, specs, tokens) {
+    const out = {};
+    const negatable = (key) => {
+        const bare = camel(key.startsWith(NO) ? key.slice(NO.length) : key);
+        return specs[bare]?.type === 'boolean' ? bare : '';
+    };
+    for (const [k, v] of Object.entries(values))
+        if (!k.startsWith(NO) || negatable(k) === '')
+            out[camel(k)] = v;
+    for (const token of tokens) {
+        if (token.kind !== 'option')
+            continue;
+        const bare = negatable(token.name);
+        if (bare !== '')
+            out[bare] = !token.name.startsWith(NO);
+    }
+    return out;
 }
 function packageLayer(pkg, name) {
     if (pkg === undefined || name === undefined)
@@ -195,18 +213,7 @@ function exitSignal(cause) {
     const code = cause?.code;
     return typeof code === 'number' && isExitCode(code) ? code : undefined;
 }
-const SINGLE_DASH_WORD = /^-([a-zA-Z][\w-]+)(?:=.*)?$/;
-function singleDashHint(argv) {
-    for (const token of argv) {
-        if (token === '--')
-            return undefined;
-        const found = SINGLE_DASH_WORD.exec(token);
-        if (found?.[1] !== undefined)
-            return `did you mean --${found[1]}? a single dash introduces one-letter options`;
-    }
-    return undefined;
-}
-function describeFailure(cause, argv) {
+async function describeFailure(cause, argv, node) {
     const signal = exitSignal(cause);
     if (signal !== undefined)
         return { code: signal, message: '', silent: true };
@@ -220,7 +227,12 @@ function describeFailure(cause, argv) {
         return { code: ExitCode.CONFIG, message, ...(cause.hint === undefined ? {} : { hint: cause.hint }) };
     }
     if (isParseArgsFailure(cause)) {
-        return { code: ExitCode.USAGE, message, hint: singleDashHint(argv) ?? 'run --help to see the available options' };
+        const explain = await import('./unknown-option.js');
+        const dash = explain.singleDashHint(argv);
+        if (dash !== undefined)
+            return { code: ExitCode.USAGE, message, hint: dash };
+        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}));
+        return { code: ExitCode.USAGE, message, hint: 'run --help to see the available options', ...better };
     }
     return { code: ExitCode.RUNTIME, message };
 }
@@ -246,13 +258,16 @@ export function beforeTerminator(argv) {
 function rootNode(manifest, root) {
     return manifest.find(root) ?? { path: root, options: {} };
 }
-function unresolved({ manifest, root, io: { width } }, argv, at) {
+function unresolved({ manifest, root, io }, argv, at) {
     const node = at ?? rootNode(manifest, root);
     const typed = argv.slice(node.path.length - root.length);
-    if (typed.length > 0 && HELP_FLAGS.has(typed[0] ?? ''))
-        return { text: renderHelp(manifest, node, { width }), code: ExitCode.OK };
+    const first = typed[0] ?? '';
+    if (typed.length > 0 && HELP_FLAGS.has(first))
+        return { text: renderHelp(manifest, node, { width: io.width }), code: ExitCode.OK };
+    if (first === '--version' || first === '-V')
+        return { text: `${versionOf(manifest, io)}\n`, code: ExitCode.OK };
     if (typed.length === 0)
-        return { text: renderHelp(manifest, node, { width }), code: ExitCode.USAGE };
+        return { text: renderHelp(manifest, node, { width: io.width }), code: ExitCode.USAGE };
     throw new UsageError(`unknown command "${typed[0] ?? ''}"`, 'run --help to see the available commands');
 }
 async function completion(manifest, argv, io) {
@@ -279,7 +294,7 @@ async function surface(manifest, argv, io) {
         return true;
     }
     if (head.includes('--schema')) {
-        io.out.write(`${JSON.stringify(schemaSurface(manifest, argv), null, 2)}\n`);
+        io.out.write(`${machineJson(schemaSurface(manifest, argv), head)}\n`);
         return true;
     }
     if (head[0] === '--mcp') {
@@ -305,7 +320,7 @@ async function surface(manifest, argv, io) {
 }
 const SCHEMA_BUDGET = 48_000;
 function schemaSurface(manifest, argv) {
-    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema'), manifest.rootPath);
+    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema' && !a.startsWith('--format=')), manifest.rootPath);
     if (node?.run !== undefined)
         return commandSchemaOf(node, manifest.rootPath);
     const full = schemaOf(manifest);
@@ -333,7 +348,7 @@ function versionOf(manifest, io) {
 }
 async function dispatch(manifest, { node, rest, name }, io) {
     const parsed = parseArgs({ args: rest, options: toParseConfig(node.options, manifest.config !== undefined), allowPositionals: true, strict: true, tokens: true });
-    const flags = canonical(parsed.values);
+    const flags = canonical(parsed.values, node.options, parsed.tokens);
     const json = flags.json === true;
     if (flags.help === true)
         return { json, text: renderHelp(manifest, node, { width: io.width }) };
@@ -389,7 +404,7 @@ function emit(io, outcome) {
     return io.exit(ExitCode.OK);
 }
 async function report(cause, { manifest, io, argv, json, name }) {
-    const failure = describeFailure(cause, argv);
+    const failure = await describeFailure(cause, argv, resolveCommand(manifest, argv) ?? undefined);
     if (failure.silent === true)
         return io.exit(failure.code);
     await manifest.fire('onError', name, {});

package/dist/schema.d.ts

@@ -77,3 +77,5 @@ export interface SchemaSummary {
 /** Above the budget (N13): every command by name and summary, and the drilling command for one in full. */
 export declare function summaryOf(manifest: Manifest, budget: number): SchemaSummary;
 export declare function schemaOf(manifest: Manifest): ProgramSchema;
+/** The machine document, compact unless a person asked for the readable one. */
+export declare const machineJson: (value: unknown, head: readonly string[]) => string;

package/dist/schema.js

@@ -114,3 +114,6 @@ export function schemaOf(manifest) {
         out.description = description;
     return out;
 }
+const JSON_PRETTY = '--format=json-pretty';
+const INDENT = 2;
+export const machineJson = (value, head) => JSON.stringify(value, null, head.includes(JSON_PRETTY) ? INDENT : 0);

package/dist/unknown-option.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `-foo=bar` means three short flags to a parser and one long flag to a person
+ * (citty #237). The more specific reading of the same argv, so it is offered first.
+ */
+export declare function singleDashHint(argv: readonly string[]): string | undefined;
+export declare function unknownOption(cause: unknown, declared: readonly string[]): {
+    message: string;
+    hint: string;
+} | undefined;

package/dist/unknown-option.js

@@ -0,0 +1,27 @@
+import { suggestSimilar } from './suggest.js';
+const UNKNOWN_OPTION = /^Unknown option '(?<flag>[^']+)'/u;
+const NEAREST = /--[\w-]+/u;
+const SINGLE_DASH_WORD = /^-(?<word>[a-zA-Z][\w-]+)(?:=.*)?$/u;
+export function singleDashHint(argv) {
+    for (const token of argv) {
+        if (token === '--')
+            return undefined;
+        const word = SINGLE_DASH_WORD.exec(token)?.groups?.['word'];
+        if (word !== undefined)
+            return `did you mean --${word}? a single dash introduces one-letter options`;
+    }
+    return undefined;
+}
+export function unknownOption(cause, declared) {
+    if (!(cause instanceof Error))
+        return undefined;
+    const flag = UNKNOWN_OPTION.exec(cause.message)?.groups?.['flag'];
+    if (flag === undefined)
+        return undefined;
+    const dashed = declared.map((option) => `--${option}`);
+    const near = NEAREST.exec(suggestSimilar(flag, dashed))?.[0];
+    return {
+        message: `unknown option ${flag}`,
+        hint: near === undefined ? 'run --help to see the available options' : `did you mean ${near}?`,
+    };
+}

package/dist/{yargs-burgee.d.ts → yargs/burgee.d.ts}

@@ -4,8 +4,8 @@
  * this module projects that snapshot into the manifest every surface reads (J7, J8).
  * Nothing here runs at parse time unless a burgee surface was asked for.
  */
-import { type Effects, type Manifest, type OptionSpec } from './manifest.js';
-import type { Positional } from './yargs-utils.js';
+import { type Effects, type Manifest, type OptionSpec } from '../manifest.js';
+import type { Positional } from './utils.js';
 /** What one yargs instance (the root, or a command's builder run on a scratch) registered. */
 export interface Snapshot {
     name: string;

package/dist/{yargs-burgee.js → yargs/burgee.js}

@@ -1,4 +1,11 @@
-import { camelCase } from './yargs-parser.js';
+/**
+ * burgee's additions on yargs syntax — the pure half. `yargs-factory.ts` snapshots what
+ * a program registered (options, descriptions, commands and their builders' results) and
+ * this module projects that snapshot into the manifest every surface reads (J7, J8).
+ * Nothing here runs at parse time unless a burgee surface was asked for.
+ */
+import {} from '../manifest.js';
+import { camelCase } from '../yargs-parser.js';
 const DEFER_PREFIX = '__yargsString__:';
 function describe(descriptions, key) {
     const raw = descriptions[key];
@@ -14,6 +21,7 @@ function typeOf(s, key) {
         return 'number';
     return 'string';
 }
+/** Options as the manifest describes them, on a null-prototype record keyed by the canonical camelCase name. */
 export function optionSpecs(s) {
     const specs = Object.create(null);
     const aliasOf = new Set();
@@ -68,6 +76,10 @@ function argumentsOf(s) {
         push(p, false);
     return out;
 }
+/**
+ * Project a snapshot into the manifest: the root, then every command as a child path.
+ * Plugin-contributed nodes survive re-projection, exactly as on the commander façade.
+ */
 export function projectManifest(manifest, root) {
     const contributed = manifest.commands.filter((c) => c.plugin !== undefined);
     manifest.commands.splice(0, manifest.commands.length, ...contributed);
@@ -90,6 +102,7 @@ export function projectManifest(manifest, root) {
     };
     visit(root, [root.name], root.description, undefined);
 }
+/** What a run prints for a handler's return value when the streams are injected. */
 export function render(value) {
     if (value === undefined || value === null)
         return '';
@@ -102,3 +115,4 @@ export function render(value) {
     }
     return `${JSON.stringify(value)}\n`;
 }
+//# sourceMappingURL=burgee.js.map

package/dist/{yargs-cliui.js → yargs/cliui.js}

@@ -1,3 +1,9 @@
+/**
+ * cliui 9 — the column layout yargs' usage renders through — with the string-width,
+ * strip-ansi and wrap-ansi it depends on, ported for `burgee/yargs`. The wrapping
+ * arithmetic is byte-for-byte the upstream's: yargs' usage tests compare whole help
+ * screens.
+ */
 const ANSI_PATTERN = '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))';
 export function stripAnsi(str) {
     return typeof str === 'string' ? str.replace(new RegExp(ANSI_PATTERN, 'g'), '') : str;
@@ -47,6 +53,7 @@ export function stringWidth(input) {
     }
     return width;
 }
+/** ansi-styles' open→close map, the part wrap-ansi reads. */
 function closeCode(code) {
     if (code === 1 || code === 2)
         return 22;
@@ -419,3 +426,4 @@ function alignCenter(str, width) {
 export function cliui(opts) {
     return new UI({ width: opts?.width || getWindowWidth(), wrap: opts?.wrap });
 }
+//# sourceMappingURL=cliui.js.map

package/dist/{yargs-command.d.ts → yargs/command.d.ts}

@@ -3,11 +3,11 @@
  * builder/handler pipeline, positionals and the default command — ported for
  * `burgee/yargs`.
  */
-import { type Middleware } from './yargs-middleware.js';
-import type { PlatformShim } from './yargs-shim.js';
-import type { UsageInstance } from './yargs-usage.js';
-import { type Positional } from './yargs-utils.js';
-import type { ValidationInstance } from './yargs-validation.js';
+import { type Middleware } from './middleware.js';
+import type { PlatformShim } from './shim.js';
+import type { UsageInstance } from './usage.js';
+import { type Positional } from './utils.js';
+import type { ValidationInstance } from './validation.js';
 export interface CommandHandler {
     original: string;
     description?: string | false | undefined;

package/dist/{yargs-command.js → yargs/command.js}

@@ -1,5 +1,10 @@
-import { applyMiddleware, commandMiddlewareFactory } from './yargs-middleware.js';
-import { isPromise, maybeAsyncResult, parseCommand } from './yargs-utils.js';
+/**
+ * yargs' command instance — `.command()` in its five shapes, `.commandDir()`, the
+ * builder/handler pipeline, positionals and the default command — ported for
+ * `burgee/yargs`.
+ */
+import { applyMiddleware, commandMiddlewareFactory } from './middleware.js';
+import { isPromise, maybeAsyncResult, parseCommand } from './utils.js';
 const DEFAULT_MARKER = /(^\*)|(^\$0)/;
 export function isYargsInstance(y) {
     return !!y && typeof y.getInternalMethods === 'function';
@@ -222,6 +227,7 @@ export class CommandInstance {
                         yargs.getInternalMethods().getUsageInstance().fail(null, error);
                     }
                     catch {
+                        // the failure was reported; yargs swallows the rethrow here
                     }
                 });
             }
@@ -412,3 +418,4 @@ function isCommandBuilderOptionDefinitions(builder) {
 export function isCommandHandlerDefinition(cmd) {
     return typeof cmd === 'object' && !Array.isArray(cmd);
 }
+//# sourceMappingURL=command.js.map

package/dist/{yargs-completion.d.ts → yargs/completion.d.ts}

@@ -2,9 +2,9 @@
  * yargs' completion — `--get-yargs-completions`, the custom completion function in its
  * three arities, and the bash/zsh script templates — ported for `burgee/yargs`.
  */
-import { type CommandInstance } from './yargs-command.js';
-import type { PlatformShim } from './yargs-shim.js';
-import type { UsageInstance } from './yargs-usage.js';
+import { type CommandInstance } from './command.js';
+import type { PlatformShim } from './shim.js';
+import type { UsageInstance } from './usage.js';
 export declare const completionShTemplate = "###-begin-{{app_name}}-completions-###\n#\n# yargs command completion script\n#\n# Installation: {{app_path}} {{completion_command}} >> ~/.bashrc\n#    or {{app_path}} {{completion_command}} >> ~/.bash_profile on OSX.\n#\n_{{app_name}}_yargs_completions()\n{\n    local cur_word args type_list\n\n    cur_word=\"${COMP_WORDS[COMP_CWORD]}\"\n    args=(\"${COMP_WORDS[@]}\")\n\n    # ask yargs to generate completions.\n    # see https://stackoverflow.com/a/40944195/7080036 for the spaces-handling awk\n    mapfile -t type_list < <({{app_path}} --get-yargs-completions \"${args[@]}\")\n    mapfile -t COMPREPLY < <(compgen -W \"$( printf '%q ' \"${type_list[@]}\" )\" -- \"${cur_word}\" |\n        awk '/ / { print \"\\\"\"$0\"\\\"\" } /^[^ ]+$/ { print $0 }')\n\n    # if no match was found, fall back to filename completion\n    if [ ${#COMPREPLY[@]} -eq 0 ]; then\n      COMPREPLY=()\n    fi\n\n    return 0\n}\ncomplete -o bashdefault -o default -F _{{app_name}}_yargs_completions {{app_name}}\n###-end-{{app_name}}-completions-###\n";
 export declare const completionZshTemplate = "#compdef {{app_name}}\n###-begin-{{app_name}}-completions-###\n#\n# yargs command completion script\n#\n# Installation: {{app_path}} {{completion_command}} >> ~/.zshrc\n#    or {{app_path}} {{completion_command}} >> ~/.zprofile on OSX.\n#\n_{{app_name}}_yargs_completions()\n{\n  local reply\n  local si=$IFS\n  IFS=$'\n' reply=($(COMP_CWORD=\"$((CURRENT-1))\" COMP_LINE=\"$BUFFER\" COMP_POINT=\"$CURSOR\" {{app_path}} --get-yargs-completions \"${words[@]}\"))\n  IFS=$si\n  if [[ ${#reply} -gt 0 ]]; then\n    _describe 'values' reply\n  else\n    _default\n  fi\n}\nif [[ \"'${zsh_eval_context[-1]}\" == \"loadautofunc\" ]]; then\n  _{{app_name}}_yargs_completions \"$@\"\nelse\n  compdef _{{app_name}}_yargs_completions {{app_name}}\nfi\n###-end-{{app_name}}-completions-###\n";
 type Done = (err: Error | null, completions: string[] | undefined) => void;

package/dist/{yargs-completion.js → yargs/completion.js}

@@ -1,5 +1,9 @@
-import { isCommandBuilderCallback } from './yargs-command.js';
-import { isPromise, parseCommand } from './yargs-utils.js';
+/**
+ * yargs' completion — `--get-yargs-completions`, the custom completion function in its
+ * three arities, and the bash/zsh script templates — ported for `burgee/yargs`.
+ */
+import { isCommandBuilderCallback } from './command.js';
+import { isPromise, parseCommand } from './utils.js';
 export const completionShTemplate = `###-begin-{{app_name}}-completions-###
 #
 # yargs command completion script
@@ -269,3 +273,4 @@ function isSyncCompletionFunction(fn) {
 function isFallbackCompletionFunction(fn) {
     return fn.length > 3;
 }
+//# sourceMappingURL=completion.js.map