API reference
burgee/help
Every export of burgee/help, with its signature and doc comment: renderHelp, plus 3 types.
burgee/help — the help renderer, by itself. See index.ts for why it is not in the barrel.
import { renderHelp } from 'burgee/help';Functions
renderHelp
Render help for one node — a runnable command, a group, or both — as text.
Deterministic for a given node and width; a snapshot suite pins it. With color
off — the default — a theme changes nothing; with it on, only ANSI is added.
function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions & {
format?: 'text';
}): string;
function renderHelp(manifest: Manifest, node: CommandNode, opts: HelpOptions & {
format: 'markdown';
}): Promise<string>;| Parameter | Type |
|---|---|
manifest | Manifest |
node | CommandNode |
opts (optional) | HelpOptions & { format?: 'text'; } |
Returns string
Interfaces
HelpOptions
interface HelpOptions {
/** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
width?: number;
/** Show type hints such as `[string]`; off by default (H6). */
verbose?: boolean;
/** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
color?: boolean;
/**
* Replaces the default styling token by token; read only when `color` is on. See
* `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
*/
theme?: HelpTheme;
/**
* The commands to list, in place of the node's visible children: each by its path from the
* node, with what it takes (`config get <key>`), under the heading of the child it is reached
* through. The engine passes every command that runs when they fit (`listed` in `usage.ts`).
*/
commands?: readonly CommandNode[];
/**
* More rows for `Global options:`, after `--json`, `--help` and `--schema`: the global flags
* the engine parses for this command (`--color`, `--quiet`, `--timeout`; agent-lint-conformance
* R1–R3), passed in by the engine like `commands`, so this renderer carries none of their words.
*/
globals?: readonly {
term: string;
text: string;
}[];
/**
* The run's language (`localised-human-surfaces` R1): every heading, row text and the root's
* line for agents are passed through it once laid out in English (the node's own description
* arrives already in the run's language, R5). The engine hands in a pack's translator; absent,
* it is the identity, and help is byte-for-byte what it was.
*/
say?: (english: string) => string;
/**
* Words the engine adds to the root's line for agents: `AGENTS.md`, when one sits beside the
* binary (agent-skill R4). Passed in like `commands`, so this renderer looks for no file.
*/
forAgents?: string;
}Types
HelpTheme
Per-token styling for help (R7). A user who has roundel passes its tokens; a user
who does not gets the defaults. Help reads heading, command, flag and value;
the others are accepted so one theme object serves the whole output stack.
type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;HelpToken
The token names of roundel's R3, typed structurally: help never imports the tokens (U13).
type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';