Harden Cleverbrush reference implementation

[andrewzolotukhin]

Original request

Make xpenser a stronger demonstrator/test project for Cleverbrush Framework by inspecting the framework documentation and local source, reviewing for security and best practices, improving JSDoc documentation, and improving test coverage. Also use the wording “projects based on CleverBrush Framework” rather than “CleverBrush based projects.”

What changed

• Added docs/cleverbrush-reference.md and linked it from README.md to document the reference architecture, framework usage rules, security baseline, tests to keep, and a new-feature checklist for projects based on CleverBrush Framework.
• Added JSDoc to framework-facing glue code in API config/server/DI setup, web config accessors, Telegram config/tracing, shared contracts/limits, client creation, and schema-driven form provider wiring.
• Hardened runtime secrets by adding production placeholder guards for API/web/Telegram service secrets and documenting Telegram env vars in .env.example.
• Redacted SQL text at the Knex OpenTelemetry instrumentation boundary via instrumentKnex(..., { sanitizeStatement: () => '<redacted>' }).
• Fixed OpenAPI component generation drift by removing schemaName() from cloned leaf/enum fragments and reusing named object schema instances where they are intended to become shared components.
• Registered OpenAPI as a first-class Cleverbrush endpoint via createOpenApiEndpoint() instead of global serveOpenApi() middleware. Preview QA initially found /external-api/openapi.json returning 404 because this framework version routes requests before unmatched global middleware can serve them.
• Added focused tests for API auth schemes, endpoint metadata/OpenAPI generation, runtime OpenAPI serving, config guardrails, client middleware/batching behavior, Telegram tracing propagation, and schema-driven form rendering.

Reasoning

The implementation follows the current Cleverbrush docs and local framework source under /root/projects/framework: named schemas are reference-based OpenAPI components and must be reused as single constants; auth schemes are reflected into OpenAPI security; the client supports middleware/batching composition; React forms are configured through registered schema renderers; and instrumentKnex supports statement sanitization. The changes are intentionally conservative: they strengthen the app as a reference implementation without changing user-facing workflows.

Screenshots / preview evidence

Screenshots are not applicable for this PR because it changes documentation, configuration guardrails, generated API metadata, telemetry privacy, and tests rather than visual UI.

Manual preview QA passed at https://xpenser-pr-026.cleverbrush.com:

• Landing page loaded.
• /external-api/openapi.json returned 200 after the OpenAPI endpoint fix.
• OpenAPI JSON included xpenser API, bearerAuth, apiKey, and /api/auth/me security alternatives.
• Login page loaded.
• Seeded account sign-in succeeded and reached /dashboard with the authenticated app shell visible.

Validation

Local validation completed on commit 706bf4e:

• npm run lint passed.
• npm run typecheck passed.
• npm test passed: 57 files, 322 tests.
• npm run test:coverage passed: 57 files, 322 tests, 60.5% statement coverage.
• git diff --check passed.
• Context7 resolved Cleverbrush Framework as /cleverbrush/framework; docs were checked for OpenAPI generation, server/auth, batching, react-form, and OTel patterns.
• Local framework source was checked under /root/projects/framework for schemaName registry behavior, instrumentKnex sanitization support, and OpenAPI middleware/endpoint serving behavior.

GitHub checks on commit 706bf4e:

• Lint and test passed.
• Deploy PR environment passed.
• Playwright e2e passed.

SigNoz verification:

• Queried logs, traces, and http.server.duration.count metrics for service.name IN ('xpenser-web-pr-26', 'xpenser-api-pr-26') after manual preview QA.
• Queried zero-padded variants and field values containing 26; no matching logs, traces, or metrics were present.
• service.name field values currently show earlier xpenser PR services but not PR Harden Cleverbrush reference implementation #26, and the metric query reported http.server.duration.count was last seen outside the checked range.
• Result: no application errors were observed, but SigNoz telemetry for the PR Harden Cleverbrush reference implementation #26 environment is missing/unavailable, so telemetry health could not be cleanly verified from MCP.