burgee 0.7.1 → 0.8.0

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,31 @@ 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";
+    };
+}>;
 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,31 @@ 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 program = defineProgram({
     name: 'burgee',
     description: 'The agent-native CLI framework, and the tools that come with it',
-    commands: [brandCommand, devCommand],
+    commands: [brandCommand, devCommand, migrateCommand],
 });
 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. */