Feature request
Allow the root-help header's first line (<name> v<version>) to carry OSC 8 hyperlinks, so a CLI can link its name → repo and its version → release tag — e.g. paperless-mcp → the repo and v2.4.0 → /releases/tag/v2.4.0.
Observed on @kjanat/dreamcli@2.1.0.
Why it's blocked today
The header is built in src/core/cli/root-help.ts:114:
const header = schema.version !== undefined ? `${schema.name} v${schema.version}` : schema.name;
Two issues prevent OSC 8 wrapping:
schema.name is reused in width-wrapped sections — the Usage: lines (root-help.ts:126), the Run '${schema.name} --help' hint (:89), binName (:57), and the Commands table. OSC 8-wrapping the name leaks the escape sequences into all of those, not just the header.
- Width helpers count raw
.length — pad() and wrapText() in src/core/help/index.ts measure with text.length, which counts the invisible OSC 8 bytes as visible columns, so --help wrapping/alignment mangles whenever escapes are present.
(The version alone is wrappable today via .version(osc8(url, v)) because it's header-only and the header line isn't wrapped — but the hardcoded v prefix sits outside the link, and the name still can't be linked.)
Proposed
Either or both:
- A header-only display field — e.g.
.displayName() or a header/banner option consumed only by formatRootHelp, excluded from binName, usage, commands, and the --help hint — so pre-formatted (OSC 8 / ANSI) text can be injected on just the first line.
- Make the width helpers ANSI/OSC-aware — a
visibleWidth() that strips escapes before .length, used by pad()/wrapText(). Useful on its own for any colored help output.
With both, [name](repo) v[version](release) on the header line becomes possible without corrupting the rest of --help.
Workaround
.version(osc8(releaseUrl, pkg.version)) links the version digits only.
Feature request
Allow the root-help header's first line (
<name> v<version>) to carry OSC 8 hyperlinks, so a CLI can link its name → repo and its version → release tag — e.g.paperless-mcp→ the repo andv2.4.0→/releases/tag/v2.4.0.Observed on
@kjanat/dreamcli@2.1.0.Why it's blocked today
The header is built in
src/core/cli/root-help.ts:114:Two issues prevent OSC 8 wrapping:
schema.nameis reused in width-wrapped sections — theUsage:lines (root-help.ts:126), theRun '${schema.name} --help'hint (:89),binName(:57), and the Commands table. OSC 8-wrapping the name leaks the escape sequences into all of those, not just the header..length—pad()andwrapText()insrc/core/help/index.tsmeasure withtext.length, which counts the invisible OSC 8 bytes as visible columns, so--helpwrapping/alignment mangles whenever escapes are present.(The version alone is wrappable today via
.version(osc8(url, v))because it's header-only and the header line isn't wrapped — but the hardcodedvprefix sits outside the link, and the name still can't be linked.)Proposed
Either or both:
.displayName()or aheader/banneroption consumed only byformatRootHelp, excluded frombinName, usage, commands, and the--helphint — so pre-formatted (OSC 8 / ANSI) text can be injected on just the first line.visibleWidth()that strips escapes before.length, used bypad()/wrapText(). Useful on its own for any colored help output.With both,
[name](repo) v[version](release)on the header line becomes possible without corrupting the rest of--help.Workaround
.version(osc8(releaseUrl, pkg.version))links the version digits only.