burgee 0.11.0 → 0.11.1

package/README.md

@@ -46,6 +46,7 @@ run(defineCommand({
   name: 'greet',
   description: 'Greet someone by name',
   options: { name: { type: 'string', required: true, description: 'who to greet' } },
+  effects: 'read_only', // what running it does to the world; required, and what --mcp reads
   run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
 }));
 ```
@@ -55,7 +56,7 @@ $ node cli.mjs --name ada
 greeting: hello, ada
 
 $ node cli.mjs --json --name ada
-{"ok":true,"data":{"greeting":"hello, ada"}}
+{"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}
 
 $ node cli.mjs            # exit 2
 error: missing required option --name
@@ -154,9 +155,11 @@ the declaration read by a different reader.
 
 ### How do I expose a CLI over MCP?
 
-Run it with `--mcp`: the same manifest is served as MCP tools over stdio. A command becomes
-a tool only when it declares its `effects` (`read_only`, `idempotent` or `non_idempotent`),
-so nothing reaches an agent by accident. Register it with any stdio client:
+Run it with `--mcp`: the same manifest is served as MCP tools over stdio. Every runnable
+command declares its `effects` — `read_only`, `idempotent` or `non_idempotent`, which become
+MCP's hints, or `withheld`, which keeps it out of the tool list — so nothing reaches an
+agent by accident. On `burgee/commander` and `burgee/yargs`, a command that declared
+nothing is still listed, marked `effects: 'undeclared'`. Register it with any stdio client:
 
 ```json
 { "mcpServers": { "mytool": { "command": "npx", "args": ["mytool", "--mcp"] } } }

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 export declare const brandCommand: import("./execute.js").Command<{
     readonly lead: {
         readonly type: "string";

package/dist/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_GROUND, defineBurgee, opposedField } from './brand.js';

package/dist/commander/command.d.ts

@@ -329,7 +329,17 @@ export declare class Command extends EventEmitter {
      */
     get manifest(): Manifest;
     _project(manifest: Manifest): void;
-    /** Options as the manifest describes them, on a null-prototype record. */
+    /**
+     * Options as the manifest describes them, on a null-prototype record — keyed so that the
+     * spelling every surface derives from a key, `--${kebab(key)}`, is a flag commander accepts.
+     *
+     * Commander negates only what it was told to, where burgee's own parser negates every
+     * boolean. So a boolean is `negatable` here only when the program declared its `--no-` twin,
+     * which folds onto it rather than appearing twice; and a `--no-x` declared alone, which has
+     * no `--x`, is described as the switch it is, under `noX`. Before this, `--no-color` was
+     * published as `color` with `flag: '--color'`: completions offered `--color` and
+     * `--no-skip-blank`, and `--mcp` sent `--color` — each refused by the parser behind them.
+     */
     _optionSpecs(): Record<string, OptionSpec>;
     /** burgee: declare what the command does to the world (N6). This is what exposes it as an MCP tool (N2). */
     effects(value: DeclaredEffects): this;

package/dist/commander/command.js

@@ -5,6 +5,7 @@ import { stripVTControlCharacters } from 'node:util';
 import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
+import { camel } from '../names.js';
 import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { suggestSimilar } from '../suggest.js';
@@ -1413,6 +1414,10 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
     _optionSpecs() {
         const specs = Object.create(null);
         for (const option of this.options) {
+            const name = option.attributeName();
+            const paired = this.options.some((o) => o.negate !== option.negate && o.attributeName() === name);
+            if (option.negate && paired)
+                continue;
             const spec = { type: option.required || option.optional ? 'string' : 'boolean' };
             if (option.description)
                 spec.description = option.description;
@@ -1424,7 +1429,9 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 spec.default = option.defaultValue;
             if (option.envVar)
                 spec.env = option.envVar;
-            Object.defineProperty(specs, option.attributeName(), { value: spec, enumerable: true, writable: true, configurable: true });
+            if (spec.type === 'boolean')
+                spec.negatable = paired;
+            Object.defineProperty(specs, option.negate ? camel(option.name()) : name, { value: spec, enumerable: true, writable: true, configurable: true });
         }
         return specs;
     }

package/dist/completions.js

@@ -16,7 +16,7 @@ function children(manifest, at) {
 function nodeOf(manifest, c) {
     const visible = Object.fromEntries(Object.entries(c.options)
         .filter(([, spec]) => spec.hidden !== true)
-        .map(([name, spec]) => [name, spec.type === 'boolean' ? { ...spec, negatable: true } : spec]));
+        .map(([name, spec]) => [name, { ...spec, negatable: spec.type === 'boolean' && spec.negatable !== false }]));
     const isRoot = c.path.length === manifest.rootPath.length;
     return {
         path: c.path.slice(manifest.rootPath.length),

package/dist/execute.js

@@ -127,7 +127,7 @@ function toParseConfig(specs, withConfig) {
             ...(spec.short === undefined ? {} : { short: spec.short }),
             ...(spec.multiple === true ? { multiple: true } : {}),
         };
-        if (spec.type === 'boolean')
+        if (spec.type === 'boolean' && spec.negatable !== false)
             config[`${NO}${kebab(name)}`] = { type: 'boolean' };
     }
     return config;
@@ -238,7 +238,7 @@ async function describeFailure(cause, argv, node) {
         const dash = explain.singleDashHint(argv);
         if (dash !== undefined)
             return { code: ExitCode.USAGE, message, hint: dash };
-        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}));
+        const better = explain.unknownOption(cause, Object.keys(node?.options ?? {}).map(kebab));
         return { code: ExitCode.USAGE, message, hint: 'run --help to see the available options', ...better };
     }
     return { code: ExitCode.RUNTIME, message };
