burgee 0.3.0 → 0.5.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/contrast.d.ts

@@ -10,18 +10,14 @@
  * WCAG 2.2 sets 4.5:1 for body text and 3:1 for large text and for the parts of
  * a graphic you need in order to understand it. A logo's bars are the latter, so
  * 3:1 is the floor used here — see `AA`.
+ *
+ * The measuring is `roundel`'s, not ours. Colour is the layer below this one, and until
+ * 2026-09-09 both packages carried the same forty lines of WCAG luminance — identical
+ * constants, identical maths, differing only in which package name the hex error says.
+ * What is left here is the part that is actually about a burgee: which pairs of a flag's
+ * own colours have to clear the floor, and how to say so to a person running `burgee brand`.
  */
-/** The floors WCAG 2.2 sets, as ratios. */
-export declare const AA: {
-    /** Body text against its background. */
-    readonly TEXT: 4.5;
-    /** Large text, UI components, and meaningful parts of a graphic. */
-    readonly GRAPHIC: 3;
-};
-/** WCAG relative luminance. */
-export declare function luminance(hex: string): number;
-/** The WCAG contrast ratio between two colours. Order does not matter. */
-export declare function contrast(a: string, b: string): number;
+import { AA, contrast, luminance } from 'roundel/contrast';
 /** Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science. */
 export declare function mix(a: string, b: string, t: number): string;
 export interface ContrastFinding {
@@ -68,3 +64,5 @@ export interface AuditInput {
  * intrinsic pair and fails a ground has a page problem, not a logo problem.
  */
 export declare function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];
+/** Re-exported so a caller reading a burgee's contrast needs one import, not two. */
+export { AA, contrast, luminance };

package/dist/contrast.js

@@ -1,38 +1,6 @@
-export const AA = {
-    TEXT: 4.5,
-    GRAPHIC: 3,
-};
+import { AA, channels, contrast, luminance } from 'roundel/contrast';
 const SRGB_MAX = 255;
-const LINEAR_THRESHOLD = 0.03928;
-const LINEAR_DIVISOR = 12.92;
-const GAMMA_OFFSET = 0.055;
-const GAMMA_SCALE = 1.055;
-const GAMMA_EXPONENT = 2.4;
-const LUMA = { r: 0.2126, g: 0.7152, b: 0.0722 };
-const CONTRAST_OFFSET = 0.05;
-const RED_AT = 1;
-const GREEN_AT = 3;
-const BLUE_AT = 5;
-const HEX_PAIRS = [RED_AT, GREEN_AT, BLUE_AT];
 const HEX_RADIX = 16;
-const SHORT_HEX_LENGTH = 4;
-function channels(hex) {
-    const full = hex.length === SHORT_HEX_LENGTH
-        ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`
-        : hex;
-    if (!/^#[0-9a-fA-F]{6}$/.test(full))
-        throw new Error(`burgee: "${hex}" is not a hex colour`);
-    const parsed = HEX_PAIRS.map((i) => Number.parseInt(full.slice(i, i + 2), HEX_RADIX) / SRGB_MAX);
-    return parsed;
-}
-export function luminance(hex) {
-    const [r, g, b] = channels(hex).map((v) => v <= LINEAR_THRESHOLD ? v / LINEAR_DIVISOR : ((v + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT);
-    return LUMA.r * r + LUMA.g * g + LUMA.b * b;
-}
-export function contrast(a, b) {
-    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
-    return (hi + CONTRAST_OFFSET) / (lo + CONTRAST_OFFSET);
-}
 export function mix(a, b, t) {
     const [ca, cb] = [channels(a), channels(b)];
     const hex = ca
@@ -91,3 +59,4 @@ export function auditBurgee(brand, grounds = []) {
     }
     return findings;
 }
+export { AA, contrast, luminance };

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

@@ -42,10 +42,42 @@ export interface CommandSchema {
     plugin?: string;
     arguments: ArgumentSpec[];
     options: Record<string, OptionSpec>;
+    /**
+     * The constraints between options (S2/S6), which `validate.ts` already enforces and the
+     * schema did not publish. Without them an agent can only discover that `--a` conflicts
+     * with `--b` by sending both and reading exit 2 — a round trip per constraint, and under
+     * E1 an exit 2 means *rewrite the command*, so it may well send the same pair again.
+     *
+     * Omitted entirely when a command declares none, so a reader can tell "no constraints"
+     * from "constraints not published".
+     */
+    relations?: PublishedRelation[];
     examples: Example[];
     /** The arguments and options as one JSON Schema object — what an MCP tool call takes. */
     inputSchema: JsonSchema;
 }
+/**
+ * A relation as JSON can carry it.
+ *
+ * `implies` takes either another option's name or a **predicate over the values**, and a
+ * function cannot be published. `JSON.stringify` turns it into `null` without a word, which
+ * would hand an agent `["force", null]` and let it conclude the constraint is malformed
+ * rather than unevaluable. So a predicate becomes the string `"(predicate)"`: the pair is
+ * still visible, and what is missing says so.
+ */
+export type PublishedRelation = {
+    exactlyOneOf: readonly string[];
+} | {
+    atLeastOneOf: readonly string[];
+} | {
+    atMostOneOf: readonly string[];
+} | {
+    conflicts: readonly string[];
+} | {
+    implies: readonly [string, string];
+};
+/** The marker a predicate leaves behind. Not a name any option can have — it has parentheses. */
+export declare const PREDICATE = "(predicate)";
 export interface ProgramSchema {
     schemaVersion: 1;
     name: string;
@@ -77,3 +109,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

@@ -1,4 +1,11 @@
 import { kebab } from './names.js';
+export const PREDICATE = '(predicate)';
+function publishable(relation) {
+    if (!('implies' in relation))
+        return relation;
+    const [option, consequent] = relation.implies;
+    return { implies: [option, typeof consequent === 'function' ? PREDICATE : consequent] };
+}
 function argumentProperty(a) {
     const p = a.variadic === true ? { type: 'array', items: { type: 'string' } } : { type: 'string' };
     if (a.description !== undefined)
@@ -76,6 +83,8 @@ export function commandSchemaOf(node, root) {
         out.lazy = true;
     if (node.plugin !== undefined)
         out.plugin = node.plugin;
+    if (node.relations !== undefined && node.relations.length > 0)
+        out.relations = node.relations.map(publishable);
     return out;
 }
 export function runnable(manifest) {
@@ -114,3 +123,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;