burgee 0.6.1 → 0.7.1

package/README.md

@@ -14,7 +14,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/v/burgee?style=flat-square&color=0a6b47" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/dm/burgee?style=flat-square" alt="npm downloads" /></a>
-  <img src="https://img.shields.io/badge/runtime%20dependencies-0-0a6b47?style=flat-square" alt="Zero runtime dependencies" />
+  <img src="https://img.shields.io/badge/dependencies-5%20in--family-0a6b47?style=flat-square" alt="Five dependencies, all in this repository: bellpull, closeout, linegauge, roundel, seniority" />
   <img src="https://img.shields.io/badge/Node.js-24+-green.svg?style=flat-square" alt="Node.js 24+" />
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
 </p>
@@ -62,7 +62,7 @@ that on every commit.
 ```text
 defineCommand()  ──▶  manifest  ──┬──▶  human help
                                   ├──▶  --json      one stable envelope
-                                  ├──▶  --schema    versioned, JSON-Schema validated
+                                  ├──▶  --schema    versioned, one document per surface
                                   ├──▶  --mcp       an MCP server, generated
                                   ├──▶  completions bash · zsh · fish · pwsh
                                   ├──▶  TypeScript types
@@ -92,6 +92,25 @@ host's own suite passes 100%; below that the rate is published instead of claime
 | `burgee/commander` | The commander API, graded by commander's suite. |
 | `burgee/testing` | Run a command in-process and assert on its result — no spawning. |
 | `burgee/brand` | One brand declaration → flag, favicon, OG card, cover, lockup. The logo above is its own output. |
+| `burgee/plugin` | `definePlugin()`, `validate()`, `CONTRACT` and `PluginError` — the host, at the subpath every package in the family publishes its host at. |
+
+## Writing a plugin
+
+```ts
+import { definePlugin } from 'burgee/plugin';
+
+export default definePlugin({
+  name: 'acme',
+  commands: [{ path: ['audit'], description: 'Audit the tree', options: {}, effects: 'read_only', run: () => ({ findings: 0 }) }],
+});
+```
+
+A plugin's command is read by exactly the code a first-party one is read by, so the same
+refusals apply: reserved option names, duplicate flags, a contributed path that is already
+declared — and `effects`, which every runnable command declares. `definePlugin` stamps the
+`contract` this burgee was compiled against; an object that reaches `use()` without one is
+refused rather than accepted on trust, because burgee's extension point shipped before it
+validated anything.
 
 ## Status
 
@@ -112,3 +131,19 @@ what it is, [roundel](https://www.npmjs.com/package/roundel) carries its colours
 none requires the others.
 
 MIT © Ofri Peretz — see [LICENSE](./LICENSE).
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `commander` | 1360 / 1360 |
+| `yargs` | 804 / 804 |
+## Where it sits
+
+Plugins register under the `commands` and `hooks` keys, against the one schema the whole family shares.
+
+Nothing in this family builds on it yet, and it builds on `bellpull`, `closeout`, `linegauge`, `roundel`, `seniority`.

package/dist/cli.js

@@ -21,6 +21,7 @@ function surfaces(brand, tagline) {
 export const brandCommand = defineCommand({
     name: 'brand',
     description: 'Generate a burgee — flag, favicon, social card, cover and lockup — from two colours',
+    effects: 'non_idempotent',
     options: {
         lead: {
             type: 'string',
@@ -104,6 +105,7 @@ export const devCommand = defineCommand({
     options: {
         'no-watch': { type: 'boolean', description: 'load once and serve; do not watch for changes' },
     },
+    effects: 'withheld',
     run: async ({ positionals, options }) => {
         const [entry] = positionals;
         if (entry === undefined)

package/dist/commander/command.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from 'node:events';
 /**
  * commander's `Command`, ported method for method from commander 15 and graded by
  * commander's own suite through `compat-oracle`. The parse pipeline, the option
@@ -12,9 +13,8 @@
  *   - `parse(argv, { stdout, stderr, exit })` injects the streams and the exit, and
  *     then reports through the E1 taxonomy — the harness's seam (T1).
  */
-import childProcess from 'node:child_process';
-import { EventEmitter } from 'node:events';
-import { type Effects, Manifest, type OptionSpec, type Plugin } from '../manifest.js';
+import * as crossSpawn from 'bellpull/cross-spawn';
+import { type DeclaredEffects, Manifest, type OptionSpec, type Plugin } from '../manifest.js';
 import { Argument, type ParseArg } from './argument.js';
 import { CommanderError } from './error.js';
 import { Help } from './help.js';
@@ -85,7 +85,7 @@ export declare class Command extends EventEmitter {
     rawArgs: string[];
     /** like .args but after custom processing and collecting variadic */
     processedArgs: unknown[];
-    runningCommand: childProcess.ChildProcess | undefined;
+    runningCommand: crossSpawn.ChildProcess | undefined;
     _allowUnknownOption: boolean;
     _allowExcessArguments: boolean;
     _scriptPath: string | null;
@@ -126,7 +126,7 @@ export declare class Command extends EventEmitter {
     /** burgee: the root's projection, created on first use. */
     _manifest: Manifest | undefined;
     /** burgee: what this command does to the world (N6); declaring it exposes the command as an MCP tool. */
-    _effects: Effects | undefined;
+    _effects: DeclaredEffects | undefined;
     /** burgee: `true`, or the replacement's name (M5). Shown in help, schema and a one-line warning on use. */
     _deprecated: boolean | string | undefined;
     _deprecationWarned: boolean;
@@ -315,7 +315,7 @@ export declare class Command extends EventEmitter {
     /** Options as the manifest describes them, on a null-prototype record. */
     _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: Effects): this;
+    effects(value: DeclaredEffects): this;
     /**
      * burgee: mark the command deprecated (M5). Help and `--schema` show it; running it prints
      * `warning: 'old' is deprecated, use 'new'` on stderr once and goes on, exit unchanged.

package/dist/commander/command.js

@@ -1,3 +1,7 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
 /**
  * commander's `Command`, ported method for method from commander 15 and graded by
  * commander's own suite through `compat-oracle`. The parse pipeline, the option
@@ -12,15 +16,12 @@
  *   - `parse(argv, { stdout, stderr, exit })` injects the streams and the exit, and
  *     then reports through the E1 taxonomy — the harness's seam (T1).
  */
-import childProcess from 'node:child_process';
-import { EventEmitter } from 'node:events';
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { stripVTControlCharacters } from 'node:util';
+// eslint-disable-next-line import-next/no-namespace -- `spawn` is read off the namespace at the call site and never captured into a local. commander's own suite mocks `childProcess.spawn` in roughly 23 `executableSubcommand` cases, and a binding captured at import never re-syncs; bellpull's `cross-spawn.ts` reads `spawn` off its default import for this exact consumer, so a named import here would undo that and take the row from 1360 / 1360 to ungradeable.
+import * as crossSpawn from 'bellpull/cross-spawn';
 import { ExitCode } from '../exit-code.js';
 import { Manifest } from '../manifest.js';
 import { serveMcp } from '../mcp.js';
+import { host } from '../runtime.js';
 import { machineJson, schemaOf } from '../schema.js';
 import { suggestSimilar } from '../suggest.js';
 import { Argument, humanReadableArgName } from './argument.js';
@@ -132,13 +133,13 @@ export class Command extends EventEmitter {
         this._args = this.registeredArguments;
         this._name = name || '';
         this._outputConfiguration = {
-            writeOut: (str) => process.stdout.write(str),
-            writeErr: (str) => process.stderr.write(str),
+            writeOut: (str) => host.stdout.write(str),
+            writeErr: (str) => host.stderr.write(str),
             outputError: (str, write) => write(str),
-            getOutHelpWidth: () => (process.stdout.isTTY ? process.stdout.columns : undefined),
-            getErrHelpWidth: () => (process.stderr.isTTY ? process.stderr.columns : undefined),
-            getOutHasColors: () => useColor() ?? (process.stdout.isTTY && process.stdout.hasColors?.()),
-            getErrHasColors: () => useColor() ?? (process.stderr.isTTY && process.stderr.hasColors?.()),
+            getOutHelpWidth: () => (host.stdout.isTTY ? host.stdout.columns : undefined),
+            getErrHelpWidth: () => (host.stderr.isTTY ? host.stderr.columns : undefined),
+            getOutHasColors: () => useColor() ?? (host.stdout.isTTY && host.stdout.hasColors?.()),
+            getErrHasColors: () => useColor() ?? (host.stderr.isTTY && host.stderr.hasColors?.()),
             stripColor: (str) => stripVTControlCharacters(str),
         };
     }
@@ -335,7 +336,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             this._exitCallback(new CommanderError(exitCode, code, message));
             // Expecting this line is not reached.
         }
-        process.exit(exitCode);
+        return host.exit(exitCode);
     }
     // commander's contract: the positional args, then the options, then the command itself.
     action(fn) {
@@ -532,15 +533,15 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             throw new Error('first parameter to parse must be array or undefined');
         parseOptions = parseOptions ?? {};
         if (argv === undefined && parseOptions.from === undefined) {
-            if (process.versions['electron'])
+            if (host.versions['electron'])
                 parseOptions.from = 'electron';
-            const execArgv = process.execArgv ?? [];
+            const execArgv = host.execArgv ?? [];
             if (execArgv.includes('-e') || execArgv.includes('--eval') || execArgv.includes('-p') || execArgv.includes('--print')) {
                 parseOptions.from = 'eval'; // internal usage, not documented
             }
         }
         if (argv === undefined)
-            argv = process.argv;
+            argv = host.argv;
         this.rawArgs = argv.slice();
         let userArgs;
         switch (parseOptions.from) {
@@ -693,27 +694,37 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
             executableFile = localFile || executableFile;
         }
         const launchWithNode = SOURCE_EXT.includes(path.extname(executableFile));
+        // Through `bellpull`, not `node:child_process`: it resolves the executable properly on
+        // Windows, where upstream sends every spawn through `node` to dodge `PATHEXT`. The
+        // reasoning, the measurement and the mock constraint are in `weight.test.ts`'s
+        // `./commander` entry — they are prose, and prose in this file ships.
         let proc;
-        if (process.platform !== 'win32') {
+        if (host.platform !== 'win32') {
             if (launchWithNode) {
                 args.unshift(executableFile);
-                args = incrementNodeInspectorPort(process.execArgv).concat(args);
-                proc = childProcess.spawn(process.argv[0] ?? process.execPath, args, { stdio: 'inherit' });
+                args = incrementNodeInspectorPort(host.execArgv).concat(args);
+                proc = crossSpawn.spawn(host.argv[0] ?? host.execPath, args, { stdio: 'inherit' });
             }
             else {
-                proc = childProcess.spawn(executableFile, args, { stdio: 'inherit' });
+                proc = crossSpawn.spawn(executableFile, args, { stdio: 'inherit' });
             }
         }
         else {
             this._checkForMissingExecutable(executableFile, executableDir, subcommand._name);
-            args.unshift(executableFile);
-            args = incrementNodeInspectorPort(process.execArgv).concat(args);
-            proc = childProcess.spawn(process.execPath, args, { stdio: 'inherit' });
+            if (launchWithNode) {
+                args.unshift(executableFile);
+                args = incrementNodeInspectorPort(host.execArgv).concat(args);
+                proc = crossSpawn.spawn(host.execPath, args, { stdio: 'inherit' });
+            }
+            else {
+                // The case upstream cannot reach: a `.cmd`, a `.bat`, or a shebang that is not node.
+                proc = crossSpawn.spawn(executableFile, args, { stdio: 'inherit' });
+            }
         }
         if (!proc.killed) {
             // Testing mainly to avoid leak warnings during unit tests with mocked spawn.
             for (const signal of FORWARDED_SIGNALS) {
-                process.on(signal, () => {
+                host.on(signal, () => {
                     if (proc.killed === false && proc.exitCode === null)
                         proc.kill(signal);
                 });
@@ -723,7 +734,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
         proc.on('close', (code) => {
             code = code ?? 1; // null when the spawned process terminated due to a signal
             if (!exitCallback)
-                process.exit(code);
+                host.exit(code);
             else
                 exitCallback(new CommanderError(code, 'commander.executeSubCommandAsync', '(close)'));
         });
@@ -735,7 +746,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
                 throw new Error(`'${executableFile}' not executable`);
             }
             if (!exitCallback) {
-                process.exit(1);
+                host.exit(1);
             }
             else {
                 const wrappedError = new CommanderError(1, 'commander.executeSubCommandAsync', '(error)');
@@ -1113,12 +1124,12 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     /** Apply environment variables to options that have no value from the cli or client code. */
     _parseOptionsEnv() {
         for (const option of this.options) {
-            if (option.envVar && option.envVar in process.env) {
+            if (option.envVar && option.envVar in host.env) {
                 const optionKey = option.attributeName();
                 // Do not overwrite cli values or values from an unknown (client-code) source.
                 if (this.getOptionValue(optionKey) === undefined || ENV_SOURCES.includes(this.getOptionValueSource(optionKey) ?? '')) {
                     if (option.required || option.optional)
-                        this.emit(`optionEnv:${option.name()}`, process.env[option.envVar]);
+                        this.emit(`optionEnv:${option.name()}`, host.env[option.envVar]);
                     else
                         this.emit(`optionEnv:${option.name()}`);
                 }
@@ -1428,7 +1439,7 @@ Expecting one of '${HOOK_EVENTS.join("', '")}'`);
     /** Output help and exit. */
     help(contextOptions) {
         this.outputHelp(contextOptions);
-        let exitCode = Number(process.exitCode ?? 0);
+        let exitCode = Number(host.exitCode ?? 0);
         if (exitCode === 0 && contextOptions && typeof contextOptions !== 'function' && contextOptions.error)
             exitCode = 1;
         // message: not all displayed text is available, so only a placeholder is passed.
@@ -1574,7 +1585,7 @@ Expecting one of '${HELP_POSITIONS.join("', '")}'`);
                 await root.parseAsync(args, { from: 'user', stdout: { write: (s) => out.push(s) }, stderr: { write: (s) => err.push(s) }, exit: (c) => void (code = c) });
                 return { stdout: out.join(''), stderr: err.join(''), code };
             };
-            return serveMcp(this.manifest, { input: process.stdin, output: { write: (s) => root._outputConfiguration.writeOut(s) }, invoke }).then(() => true);
+            return serveMcp(this.manifest, { input: host.stdin, output: { write: (s) => root._outputConfiguration.writeOut(s) }, invoke }).then(() => true);
         }
         return false;
     }
@@ -1749,9 +1760,9 @@ function incrementNodeInspectorPort(args) {
  * and CLICOLOR_FORCE enable, otherwise undecided (the stream's TTY-ness decides).
  */
 export function useColor() {
-    if (process.env['NO_COLOR'] || process.env['FORCE_COLOR'] === '0' || process.env['FORCE_COLOR'] === 'false')
+    if (host.env['NO_COLOR'] || host.env['FORCE_COLOR'] === '0' || host.env['FORCE_COLOR'] === 'false')
         return false;
-    if (process.env['FORCE_COLOR'] || process.env['CLICOLOR_FORCE'] !== undefined)
+    if (host.env['FORCE_COLOR'] || host.env['CLICOLOR_FORCE'] !== undefined)
         return true;
     return undefined;
 }

package/dist/commander.d.ts

@@ -1,7 +1,7 @@
 /**
  * `burgee/commander` — commander's public surface, implemented over burgee (J9: no
  * dependency on commander itself). Graded by commander's own suite; see
- * `.sdlc/intents/commander-compat/design.md` and `npm run compat`.
+ * `.sdlc/intents/commander-compat/spec.md` and `npm run compat`.
  */
 import { Argument } from './commander/argument.js';
 import { Command } from './commander/command.js';

package/dist/completions.d.ts

@@ -26,6 +26,14 @@ interface FigOption {
         name: string;
         suggestions?: string[];
     };
+    /**
+     * Fig's own two keys for option relationships, spelled as Fig spells them:
+     * `dependsOn` keeps our name, `exclusive` becomes `exclusiveOn`. Both take the option's
+     * *spelling*, which is what Fig matches against on the command line — `fig-schema.test.ts`
+     * pins that these keys are ones `@withfig/autocomplete-types` declares on `Option`.
+     */
+    dependsOn?: string[];
+    exclusiveOn?: string[];
 }
 interface FigSubcommand {
     name: string;

package/dist/completions.js

@@ -1,4 +1,4 @@
-import { kebab } from './names.js';
+import { flagsOf, kebab } from './names.js';
 export const SHELLS = ['bash', 'zsh', 'fish', 'pwsh'];
 const GLOBAL = {
     json: { type: 'boolean', description: 'machine-readable output' },
@@ -201,6 +201,10 @@ function figOptions(node) {
             o.description = s.description;
         if (takesValue(s))
             o.args = { name: s.placeholder ?? 'value', ...(s.choices === undefined ? {} : { suggestions: [...s.choices] }) };
+        if (s.dependsOn !== undefined && s.dependsOn.length > 0)
+            o.dependsOn = flagsOf(s.dependsOn);
+        if (s.exclusive !== undefined && s.exclusive.length > 0)
+            o.exclusiveOn = flagsOf(s.exclusive);
         return o;
     });
 }

package/dist/definition.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What must be true of a command's declaration before it is added — whoever declared it.
+ *
+ * Split out of `validate.ts` on 2026-09-16, and the weight lock is what asked for it. That
+ * file holds two unrelated jobs: these checks, which run once when a program is built, and
+ * the run-time half — relations, numbers, choices, Standard Schema — which runs on every
+ * invocation and is four fifths of the bytes. Nothing minded while the only caller was
+ * `defineCommand`, because the engine carries both anyway.
+ *
+ * The plugin host is what made it matter. `Manifest.use()` has to run these checks, so
+ * `plugin.ts` imports them, so **every** graph that reaches the manifest now reaches them —
+ * and that includes the commander and yargs front-ends, which reach the manifest and nothing
+ * else of the engine. Importing `validate.js` for `checkDefinition` put 6,409 bytes of
+ * run-time coercion into both front-ends to get 1,600 bytes of definition checking, and took
+ * `./commander` over 128,000 — the budget that exists to prove the front-end is no heavier
+ * than commander's own `lib/`. One file per job, and the front-ends pay for the job they use.
+ */
+import { type OptionSpec } from './manifest.js';
+/**
+ * The fourth answer, which is not about the world: *this command is not offered to agents*.
+ *
+ * Exported because `mcp.ts` filters on it and a second spelling of a magic string is a
+ * second thing to keep in step. See `DeclaredEffects` in `manifest.ts` for why the word is
+ * `withheld` and not `none`.
+ */
+export declare const WITHHELD = "withheld";
+/**
+ * What must be true of a declaration before anything runs (yargs #1198, #887, #1679):
+ * a known type, one short alias per command, no two keys that meet on the command line.
+ */
+export declare function checkDefinition(name: string, options: Record<string, OptionSpec>): void;
+/**
+ * The whole door: the reserved names of V5, {@link checkDefinition}, and {@link checkEffects}.
+ *
+ * This exists as one function because it was two. `defineCommand` ran both; `Manifest.use()`
+ * ran neither, so a plugin's command was admitted unread — and a plugin option named `json`
+ * did not clash with the envelope flag, it replaced it in the parse config. The fix is not a
+ * second copy of the guard beside `use()`; it is that there is one guard and both callers
+ * reach it, which is the only arrangement a reader can check by looking.
+ *
+ * `effects` and `runs` are required rather than optional for exactly that reason. An optional
+ * third argument would be a check a caller can decline by writing nothing, which is the shape
+ * of the defect `checkEffects` exists to remove, one level up.
+ */
+export declare function checkCommand(name: string, options: Record<string, OptionSpec>, effects: unknown, runs: boolean): void;

package/dist/definition.js

@@ -0,0 +1,57 @@
+import { kebab } from './names.js';
+const TYPES = new Set(['string', 'boolean', 'number']);
+const EFFECTS = ['read_only', 'idempotent', 'non_idempotent'];
+export const WITHHELD = 'withheld';
+const DECLARED = [...EFFECTS, WITHHELD];
+const RESERVED = new Set(['json', 'help', 'schema', 'mcp', 'version', 'explain']);
+function checkRelationNames(name, key, spec, options) {
+    for (const field of ['dependsOn', 'exclusive']) {
+        for (const other of spec[field] ?? []) {
+            if (other !== key && other in options)
+                continue;
+            const why = other === key ? 'itself' : `not an option of "${name}"`;
+            throw new Error(`burgee: option "${key}" of "${name}" declares ${field} "${other}", which is ${why}`);
+        }
+    }
+}
+export function checkDefinition(name, options) {
+    const shorts = new Map();
+    const flags = new Map();
+    for (const [key, spec] of Object.entries(options)) {
+        if (!TYPES.has(spec.type))
+            throw new Error(`burgee: option "${key}" of "${name}" has unknown type "${String(spec.type)}"`);
+        if (spec.short !== undefined) {
+            const owner = shorts.get(spec.short);
+            if (owner !== undefined)
+                throw new Error(`burgee: options "${owner}" and "${key}" of "${name}" both use -${spec.short}`);
+            shorts.set(spec.short, key);
+        }
+        const flag = kebab(key);
+        const clash = flags.get(flag);
+        if (clash !== undefined)
+            throw new Error(`burgee: options "${clash}" and "${key}" of "${name}" are both --${flag}`);
+        flags.set(flag, key);
+        if ((spec.minimum !== undefined || spec.maximum !== undefined || spec.integer !== undefined) && spec.type !== 'number') {
+            throw new Error(`burgee: option "${key}" of "${name}" declares a numeric bound but is not a number`);
+        }
+        checkRelationNames(name, key, spec, options);
+    }
+}
+function checkEffects(name, effects, runs) {
+    if (effects === undefined) {
+        if (!runs)
+            return;
+        throw new Error(`burgee: command "${name}" is runnable and declares no effects; declare ${EFFECTS.join(', ')} — or ${WITHHELD}, which serves it to people and keeps it out of the MCP tool list`);
+    }
+    if (!DECLARED.includes(effects)) {
+        throw new Error(`burgee: command "${name}" declares effects ${JSON.stringify(effects)}, which is not an effects; use ${DECLARED.join(', ')}`);
+    }
+}
+export function checkCommand(name, options, effects, runs) {
+    for (const key of Object.keys(options)) {
+        if (RESERVED.has(key) || RESERVED.has(kebab(key)))
+            throw new Error(`burgee: option "${key}" is reserved and cannot be redefined`);
+    }
+    checkDefinition(name, options);
+    checkEffects(name, effects, runs);
+}

package/dist/execute.d.ts

@@ -1,4 +1,4 @@
-import { type ArgumentSpec, type CommandNode, type Effects, type Example, type LazyModule, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
+import { type ArgumentSpec, type CommandNode, type DeclaredEffects, type Example, type LazyModule, Manifest, type OptionSpec, type Relation, type RunContext } from './manifest.js';
 export interface CommandContext<O> extends Omit<RunContext, 'options'> {
     options: O;
 }
@@ -33,8 +33,17 @@ export interface Command<S extends OptionSpecs = OptionSpecs> {
     epilogue?: string;
     hidden?: boolean;
     deprecated?: boolean | string;
-    /** What running it does to the world (N6). Declaring it is what exposes the command as an MCP tool (N2). */
-    effects?: Effects;
+    /**
+     * What running it does to the world (N6). Declaring one of the three is what exposes the
+     * command as an MCP tool (N2); `'withheld'` declares that it is not offered to agents.
+     *
+     * Optional on the type and **required at definition time** on a command that runs:
+     * `defineCommand` refuses one that omits it. It stays optional here because a group that
+     * only holds subcommands declares none, and TypeScript cannot make a field's presence
+     * depend on a sibling's without splitting `Command` into a union that would cost the
+     * option-spec inference every caller of this type relies on.
+     */
+    effects?: DeclaredEffects;
     /** Relationships between options, validated before choices and the handler (S2, S6). */
     relations?: readonly Relation[];
     /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */