burgee 0.2.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/dev.d.ts

@@ -0,0 +1,47 @@
+import { Manifest } from './manifest.js';
+import { type Invoke } from './mcp.js';
+export interface Writer {
+    write: (s: string) => unknown;
+}
+export interface DevOptions {
+    /** The module that exports the program: `program` (or `default`) as a burgee manifest, a commander `Command` or a yargs instance. */
+    entry: string;
+    /** The MCP channel. */
+    input: NodeJS.ReadableStream;
+    output: Writer;
+    /** Where the reload report goes: never stdout, which carries MCP. */
+    log: Writer;
+    /** Off for tests that drive `reload()` themselves. */
+    watch?: boolean;
+    /** Files changed within this window coalesce into one reload. */
+    debounceMs?: number;
+}
+export interface Loaded {
+    manifest: Manifest;
+    invoke: Invoke;
+    kind: 'burgee' | 'commander' | 'yargs';
+    /** Milliseconds from the trigger to the manifest being served (W6). */
+    ms: number;
+}
+export interface DevHandle {
+    ready: Promise<Loaded>;
+    /** Re-import the entry, print the diff and the help, swap the served manifest. */
+    reload: () => Promise<Loaded>;
+    /** Settles when the MCP input closes. */
+    done: Promise<void>;
+    close: () => void;
+}
+/**
+ * Import the entry as a fresh module graph. The query is what discards the previous
+ * graph: the same URL would hand back the cached module and its stale handlers.
+ */
+export declare function load(entry: string, generation: number): Promise<Loaded>;
+/** What changed between two manifests, by command path: added, removed, or a different schema. */
+export declare function diffManifests(before: Manifest | undefined, after: Manifest): {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+/** The reload report: one save, every surface (W3). */
+export declare function report(before: Manifest | undefined, loaded: Loaded): string;
+export declare function dev(opts: DevOptions): DevHandle;

package/dist/dev.js

@@ -0,0 +1,132 @@
+import { watch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execute } from './execute.js';
+import { renderHelp } from './help.js';
+import { Manifest } from './manifest.js';
+import { startMcp, toolsOf } from './mcp.js';
+import { commandSchemaOf } from './schema.js';
+const DEFAULT_DEBOUNCE_MS = 50;
+const SOURCE = /\.(m?[jt]s|c[jt]s|json)$/;
+const isObject = (x) => x !== null && x !== undefined && typeof x === 'object' && !Array.isArray(x);
+function isManifest(x) {
+    return x instanceof Manifest || (isObject(x) && Array.isArray(x['commands']) && Array.isArray(x['rootPath']));
+}
+function isYargs(x) {
+    return isObject(x) && typeof x['burgee'] === 'function' && isObject(x['manifest']);
+}
+function isCommander(x) {
+    return isObject(x) && typeof x['parseAsync'] === 'function' && isObject(x['manifest']);
+}
+function invokeOn(program, kind, entry) {
+    return async (argv) => {
+        const out = [];
+        const err = [];
+        let code = 0;
+        const seam = { stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) };
+        if (kind === 'burgee')
+            await execute(program, { argv, from: 'user', entry, ...seam });
+        else if (kind === 'yargs')
+            await program.burgee(seam).parseAsync(argv);
+        else
+            await program.parseAsync(argv, { from: 'user', ...seam });
+        return { stdout: out.join(''), stderr: err.join(''), code };
+    };
+}
+export async function load(entry, generation) {
+    const started = performance.now();
+    const url = pathToFileURL(resolve(entry));
+    url.searchParams.set('burgee-dev', String(generation));
+    const mod = (await import(url.href));
+    const exported = mod['program'] ?? mod['default'];
+    if (isManifest(exported))
+        return { manifest: exported, invoke: invokeOn(exported, 'burgee', entry), kind: 'burgee', ms: performance.now() - started };
+    if (isYargs(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'yargs', entry), kind: 'yargs', ms: performance.now() - started };
+    if (isCommander(exported))
+        return { manifest: exported.manifest, invoke: invokeOn(exported, 'commander', entry), kind: 'commander', ms: performance.now() - started };
+    throw new Error(`${entry} exports no program: export a burgee manifest, a commander Command or a yargs instance as \`program\` or default`);
+}
+const schemasByPath = (m) => new Map(m.commands.map((c) => [c.path.join(' '), JSON.stringify(commandSchemaOf(c, m.rootPath))]));
+export function diffManifests(before, after) {
+    const was = before === undefined ? new Map() : schemasByPath(before);
+    const now = schemasByPath(after);
+    return {
+        added: [...now.keys()].filter((k) => !was.has(k)),
+        removed: [...was.keys()].filter((k) => !now.has(k)),
+        changed: [...now.keys()].filter((k) => was.has(k) && was.get(k) !== now.get(k)),
+    };
+}
+export function report(before, loaded) {
+    const { manifest } = loaded;
+    const diff = diffManifests(before, manifest);
+    const lines = [];
+    lines.push(`${before === undefined ? 'loaded' : 'reloaded'} ${manifest.rootPath.join(' ')} (${loaded.kind}) in ${loaded.ms.toFixed(0)} ms — ${manifest.commands.length} commands, ${toolsOf(manifest).length} MCP tools`);
+    for (const p of diff.added)
+        lines.push(`  + ${p}`);
+    for (const p of diff.removed)
+        lines.push(`  - ${p}`);
+    for (const p of diff.changed)
+        lines.push(`  ~ ${p}`);
+    const root = manifest.find(manifest.rootPath);
+    if (root !== undefined)
+        lines.push('', renderHelp(manifest, root).trimEnd());
+    return `${lines.join('\n')}\n`;
+}
+export function dev(opts) {
+    let generation = 0;
+    let current;
+    let server;
+    let watcher;
+    let timer;
+    let chain = Promise.resolve();
+    const entry = resolve(opts.entry);
+    const reloadNow = async () => {
+        generation += 1;
+        const loaded = await load(entry, generation);
+        opts.log.write(report(current, loaded));
+        current = loaded.manifest;
+        if (server === undefined)
+            server = startMcp(loaded.manifest, { input: opts.input, output: opts.output, invoke: loaded.invoke });
+        else
+            server.swap(loaded.manifest, loaded.invoke);
+        return loaded;
+    };
+    const reload = async () => {
+        await chain;
+        const next = reloadNow();
+        chain = next.catch((err) => {
+            opts.log.write(`reload failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+        return await next;
+    };
+    const ready = reload();
+    if (opts.watch !== false) {
+        watcher = watch(dirname(entry), { recursive: true }, (_event, filename) => {
+            const name = filename === null ? '' : String(filename);
+            if (name !== '' && (!SOURCE.test(name) || name.includes('node_modules')))
+                return;
+            clearTimeout(timer);
+            timer = setTimeout(() => void reload().catch(() => undefined), opts.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+        });
+    }
+    const untilInputCloses = async () => {
+        try {
+            await ready;
+            await server.done;
+        }
+        finally {
+            watcher?.close();
+        }
+    };
+    const done = untilInputCloses();
+    return {
+        ready,
+        reload,
+        done,
+        close: () => {
+            clearTimeout(timer);
+            watcher?.close();
+        },
+    };
+}

package/dist/execute.d.ts

@@ -1,4 +1,4 @@
-import { type ArgumentSpec, type Effects, type Example, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
+import { type ArgumentSpec, type CommandNode, type Effects, type Example, type LazyModule, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
 export interface CommandContext<O> extends Omit<RunContext, 'options'> {
     options: O;
 }
@@ -39,6 +39,8 @@ export interface Command<S extends OptionSpecs = OptionSpecs> {
     relations?: readonly Relation[];
     /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
     run?: (ctx: CommandContext<InferOptions<NoInfer<S>>>) => unknown;
+    /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */
+    load?: () => Promise<LazyModule>;
     commands?: AnyCommand[];
 }
 export interface Program {
@@ -59,6 +61,13 @@ export interface Program {
     commands: AnyCommand[];
 }
 export declare function defineCommand<const S extends OptionSpecs = OptionSpecs>(command: Command<S>): Command<S>;
+/**
+ * Options declared once and spread into each command that takes them (M4): never global,
+ * so `--schema` stays a tree and each command's help lists them as its own, and the
+ * handler's `options` type carries them like any other. Every copy is tagged
+ * `sharedFrom` with the set's name, so the schema says where it came from.
+ */
+export declare function sharedOptions<const T extends OptionSpecs>(name: string, specs: T): T;
 /** A native multi-command program. The manifest it builds is the same one the façades fill. */
 export declare function defineProgram(program: Program): Manifest;
 export interface RunOptions {
@@ -89,6 +98,18 @@ export declare function execute(manifest: Manifest, opts?: RunOptions & {
     root?: string[];
     from?: 'node' | 'user';
 }): Promise<void>;
+/** M6: which command argv names, or null — the same longest-prefix match `execute` uses. */
+export declare function resolveCommand(manifest: Manifest, argv: readonly string[]): CommandNode | null;
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * M6: run a command programmatically — the harness's own entry, public. The streams are
+ * captured, the exit recorded; env, cwd and the entry can be injected like `execute`'s.
+ */
+export declare function runCommand(manifest: Manifest, argv: readonly string[], opts?: Pick<RunOptions, 'env' | 'cwd' | 'entry' | 'stdin'>): Promise<RunResult>;
 /**
  * The one-file entry: a single command, or a program from `defineProgram`. Both go
  * through `execute`, so there is exactly one code path from argv to exit.