@@ -505,7 +505,7 @@ export async function run(target, opts = {}) {
     manifest.rootPath = [target.name];
     manifest.add({
         path: [target.name],
-        ...(target.description === undefined ? {} : { description: target.description }),
+        ...helpFields(target),
         options: target.options ?? {},
         ...(target.run === undefined ? {} : { run: target.run }),
     });

package/dist/manifest.d.ts

@@ -78,6 +78,13 @@ export interface OptionSpec {
     /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
     deprecated?: boolean | string;
     hidden?: boolean;
+    /**
+     * `boolean` only: whether `--no-<name>` is accepted. Every boolean is negatable unless this
+     * says `false`. burgee's own parser negates every boolean (see `toParseConfig`); the
+     * commander façade sets `false` where commander would refuse the negation, so completions
+     * and `--mcp` never offer or send a flag the parser behind them rejects.
+     */
+    negatable?: boolean;
     /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
     sharedFrom?: string;
 }

package/dist/mcp.d.ts

@@ -34,7 +34,11 @@ export type Invoke = (argv: string[]) => Promise<{
  * 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_-]`. */
+/**
+ * `config get` → `config_get`: MCP tool names are `[a-zA-Z0-9_-]`, one character or more. A
+ * program whose root runs — a single `run(defineCommand(…))`, a commander program with a root
+ * `.action()` — has no typed name at all, so its tool is named after the program.
+ */
 export declare const toolName: (node: CommandNode, root: string[]) => string;
 /**
  * The tool list: every runnable, visible command an author has not withheld.

package/dist/mcp.js

@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline';
 import { WITHHELD } from './definition.js';
+import { kebab } from './names.js';
 import { inputSchemaOf, runnable, typedName } from './schema.js';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 const JSON_RPC_INVALID_REQUEST = -32600;
@@ -14,7 +15,7 @@ export function annotationsOf(effects) {
         destructiveHint: effects === 'non_idempotent',
     };
 }
-export const toolName = (node, root) => typedName(node, root).replaceAll(' ', '_');
+export const toolName = (node, root) => (typedName(node, root) || root.join(' ')).replaceAll(' ', '_');
 function describe(node) {
     const parts = [node.description ?? node.summary ?? ''];
     for (const e of node.examples ?? [])
@@ -32,12 +33,13 @@ function optionArgs(node, args) {
         const value = args[name];
         if (value === undefined || value === null)
             continue;
-        if (spec.type === 'boolean') {
-            if (value === true)
-                out.push(`--${name}`);
-        }
-        else
-            out.push(`--${name}`, String(value));
+        const flag = `--${kebab(name)}`;
+        if (spec.type !== 'boolean')
+            out.push(flag, String(value));
+        else if (value === true)
+            out.push(flag);
+        else if (value === false && spec.negatable !== false && (spec.default === true || spec.env !== undefined))
+            out.push(`--no-${kebab(name)}`);
     }
     return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "burgee",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "An agent-native CLI framework, drop-in compatible with commander and yargs. One declaration; help, --json, --schema, --mcp and completions all projected from it.",
   "license": "MIT",
   "type": "module",
@@ -146,11 +146,11 @@
     "provenance": true
   },
   "dependencies": {
-    "bellpull": "^0.3.0",
-    "closeout": "^0.5.0",
-    "linegauge": "^0.5.0",
-    "roundel": "^0.5.0",
-    "seniority": "^0.5.0"
+    "bellpull": "^0.3.1",
+    "closeout": "^0.5.1",
+    "linegauge": "^0.5.1",
+    "roundel": "^0.5.1",
+    "seniority": "^0.5.1"
   },
   "devDependencies": {
     "vitest": "^5.0.1"