burgee 0.7.1 → 0.9.0

package/README.md

@@ -141,6 +141,7 @@ Graded by the incumbent's own test suite:
 | suite | passing |
 | :-- | --: |
 | `commander` | 1360 / 1360 |
+| `meow` | 132 / 148 |
 | `yargs` | 804 / 804 |
 ## Where it sits
 

package/dist/check.d.ts

@@ -0,0 +1,22 @@
+import { ExitCode } from './exit-code.js';
+export interface CheckReport {
+    name: string;
+    commands: {
+        path: string;
+        description: string;
+        effects: string;
+    }[];
+    hooks: {
+        stage: 'preRun' | 'postRun' | 'onError';
+        applies: string;
+    }[];
+}
+export interface CheckRefusal {
+    refused: {
+        code: string;
+        message: string;
+        fix: string;
+    };
+    exitCode: ExitCode;
+}
+export declare function checkPlugin(file: string): Promise<CheckReport | CheckRefusal>;

package/dist/check.js

@@ -0,0 +1,35 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ExitCode } from './exit-code.js';
+import { Manifest } from './manifest.js';
+import { PluginError, validate } from './plugin.js';
+const STAGES = ['preRun', 'postRun', 'onError'];
+const refuse = (code, message, fix) => ({ refused: { code, message, fix }, exitCode: ExitCode.RUNTIME });
+export async function checkPlugin(file) {
+    const loaded = (await import(pathToFileURL(resolve(file)).href));
+    const plugin = loaded.default ?? loaded;
+    try {
+        validate(plugin, []);
+        new Manifest().use(plugin);
+    }
+    catch (error) {
+        if (error instanceof PluginError)
+            return refuse(error.code, error.message, error.fix);
+        if (error instanceof Error)
+            return refuse('E_PLUGIN_SCHEMA', error.message, 'fix the contributed command the message names; it is checked exactly as one of the program’s own');
+        throw error;
+    }
+    const { name, commands = [], hooks = {} } = plugin;
+    const report = {
+        name,
+        commands: commands.map((c) => ({ path: c.path.join(' '), description: c.description ?? '', effects: String(c.effects ?? 'undeclared') })),
+        hooks: STAGES.filter((stage) => hooks[stage] !== undefined).map((stage) => ({
+            stage,
+            applies: hooks[stage]?.filter?.command === undefined ? 'every command' : `commands matching ${String(hooks[stage]?.filter?.command)}`,
+        })),
+    };
+    if (report.commands.length === 0 && report.hooks.length === 0) {
+        return refuse('E_NO_CONTRIBUTION', `${name} registers, but contributes nothing burgee reads`, 'add `commands` or `hooks` — a key another package in the family reads is allowed in the same object, but `burgee check` cannot show it');
+    }
+    return report;
+}

package/dist/cli.d.ts

@@ -26,7 +26,7 @@ export declare const brandCommand: import("./execute.js").Command<{
         readonly type: "string";
         readonly description: "outline colour, hex. Omit for no outline";
     };
