feat(agent-bff): emit the OpenAPI document from a forest-bff openapi subcommand

[Tonours]

Stacked on #1810 (feature/prd-886-openapi-static-document), which is itself stacked on #1809. The base is #1810's branch, not main: both parents must be reviewed and merged first, in order (#1809, then #1810, then this). The diff below is only this branch's commit.

Adds forest-bff openapi: writes the OpenAPI document to stdout without booting the server.

fixes PRD-887

Why a CLI at all

GET /agent/openapi.json is auth-gated, so a CI job, a codegen step, or a client dev without credentials has no HTTP path to the document. The CLI is that path. It needs no configuration, so it runs in a pipeline with no secrets:

forest-bff openapi > openapi.json

Behavior change on the packaged bin

Worth a look before merge. Previously forest-bff <anything> ignored argv and booted the server. Now argv is parsed:

Invocation	Before	After
forest-bff	boots the server	boots the server, unchanged
forest-bff openapi	booted the server	writes the document, exit 0
forest-bff --help / -h	booted the server	usage on stdout, exit 0
forest-bff --version / -v	booted the server	bare version on stdout, exit 0
forest-bff openapi extra	booted the server	exit 1, names the extra argument
forest-bff bogus	booted the server	exit 1, reason on stderr

--help and --version follow POSIX: a help request is not an error, so they print to stdout and exit 0. Failures print the reason on stderr with a one-line pointer to --help rather than dumping the whole usage.

A deployment that passed a stray flag and silently got a server will now fail on upgrade. The repo's own start scripts pass no arguments.

Scope and safety

The no-argv path is untouched: same runCli, same config parsing, same middleware chain. The export path never calls parseConfig, never constructs a logger, never binds a socket.

Hand-rolled argv switch in its own cli-dispatch.ts (74 lines), no arg-parsing dependency. cli-core.ts drops to 245 lines.

Stdout purity

An export piped to a file must contain only the document. This is easy to break silently: createConsoleLogger sends Info to console.info, which writes to stdout, not stderr. Any future log on the export path would corrupt every pipe without failing anything.

Verified byte-exactly rather than assumed: stdout is 48327 bytes, the serialized document is 48327 bytes. A test pins one single process.stdout.write call and asserts console.info is never reached.

How to test

yarn workspace @forestadmin/agent-bff test
yarn workspace @forestadmin/agent-bff lint

cd packages/agent-bff
env -i PATH="$PATH" node dist/cli.js openapi | npx @redocly/cli lint -   # valid, no config
node dist/cli.js --help; echo $?                                          # 0, usage on stdout
node dist/cli.js --version; echo $?                                      # 0, bare version
node dist/cli.js bogus; echo $?                                          # 1, reason on stderr
node dist/cli.js openapi extra; echo $?                                  # 1, names "extra"

Ran on this branch: 793 tests pass (777 before, 16 added), lint and build clean.

An end-to-end pass covered the export with an empty environment (exit 0, document on stdout, stderr empty), the listener count before and after the export (unchanged, so nothing bound), the unknown-subcommand exit code with empty stdout, redocly validation of the exported document, the no-argv boot, and byte equality between the CLI export and the body the route serves, and the four POSIX flags. 14 checks, all passing.

Known limitations

DispatchOutcome.exitCode is typed number and the type admits {exitCode: 1, server}, a combination the code never produces. Harmless today since the only consumer reads exitCode alone.

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

[linear-code]

PRD-887

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 6): dispatchCli	1

[macroscopeapp]

🟢 Low agent-bff/README.md:26

The README states that --help and --version print to stdout and exit 0 and that any other argument exits 1, but the CLI also accepts -h and -v as aliases that print to stdout and exit 0. Passing -h or -v is covered by the "any other argument exits 1" claim, so the documented behavior contradicts the actual behavior. Consider documenting -h and -v as accepted aliases.

Suggested change

	`forest-bff --help` and `forest-bff --version` print to stdout and exit 0. Any other
	argument exits 1 with the reason on stderr.
	`forest-bff --help`/`-h` and `forest-bff --version`/`-v` print to stdout and exit 0. Any other
	argument exits 1 with the reason on stderr.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/agent-bff/README.md around lines 26-27:

The README states that `--help` and `--version` print to stdout and exit 0 and that any other argument exits 1, but the CLI also accepts `-h` and `-v` as aliases that print to stdout and exit 0. Passing `-h` or `-v` is covered by the "any other argument exits 1" claim, so the documented behavior contradicts the actual behavior. Consider documenting `-h` and `-v` as accepted aliases.