burgee 0.7.1 → 0.9.0

package/dist/index.d.ts

@@ -4,15 +4,40 @@
  *
  * The public entry, and only that. The execution core lives in execute.ts so a
  * façade can import it without pulling this barrel.
+ *
+ * ## What is not here, and why (D-093, reversed on a measurement)
+ *
+ * This barrel used to re-export the value half of `help.ts`, `mcp.ts`, `schema.ts`,
+ * `plugin.ts`, `manifest.ts` and `seniority/precedence` as a convenience. A re-export is
+ * not free: it makes those modules live for every consumer of `burgee`, whether or not
+ * anything reads them. `execute.ts` loads each one behind an `await import()`, so the only
+ * thing keeping them on the startup path was this file.
+ *
+ * Measured 2026-09-21 with `--splitting --outdir` over the transitive closure of `import`
+ * statements — the initial load a consumer actually pays:
+ *
+ *   - `import { run } from 'burgee'` — **44,663 bytes**
+ *   - the same program against `execute.ts` directly — **31,047 bytes**
+ *   - cold start, `burgee ÷ cac` — **2.113 → 1.717**
+ *
+ * D-093 declined this split on a cold-start argument it did not have the number for. The
+ * number says 13,616 bytes and 19% of startup, so the split lands: every value moved here
+ * has a subpath of its own (`burgee/help`, `burgee/mcp`, `burgee/schema`, `burgee/plugin`,
+ * `burgee/config`), which is where a program that wants it should say so.
+ *
+ * **Every `type` stays.** A type re-export is erased and costs a consumer nothing, so the
+ * whole type surface is still importable from `burgee` and no typed program has to move.
  */
 export { ExitCode, isExitCode, type ExitCode as ExitCodeValue } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, type AnyCommand, type Command, type CommandContext, type InferOptions, type OptionSpecs, type Program, type RunOptions, type RunResult, } from './execute.js';
 export { checkCommand, checkDefinition } from './definition.js';
-export { camel, kebab, UsageError } from './validate.js';
+export { AuthError, camel, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent, type AgentProbe, type Detection } from './agent.js';
-export { renderHelp, type HelpOptions, type HelpTheme, type HelpToken } from './help.js';
-export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming, type Candidate, type Layers, type Provenance, type Resolution, type Source } from 'seniority/precedence';
-export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, type CommandSchema, type JsonSchema, type ProgramSchema, type SchemaSummary } from './schema.js';
-export { CONTRACT, definePlugin, PluginError, type PluginErrorCode } from './plugin.js';
-export { Manifest, type ArgumentSpec, type CommandNode, type Effects, type Example, type Hook, type LazyModule, type OptionSpec, type ActionRequiredSpec, type Plugin, type Relation, type RunContext, type StandardResult, type StandardSchemaV1, } from './manifest.js';
+export type { HelpOptions, HelpTheme, HelpToken } from './help.js';
+export type { Invoke, ServeOptions, Tool, ToolAnnotations } from './mcp.js';
+export type { Candidate, Layers, Provenance, Resolution, Source } from 'seniority/precedence';
+export type { CommandSchema, JsonSchema, ProgramSchema, SchemaSummary } from './schema.js';
+export type { PluginErrorCode } from './plugin.js';
+export type { 
+/** The class itself lives at `burgee/schema`; the *type* stays here so `defineProgram`'s return type is nameable. */
+Manifest, ArgumentSpec, CommandNode, Effects, Example, Hook, LazyModule, OptionSpec, ActionRequiredSpec, Plugin, Relation, RunContext, StandardResult, StandardSchemaV1, } from './manifest.js';

package/dist/index.js

@@ -1,11 +1,5 @@
 export { ExitCode, isExitCode } from './exit-code.js';
 export { defineCommand, defineProgram, execute, resolveCommand, run, runCommand, sharedOptions, } from './execute.js';
 export { checkCommand, checkDefinition } from './definition.js';
-export { camel, kebab, UsageError } from './validate.js';
+export { AuthError, camel, kebab, UsageError } from './validate.js';
 export { AGENT_PROBES, detectAgent } from './agent.js';
-export { renderHelp } from './help.js';
-export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';
-export { ConfigError, envName, explain, resolve, screaming } from 'seniority/precedence';
-export { commandSchemaOf, inputSchemaOf, schemaOf, summaryOf } from './schema.js';
-export { CONTRACT, definePlugin, PluginError } from './plugin.js';
-export { Manifest, } from './manifest.js';

package/dist/mcp-entry.d.ts

@@ -0,0 +1,2 @@
+/** `burgee/mcp` — the MCP server, by itself. See `index.ts` for why it is not in the barrel. */
+export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, type Invoke, type ServeOptions, type Tool, type ToolAnnotations } from './mcp.js';

package/dist/mcp-entry.js

@@ -0,0 +1 @@
+export { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf } from './mcp.js';

package/dist/mcp.d.ts

@@ -2,9 +2,15 @@ import { type CommandNode, type Effects, type Manifest } from './manifest.js';
 import { type JsonSchema } from './schema.js';
 export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
 export interface ToolAnnotations {
-    readOnlyHint: boolean;
-    idempotentHint: boolean;
-    destructiveHint: boolean;
+    readOnlyHint?: boolean;
+    idempotentHint?: boolean;
+    destructiveHint?: boolean;
+    /**
+     * `'undeclared'`, and only ever that (G1). It appears on a command whose author said
+     * nothing — every commander and yargs command that did not call `.effects()` — and never
+     * beside a hint, because a hint is what a declaration produces.
+     */
+    effects?: 'undeclared';
 }
 export interface Tool {
     name: string;
@@ -18,20 +24,34 @@ export type Invoke = (argv: string[]) => Promise<{
     stderr: string;
     code: number;
 }>;
-/** MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration. */
-export declare function annotationsOf(effects: Effects): ToolAnnotations;
+/**
+ * MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration.
+ *
+ * No declaration returns no hints (G1). That is not a gap: MCP defines a default for each of
+ * the three — `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false` — so an
+ * absent hint already reads as *assume the worst*, in the client's own vocabulary and without
+ * burgee inventing a value it has no basis for. `effects: 'undeclared'` is the positive half:
+ * this command is not a `read_only` one, and it is not a `withheld` one either — nobody said.
+ */
+export declare function annotationsOf(effects?: Effects): ToolAnnotations;
 /** `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`. */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
 /**
- * The tool list: every runnable, visible command that declared what running it does.
+ * The tool list: every runnable, visible command an author has not withheld.
+ *
+ * One word is absent and one is not, and until 2026-09-21 they were the same thing. An
+ * author who wrote `'withheld'` thought about it and said no; that is what the word is for
+ * and it still means absent. An author who wrote nothing — which on burgee's own API
+ * `checkCommand` refuses, and which **every** command built through the commander or yargs
+ * façade is, because neither incumbent has a notion of effects and neither can be made to
+ * acquire one without breaking the suites that grade the façades — was treated the same way,
+ * so a migrated user's whole program was silently not a tool.
  *
- * Two commands are absent and for different reasons. One declared `'withheld'` — an author
- * who thought about it and said no, which is what that word is for. The other has no
- * `effects` at all, which `checkCommand` now refuses at declaration, so on burgee's own API
- * it cannot reach here; a command built through the commander or yargs façade still can,
- * because neither incumbent has a notion of effects and neither can be made to acquire one
- * without breaking the suites that grade the façades. The filter treats both as *not a
- * tool*, which is the same conservative reading it always had.
+ * Reading silence as refusal was conservative and it was also the thing standing between the
+ * product and its own pitch. Absent-from-the-list is strictly worse for the caller than
+ * present-with-honest-annotations: an agent that cannot see a command cannot decide about it,
+ * and cannot ask. So an undeclared command is listed and says so — see {@link annotationsOf}
+ * for why it carries no hints rather than a reassuring default.
  */
 export declare function toolsOf(manifest: Manifest): Tool[];
 /** A tool call's arguments back into argv: the command, its options, `--json`, then positionals in declared order. */

package/dist/mcp.js

@@ -6,6 +6,8 @@ const JSON_RPC_INVALID_REQUEST = -32600;
 const JSON_RPC_METHOD_NOT_FOUND = -32601;
 const JSON_RPC_INVALID_PARAMS = -32602;
 export function annotationsOf(effects) {
+    if (effects === undefined)
+        return { effects: 'undeclared' };
     return {
         readOnlyHint: effects === 'read_only',
         idempotentHint: effects !== 'non_idempotent',
@@ -21,7 +23,7 @@ function describe(node) {
 }
 export function toolsOf(manifest) {
     return runnable(manifest)
-        .filter((c) => c.effects !== undefined && c.effects !== WITHHELD)
+        .filter((c) => c.effects !== WITHHELD)
         .map((c) => ({ name: toolName(c, manifest.rootPath), description: describe(c), inputSchema: inputSchemaOf(c), annotations: annotationsOf(c.effects) }));
 }
 function optionArgs(node, args) {
@@ -59,8 +61,7 @@ async function callTool(session, params) {
     const given = params ?? {};
     const raw = given['name'];
     const name = typeof raw === 'string' ? raw : '';
-    const exposed = new Set(toolsOf(manifest).map((t) => t.name));
-    const node = exposed.has(name) ? runnable(manifest).find((c) => toolName(c, root) === name) : undefined;
+    const node = runnable(manifest).find((c) => c.effects !== WITHHELD && toolName(c, root) === name);
     if (node === undefined)
         return { error: { code: JSON_RPC_INVALID_PARAMS, message: `unknown tool "${name}"` } };
     const args = (given['arguments'] ?? {});

package/dist/meow/parse.d.ts

@@ -0,0 +1,21 @@
+import { type AnyFlag, type Options } from './types.js';
+/** Where a command run's parent arguments end and the child's begin. */
+export interface Split {
+    parent: string[];
+    input: string[];
+    command?: string;
+    unknownCommand?: string;
+}
+/** Every flag name a caller may write, and the canonical name each maps to. */
+export declare function aliasMap(flags: Record<string, AnyFlag>): Record<string, string[]>;
+export declare function typeofDefault(value: unknown): 'string' | 'boolean' | 'number' | undefined;
+/**
+ * Where the parent's arguments end and the command's begin.
+ *
+ * The first token the parser reads as positional is the command word; everything after it in
+ * the *raw* argv is the child's, unparsed. `--` is not a fence here — the suite states that
+ * `-- --unknown run` reports `Unknown command: --unknown`, so a post-separator word is a
+ * candidate command like any other.
+ */
+export declare function splitAtCommand(argv: string[], parserOptions: Record<string, unknown>, opts: Options): Split;
+/** stderr and exit 2 — how meow ends a run the flags do not support. */

package/dist/meow/parse.js

@@ -0,0 +1,43 @@
+import parser, { decamelize } from '../yargs-parser.js';
+export function aliasMap(flags) {
+    const out = {};
+    for (const [name, spec] of Object.entries(flags)) {
+        const names = [];
+        if (typeof spec.shortFlag === 'string')
+            names.push(spec.shortFlag);
+        if (typeof spec.alias === 'string')
+            names.push(spec.alias);
+        for (const extra of spec.aliases ?? [])
+            names.push(extra);
+        const decamelized = decamelize(name, '-');
+        if (decamelized !== name)
+            names.push(decamelized);
+        if (names.length > 0)
+            Object.defineProperty(out, name, { value: names, writable: true, enumerable: true, configurable: true });
+    }
+    return out;
+}
+export function typeofDefault(value) {
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'string')
+        return 'string';
+    if (Array.isArray(value))
+        return typeofDefault(value[0]);
+    return undefined;
+}
+export function splitAtCommand(argv, parserOptions, opts) {
+    const probe = parser.detailed(argv, parserOptions);
+    const first = probe.argv['_'][0];
+    if (first === undefined)
+        return { parent: argv, input: [] };
+    const word = String(first);
+    const at = argv.indexOf(word);
+    const parent = at === -1 ? argv : argv.slice(0, at);
+    const input = at === -1 ? [] : argv.slice(at + 1);
+    if (!(opts.commands ?? []).includes(word))
+        return { parent, input, unknownCommand: word };
+    return { parent, input, command: word };
+}

package/dist/meow/present.d.ts

@@ -0,0 +1,35 @@
+import { type Options } from './types.js';
+/** The nearest `package.json` above the caller's module, which is what `importMeta` is for. */
+/** The nearest `package.json` above the caller's module, which is what `importMeta` is for. */
+export declare function readPackageUp(importMeta: ImportMeta | undefined): Record<string, unknown>;
+/**
+ * meow's help block.
+ *
+ * Indented by `helpIndent` (2 by default) — but only when there is more than one line to
+ * indent, which is why `{description: false, help: 'single line'}` comes back flush. The
+ * suite states both shapes and they disagree about the indent, not about the text.
+ */
+/**
+ * meow's help block.
+ *
+ * Indented by `helpIndent` (2 by default) — but only when there is more than one line to
+ * indent, which is why `{description: false, help: 'single line'}` comes back flush. The
+ * suite states both shapes and they disagree about the indent, not about the text.
+ */
+export declare function buildHelp(options: Options, pkg: Record<string, unknown>): string;
+/** `common-tags`' `stripIndent`, for the template literals meow's callers write help in. */
+/** `common-tags`' `stripIndent`, for the template literals meow's callers write help in. */
+export declare function stripIndent(text: string): string;
+/** Every flag name a caller may write, and the canonical name each maps to. */
+/**
+ * The half of `normalize-package-data` meow's callers can see.
+ *
+ * `bin` as a string becomes `{ [name]: path }` — the suite reads `cli.pkg.bin['browser-sync']`
+ * — and an absent `version` becomes `''`. A copy, because `pkg normalization is lazy` asserts
+ * the object the caller passed in is untouched.
+ */
+export declare function normalizePackage(pkg: Record<string, unknown>): Record<string, unknown>;
+/** meow renames the process after the binary it is, which `ps` and a crash report both read. */
+/** meow renames the process after the binary it is, which `ps` and a crash report both read. */
+export declare function setProcessTitle(pkg: Record<string, unknown>): void;
+/** An own property under a key the caller chose — never the prototype setter. */

package/dist/meow/present.js

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { host } from '../runtime.js';
+const indent = (text, spaces) => text.replace(/^(?!\s*$)/gmu, ' '.repeat(spaces));
+export function readPackageUp(importMeta) {
+    if (importMeta?.url === undefined)
+        return {};
+    let dir = dirname(fileURLToPath(importMeta.url));
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        }
+        catch {
+            const up = dirname(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    return {};
+}
+export function buildHelp(options, pkg) {
+    const description = options.description === false ? '' : (options.description ?? pkg['description'] ?? '');
+    const body = options.help === false ? '' : stripIndent(options.help ?? '');
+    const parts = [description, body].filter((p) => p !== '');
+    if (parts.length === 0)
+        return '';
+    const text = parts.join('\n\n');
+    const width = options.helpIndent ?? 2;
+    return `\n${text.includes('\n') ? indent(text, width) : text}\n`;
+}
+export function stripIndent(text) {
+    const lines = text.split('\n');
+    const widths = lines.filter((l) => l.trim() !== '').map((l) => (/^(\s*)/u.exec(l)?.[1] ?? '').length);
+    const smallest = widths.length === 0 ? 0 : Math.min(...widths);
+    return lines
+        .map((l) => l.slice(smallest))
+        .join('\n')
+        .trim();
+}
+export function normalizePackage(pkg) {
+    const out = { ...pkg };
+    const name = typeof out['name'] === 'string' ? out['name'].replace(/^@[^/]+\//u, '') : undefined;
+    if (typeof out['bin'] === 'string' && name !== undefined)
+        out['bin'] = Object.fromEntries([[name, out['bin']]]);
+    if (out['version'] === undefined)
+        out['version'] = '';
+    return out;
+}
+export function setProcessTitle(pkg) {
+    const bin = pkg['bin'];
+    const first = typeof bin === 'object' && bin !== null ? Object.keys(bin)[0] : undefined;
+    const name = typeof pkg['name'] === 'string' ? pkg['name'].replace(/^@[^/]+\//u, '') : undefined;
+    const title = first ?? name;
+    if (title !== undefined && title !== '')
+        host.setTitle(title);
+}

package/dist/meow/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `burgee/meow` — the option and result shapes meow's callers write against.
+ *
+ * Kept beside the implementation rather than inside it because three files read them and a
+ * façade's contract is the part most worth seeing on its own.
+ */
+export interface AnyFlag {
+    type?: 'string' | 'boolean' | 'number';
+    alias?: string;
+    aliases?: string[];
+    shortFlag?: string;
+    default?: unknown;
+    isRequired?: boolean | ((flags: Record<string, unknown>, input: string[]) => boolean);
+    isMultiple?: boolean;
+    choices?: unknown[];
+}
+export interface Options {
+    importMeta?: ImportMeta;
+    argv?: readonly string[];
+    description?: string | false;
+    help?: string | false;
+    version?: string | false;
+    autoHelp?: boolean;
+    autoVersion?: boolean;
+    helpIndent?: number;
+    flags?: Record<string, AnyFlag>;
+    pkg?: Record<string, unknown>;
+    input?: unknown;
+    inferType?: boolean;
+    booleanDefault?: boolean | null | undefined;
+    hardRejection?: boolean;
+    allowUnknownFlags?: boolean;
+    commands?: string[];
+}
+export interface Result {
+    input: string[];
+    flags: Record<string, unknown>;
+    unnormalizedFlags: Record<string, unknown>;
+    pkg: Record<string, unknown>;
+    help: string;
+    version: string;
+    command?: string;
+    showHelp: (code?: number) => never;
+    showVersion: () => void;
+}
+/** An own property under a key the caller chose — never the prototype setter. */
+export declare function own(target: Record<string, unknown>, key: string, value: unknown): void;

package/dist/meow/types.js

@@ -0,0 +1,3 @@
+export function own(target, key, value) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}

package/dist/meow/validate.d.ts

@@ -0,0 +1,35 @@
+import { type AnyFlag, type Options } from './types.js';
+export declare function validateFlags(flags: Record<string, AnyFlag>): void;
+/** meow refuses to guess where the caller's `package.json` is. */
+/** meow refuses to guess where the caller's `package.json` is. */
+export declare function requireImportMeta(importMeta: ImportMeta | undefined): void;
+/** meow, over burgee's parser. */
+/** `commands` is an array of bare words, and meow says so in three different sentences. */
+export declare function validateCommands(commands: string[] | undefined): void;
+/**
+ * Where the parent's arguments end and the command's begin.
+ *
+ * The first token the parser reads as positional is the command word; everything after it in
+ * the *raw* argv is the child's, unparsed. `--` is not a fence here — the suite states that
+ * `-- --unknown run` reports `Unknown command: --unknown`, so a post-separator word is a
+ * candidate command like any other.
+ */
+export declare function checkChoices(specs: Record<string, AnyFlag>, flags: Record<string, unknown>): void;
+export declare function checkRequired(specs: Record<string, AnyFlag>, flags: Record<string, unknown>, input: string[]): void;
+export declare function checkUnknown(specs: Record<string, AnyFlag>, parsedFlags: Record<string, unknown>, argv: string[], opts: Options): void;
+/** `commands` is an array of bare words, and meow says so in three different sentences. */
+/** meow's `input` option may demand positionals, as a boolean or as a predicate. */
+export declare function checkInput(opts: Options, input: string[], flags: Record<string, unknown>): void;
+/** A flag declared once may be given once — the parser collects repeats into an array. */
+/** A flag declared once may be given once — the parser collects repeats into an array. */
+export declare function checkSetOnce(specs: Record<string, AnyFlag>, parsed: Record<string, unknown>): void;
+/**
+ * The half of `normalize-package-data` meow's callers can see.
+ *
+ * `bin` as a string becomes `{ [name]: path }` — the suite reads `cli.pkg.bin['browser-sync']`
+ * — and an absent `version` becomes `''`. A copy, because `pkg normalization is lazy` asserts
+ * the object the caller passed in is untouched.
+ */
+/** stderr and exit 2 — how meow ends a run the flags do not support. */
+export declare function reportAndExit(message: string): never;
+/** meow's `input` option may demand positionals, as a boolean or as a predicate. */

package/dist/meow/validate.js

@@ -0,0 +1,144 @@
+import { fileURLToPath } from 'node:url';
+import { ExitCode } from '../exit-code.js';
+import { host } from '../runtime.js';
+import { camelCase, decamelize } from '../yargs-parser.js';
+export function validateFlags(flags) {
+    const errors = [];
+    const kebab = Object.keys(flags).filter((name) => name.includes('-') && name !== '--');
+    if (kebab.length > 0)
+        errors.push(`Flag keys may not contain '-'. Invalid flags: ${kebab.map((k) => `\`${k}\``).join(', ')}`);
+    const renamed = Object.entries(flags).filter(([, spec]) => typeof spec.alias === 'string');
+    if (renamed.length > 0) {
+        errors.push(`The option \`alias\` has been renamed to \`shortFlag\`. The following flags need to be updated: ${renamed.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    const badChoices = Object.entries(flags).filter(([, spec]) => spec.choices !== undefined && !Array.isArray(spec.choices));
+    if (badChoices.length > 0) {
+        errors.push(`The option \`choices\` must be an array. Invalid flags: ${badChoices.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    for (const [name, spec] of Object.entries(flags)) {
+        if (spec.default === undefined || spec.type === undefined)
+            continue;
+        const values = Array.isArray(spec.default) ? spec.default : [spec.default];
+        const wrong = values.find((v) => typeof v !== spec.type);
+        if (wrong !== undefined)
+            errors.push(`Expected "${name}" default value to be of type "${String(spec.type)}", got "${typeof wrong}"`);
+    }
+    if (errors.length > 0)
+        throw new Error(`${errors.join('\n')}`);
+}
+export function requireImportMeta(importMeta) {
+    if (importMeta === undefined || typeof importMeta !== 'object' || typeof importMeta.url !== 'string') {
+        throw new TypeError('The `importMeta` option is required. Its value must be `import.meta`.');
+    }
+    try {
+        fileURLToPath(importMeta.url);
+    }
+    catch {
+        throw new TypeError('The `importMeta` option is required. Its value must be `import.meta`.');
+    }
+}
+export function validateCommands(commands) {
+    if (commands === undefined)
+        return;
+    if (!Array.isArray(commands))
+        throw new TypeError('The `commands` option must be an array of strings.');
+    if (commands.length === 0)
+        throw new TypeError('The `commands` option must contain at least one command.');
+    const bad = commands.some((c) => typeof c !== 'string' || c === '' || /\s/u.test(c) || c.startsWith('-'));
+    if (bad)
+        throw new TypeError('The `commands` option must be an array of non-empty strings without whitespace that do not start with `-`.');
+}
+export function checkChoices(specs, flags) {
+    const errors = [];
+    const badDefaults = Object.entries(specs).filter(([, spec]) => {
+        if (spec.default === undefined || !Array.isArray(spec.choices))
+            return false;
+        return (Array.isArray(spec.default) ? spec.default : [spec.default]).some((d) => !spec.choices?.includes(d));
+    });
+    if (badDefaults.length > 0) {
+        throw new Error(`Each value of the option \`default\` must exist within the option \`choices\`. Invalid flags: ${badDefaults.map(([n]) => `\`--${n}\``).join(', ')}`);
+    }
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.choices === undefined || !Array.isArray(spec.choices))
+            continue;
+        const label = `--${decamelize(name, '-')}`;
+        const allowed = `[${spec.choices.map((c) => `\`${String(c)}\``).join(', ')}]`;
+        const value = flags[name];
+        const required = typeof spec.isRequired === 'function' ? true : spec.isRequired === true;
+        if (value === undefined || value === '') {
+            if (required)
+                errors.push(`Flag \`${label}\` has no value. Value must be one of: ${allowed}`);
+            continue;
+        }
+        const values = Array.isArray(value) ? value : [value];
+        const bad = values.filter((v) => !spec.choices?.includes(v));
+        if (bad.length > 0) {
+            errors.push(`Unknown value${bad.length > 1 ? 's' : ''} for flag \`${label}\`: ${bad.map((b) => `\`${String(b)}\``).join(', ')}. Value must be one of: ${allowed}`);
+        }
+    }
+    if (errors.length > 0)
+        throw new Error(`${errors.join('\n')}`);
+}
+export function checkRequired(specs, flags, input) {
+    const missing = [];
+    for (const [name, spec] of Object.entries(specs)) {
+        let required = spec.isRequired;
+        if (typeof spec.isRequired === 'function') {
+            required = spec.isRequired(flags, input);
+            if (typeof required !== 'boolean') {
+                throw new TypeError(`Return value for isRequired callback should be of type boolean, but ${typeof required} was returned.`);
+            }
+        }
+        if (required !== true)
+            continue;
+        const value = flags[name];
+        if (value !== undefined && value !== '' && !(Array.isArray(value) && value.length === 0))
+            continue;
+        const short = typeof spec.shortFlag === 'string' ? `, -${spec.shortFlag}` : '';
+        missing.push(`--${decamelize(name, '-')}${short}`);
+    }
+    if (missing.length > 0) {
+        reportAndExit(`Missing required flag${missing.length > 1 ? 's' : ''}\n${missing.map((m) => `\t${m}`).join('\n')}`);
+    }
+}
+export function checkUnknown(specs, parsedFlags, argv, opts) {
+    const known = new Set(['--']);
+    if (opts.autoHelp !== false)
+        known.add('help');
+    if (opts.autoVersion !== false)
+        known.add('version');
+    for (const [name, spec] of Object.entries(specs)) {
+        known.add(name);
+        known.add(decamelize(name, '-'));
+        if (typeof spec.shortFlag === 'string')
+            known.add(spec.shortFlag);
+        if (typeof spec.alias === 'string')
+            known.add(spec.alias);
+    }
+    const unknown = Object.keys(parsedFlags).filter((k) => !known.has(k) && !known.has(camelCase(k)) && !known.has(decamelize(k, '-')));
+    if (unknown.length > 0) {
+        const names = unknown.map((u) => (u.length === 1 ? `-${u}` : `--${decamelize(u, '-')}`));
+        reportAndExit(`Unknown flag${names.length > 1 ? 's' : ''}\n${names.join('\n')}`);
+    }
+    void argv;
+}
+export function checkInput(opts, input, flags) {
+    if (typeof opts.input !== 'object' || opts.input === null)
+        return;
+    const spec = opts.input;
+    const required = typeof spec.isRequired === 'function' ? spec.isRequired(flags, input) : spec.isRequired === true;
+    if (required && input.length === 0)
+        reportAndExit('Missing required input');
+}
+export function checkSetOnce(specs, parsed) {
+    for (const [name, spec] of Object.entries(specs)) {
+        if (spec.isMultiple === true || name === '--')
+            continue;
+        if (Array.isArray(parsed[name]))
+            throw new Error(`The flag --${decamelize(name, '-')} can only be set once.`);
+    }
+}
+export function reportAndExit(message) {
+    host.stderr.write(`${message}\n`);
+    return host.exit(ExitCode.USAGE);
+}

package/dist/meow.d.ts

@@ -0,0 +1,6 @@
+import { type Options, type Result } from './meow/types.js';
+export { type AnyFlag, type Options, type Result } from './meow/types.js';
+/** meow, over burgee's parser. */
+declare function meow(helpText: string | Options, options?: Options): Result;
+declare const meowFacade: typeof meow;
+export default meowFacade;