-    readonly 'bordure-width': {
+    readonly bordureWidth: {
         readonly type: "string";
         readonly default: "1.5";
         readonly description: "outline width";
@@ -43,7 +43,7 @@ export declare const brandCommand: import("./execute.js").Command<{
         readonly type: "string";
         readonly description: "page colour(s) the flag will fly on, comma separated. Checked for contrast";
     };
-    readonly 'allow-low-contrast': {
+    readonly allowLowContrast: {
         readonly type: "boolean";
         readonly description: "emit anyway when a contrast check fails. Says so in the output";
     };
@@ -54,9 +54,37 @@ export declare const brandCommand: import("./execute.js").Command<{
  * CLI's own weight and the framework's stay what they were (W4).
  */
 export declare const devCommand: import("./execute.js").Command<{
-    readonly 'no-watch': {
+    readonly noWatch: {
         readonly type: "boolean";
         readonly description: "load once and serve; do not watch for changes";
     };
 }>;
+/**
+ * `burgee migrate [dir]` — rewrite a commander or yargs project's imports to burgee's
+ * drop-in front-ends and report what changed, with the numbers that say why it was safe.
+ *
+ * The engine is loaded on this path only (K6), the same way `dev` is: a dynamic import, so
+ * `burgee`'s own start-up and the framework's weight are what they were. `weight.test.ts`
+ * denies `migrate.js` to the root entry by name, so that cannot drift back.
+ *
+ * `idempotent` is the honest answer rather than the conservative one, and it is earned:
+ * `burgee/commander` is not a key in the mapping, so a second run over a migrated tree
+ * rewrites nothing. N6 then requires the result to report `changed`, which it does.
+ */
+export declare const migrateCommand: import("./execute.js").Command<{
+    readonly dryRun: {
+        readonly type: "boolean";
+        readonly description: "scan and report; write nothing";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "migrate even though the git tree has uncommitted changes";
+    };
+}>;
+/**
+ * `burgee check <plugin-file>` — the feedback loop PRINCIPLES 7 asks every extension surface
+ * for, and the one burgee did not have. See `check.ts`: this one returns its report as data, so
+ * `--json` is the form an agent that just wrote a plugin reads.
+ */
+export declare const pluginCheckCommand: import("./execute.js").Command<import("./execute.js").OptionSpecs>;
 export declare const program: import("./manifest.js").Manifest;

package/dist/cli.js

@@ -44,14 +44,14 @@ export const brandCommand = defineCommand({
             description: 'path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box',
         },
         bordure: { type: 'string', description: 'outline colour, hex. Omit for no outline' },
-        'bordure-width': { type: 'string', default: DEFAULT_BORDURE_WIDTH, description: 'outline width' },
+        bordureWidth: { type: 'string', default: DEFAULT_BORDURE_WIDTH, description: 'outline width' },
         tagline: { type: 'string', description: 'one line under the name on the card and cover' },
         out: { type: 'string', description: 'directory to write into. Omit to print the flag only' },
         'on': {
             type: 'string',
             description: 'page colour(s) the flag will fly on, comma separated. Checked for contrast',
         },
-        'allow-low-contrast': {
+        allowLowContrast: {
             type: 'boolean',
             description: 'emit anyway when a contrast check fails. Says so in the output',
         },
@@ -68,7 +68,7 @@ export const brandCommand = defineCommand({
             : {
                 bordure: {
                     color: options.bordure,
-                    width: Number(options['bordure-width'] ?? DEFAULT_BORDURE_WIDTH),
+                    width: Number(options.bordureWidth ?? DEFAULT_BORDURE_WIDTH),
                 },
             };
         const brand = {
@@ -84,7 +84,7 @@ export const brandCommand = defineCommand({
             .filter((g) => g !== '');
         const findings = auditBurgee(brand, grounds);
         const failed = findings.filter((f) => !f.passes);
-        if (failed.length > 0 && options['allow-low-contrast'] !== true) {
+        if (failed.length > 0 && options.allowLowContrast !== true) {
             throw new Error(`contrast below WCAG AA:\n${report(failed)}\n${CONTRAST_HINT}`);
         }
         const written = surfaces(brand, options.tagline ?? '');
@@ -103,7 +103,7 @@ export const devCommand = defineCommand({
     description: 'Watch a CLI entry, reload it on change, and serve it as MCP on stdio while you write it',
     arguments: [{ name: 'entry', description: 'the module that exports the program, as program or as its default export', required: true }],
     options: {
-        'no-watch': { type: 'boolean', description: 'load once and serve; do not watch for changes' },
+        noWatch: { type: 'boolean', description: 'load once and serve; do not watch for changes' },
     },
     effects: 'withheld',
     run: async ({ positionals, options }) => {
@@ -111,13 +111,42 @@ export const devCommand = defineCommand({
         if (entry === undefined)
             throw new Error('an entry file is required');
         const [{ dev }, { processRuntime }] = await Promise.all([import('./dev.js'), import('./runtime.js')]);
-        const handle = dev({ entry, input: processRuntime.stdin, output: processRuntime.stdout, log: processRuntime.stderr, watch: options['no-watch'] !== true });
+        const handle = dev({ entry, input: processRuntime.stdin, output: processRuntime.stdout, log: processRuntime.stderr, watch: options.noWatch !== true });
         await handle.done;
     },
 });
+export const migrateCommand = defineCommand({
+    name: 'migrate',
+    description: 'Rewrite commander and yargs imports to burgee’s drop-in front-ends, and report what changed',
+    arguments: [{ name: 'dir', description: 'the project to migrate. Defaults to the current directory', required: false }],
+    options: {
+        dryRun: { type: 'boolean', description: 'scan and report; write nothing' },
+        force: { type: 'boolean', description: 'migrate even though the git tree has uncommitted changes' },
+    },
+    effects: 'idempotent',
+    examples: [
+        { command: 'burgee migrate --dry-run', description: 'what it would change, without changing it' },
+        { command: 'burgee migrate --json', description: 'the same report as data; exit 1 when anything was refused' },
+    ],
+    run: async ({ positionals, options }) => {
+        const [{ migrate }, { host }] = await Promise.all([import('./migrate.js'), import('./runtime.js')]);
+        return await migrate({ dir: positionals[0] ?? host.cwd(), dryRun: options.dryRun === true, force: options.force === true });
+    },
+});
+export const pluginCheckCommand = defineCommand({
+    name: 'check',
+    description: 'Validate a burgee plugin, register it into a throwaway program, and report what it contributes',
+    arguments: [{ name: 'file', description: 'the plugin module to check' }],
+    effects: 'read_only',
+    examples: [
+        { command: 'burgee check ./my-plugin.mjs', description: 'what the plugin contributes, or why it was refused' },
+        { command: 'burgee check ./my-plugin.mjs --json', description: 'the same, as data; exit 1 on a refusal' },
+    ],
+    run: async ({ positionals }) => (await import('./check.js')).checkPlugin(positionals[0] ?? ''),
+});
 export const program = defineProgram({
     name: 'burgee',
     description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand, devCommand],
+    commands: [brandCommand, devCommand, migrateCommand, pluginCheckCommand],
 });
 run(program);

package/dist/commander/argument.js

@@ -8,7 +8,6 @@ export class Argument {
     argChoices = undefined;
     required;
     _name;
-    /** `<required>`, `[optional]`, bare = required; a trailing `...` makes it variadic. */
     constructor(name, description) {
         this.description = description || '';
         switch (name[0]) {
@@ -67,9 +66,7 @@ export class Argument {
         return this;
     }
 }
-/** `<name>` / `[name]` / `<name...>` for usage strings. */
 export function humanReadableArgName(arg) {
     const nameOutput = arg.name() + (arg.variadic ? '...' : '');
     return arg.required ? `<${nameOutput}>` : `[${nameOutput}]`;
 }
-//# sourceMappingURL=argument.js.map

package/dist/commander/command.d.ts

@@ -72,6 +72,8 @@ interface SavedState {
 interface Burgee {
     exit: ((code: number) => void) | undefined;
     json: boolean;
+    /** One failure, one envelope (G5). */
+    reported?: boolean;
 }
 export declare class Command extends EventEmitter {
     commands: Command[];
@@ -244,6 +246,8 @@ export declare class Command extends EventEmitter {
     optsWithGlobals(): Record<string, unknown>;
     /** Display an error message and exit (or call exitOverride). */
     error(message: string, errorOptions?: ErrorOptions): never;
+    /** One failure as the envelope (E3, G5); `fix` only when one candidate was named. */
+    _reportJson(code: string, message: string): void;
     /** Apply environment variables to options that have no value from the cli or client code. */
     _parseOptionsEnv(): void;
     /** Apply implied option values where the option is undefined or at its default. */
@@ -328,15 +332,15 @@ export declare class Command extends EventEmitter {
      */
     _burgeeSurface(userArgs: string[]): boolean | Promise<boolean>;
     /** The surfaces after `completion`: `--schema` is synchronous, `--mcp` serves until stdin closes. */
-    _burgeeSurfaceRest(head: string[], declared: (flag: string) => boolean): boolean | Promise<boolean>;
+    _burgeeSurfaceRest(head: string[]): boolean | Promise<boolean>;
     /** Additive, and the point of the whole exercise: plugins commander has never had (#2505, unlanded). */
     use(plugin: Plugin): this;
     /** Inject the streams and the exit for one parse; returns commander's own parse options. */
     _prepareBurgee(parseOptions?: BurgeeParseOptions): ParseOptions | undefined;
     /** In burgee mode the whole run settles to one E1 exit; otherwise commander's behaviour, untouched. */
     _runBurgee(run: () => unknown): unknown;
-    /** `--json` that no command in the chain declared is burgee's envelope, not an unknown option. */
-    _takeJson(unknown: string[]): void;
+    /** Any command from here down declares this flag, so burgee does not serve it: additive only. */
+    _declares(flag: string): boolean;
     /** The action, wrapped in the plugin hooks and followed by the envelope or the rendering. */
     _runAction(): unknown;
     /** burgee (M5): once per process, on stderr; only for a command that asked, so commander's own output is untouched. */