Skip to content

Support OSC 8 hyperlinks in the help header (name/version) #20

@kjanat

Description

@kjanat

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:

  1. 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.
  2. Width helpers count raw .lengthpad() 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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions