feat: public docgen command and binary spec discovery

[bhouston]

Closes #23

Adapters

ocobra and ourfave gain a WithPublicCommand(name) option that attaches a visible subcommand (e.g. docgen) alongside the hidden __opencli. Both commands share one implementation and now accept --format yaml|json in addition to -o/--out. Generator commands are marked via cobra Annotations / urfave Metadata so the tree walk skips them regardless of name.

ocobra.FromCommand(rootCmd, ocobra.WithPublicCommand("docgen"))

__opencli is unchanged and always attached, so existing users are unaffected.

ocli

ocli check, ocli gen docs, and ocli gen cli now accept a CLI binary in place of a spec file. When the path has no .json/.yaml/.yml extension and is executable, ocli runs <binary> __opencli first, then <binary> docgen, and uses the first document produced. This supports CLIs that expose only one of the two commands (clidoc, for instance, exposes both).

Spec loading for the three commands is consolidated into one helper, replacing three copies of the same stat/extension/read logic.

Docs and tests

• README adapter section documents the option and binary input.
• ocli.ocs.yaml argument descriptions updated; generated CLI code and docs regenerated.
• Tests: public command is visible, honours --format json, and is excluded from the document (both adapters); binary fallback to docgen; error listing tried commands.

go generate ./... and go test ./... pass.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 93.97590% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
adapters/ourfave/ourfave.go	90.00%	1 Missing and 1 partial ⚠️
internal/cli/app/actions.go	95.00%	2 Missing ⚠️
adapters/ocobra/ocobra.go	95.65%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[bcdxn]

As I've been thinking through this: I don't think I actually want ocli itself to execute a CLI binary to discover its OpenCLI document.

The original __opencli adapter was intended primarily as a bridge for existing/code-first CLIs to produce an OpenCLI document. Once you have that document, I want ocli or other tools in the ecosystem to operate on the document itself rather than needing to know how it was produced.

So I'm leaning toward keeping the flow explicit:

mycli __opencli > opencli.yaml
ocli gen docs --path opencli.yaml

It keeps a pretty clean separation between "produce an OpenCLI document" and "operate on an OpenCLI document." It also means --path always means a path to an OpenCLI document rather than sometimes a string path, sometimes a binary executable.

This way also makes me less concerned about whether we need to standardize a bunch of alternative discovery mechanisms. __opencli can simply be the machine-facing convention for adapters, while the actual OpenCLI tooling continues to consume the resulting document.

If you remove the public-command changes and instead add an option to customize the name of the existing __opencli command, while keeping __opencli as the default, I'm happy to accept the PR.