feat(agent-bff): scaffold the agent-bff package

[Tonours]

fixes PRD-647

Forest BFF Slice 0: the @forestadmin/agent-bff package skeleton. Bootable, nothing more. The Zod→OpenAPI spike (PRD-648) and the OAuth trace (PRD-649) build on it.

What it does

• CommonJS package, forest-bff bin, modeled on workflow-executor.
• Koa 3 server + GET /health + X-Forest-Bff-Version header (version read from package.json).
• Config validated at boot with Zod, model C:
  • malformed value (non-http(s) *_URL, non-integer HTTP_PORT) → fail-fast, clear exit, never echoes the value;
  • absent/empty required var → server still boots and reports degraded via /health 503.
• Injectable logger (copied from workflow-executor, copy-first — shared-core extraction deferred).
• Stack pinned for the spike: Koa 3, Zod 4.3.6.

Env vars (named here so PRD-648/649 reuse them): FOREST_AUTH_SECRET, FOREST_ENV_SECRET, FOREST_SERVER_URL, FOREST_APP_URL, AGENT_URL, HTTP_PORT (default 3450).

Security

/health is unauthenticated, so its body is { status, version } only — it never says which config key is present or missing (that would leak the internal config surface). Missing keys are surfaced to operators via a single startup Warn log. Secrets are kept verbatim (not trimmed), so a secret with surrounding spaces isn't silently altered.

What does NOT change

No auth, no data endpoints, no OpenAPI (later slices). The agent-client call path is not wired — only its URL is read. No other package touched, no yarn.lock churn.

How to test

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

Boot it and hit /health:

FOREST_AUTH_SECRET=x FOREST_ENV_SECRET=x FOREST_SERVER_URL=https://a.com \
  FOREST_APP_URL=https://b.com AGENT_URL=https://c.com node packages/agent-bff/dist/cli.js
curl -i localhost:3450/health   # 200 { status, version }, X-Forest-Bff-Version header, port 3450

• Drop a required var (e.g. FOREST_SERVER_URL) → boots, /health 503 degraded, missing key logged at startup (not in the response).
• Break a value (AGENT_URL=nope) → exit 1, sanitized message, secret never echoed.

---

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-647

[qltysh]

4 new issues

Tool	Category	Rule	Count
qlty	Duplication	Found 23 lines of identical code in 2 locations (mass = 119)	2
qlty	Structure	Complex binary expression	1
qlty	Structure	Function with high complexity (count = 11): start	1

[qltysh]

Coverage Impact

⬇️ Merging this pull request will decrease total coverage on main by 0.05%.

Modified Files with Diff Coverage (8)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/adapters/console-logger.ts	100.0%
	packages/agent-bff/src/version.ts	100.0%
	packages/agent-bff/src/cli-core.ts	100.0%
	packages/agent-bff/src/defaults.ts	100.0%
	packages/agent-bff/src/config/env-config.ts	100.0%
	packages/agent-bff/src/errors.ts	100.0%
	packages/agent-bff/src/http/bff-http-server.ts	100.0%
	packages/agent-bff/src/index.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.