@opsydyn/elysia-spectral 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.2.0](https://github.com/opsydyn/elysia-spectral/compare/v1.1.1...v1.2.0) (2026-04-28)
+
+
+### Features
+
+* optional bearer auth for the lint dashboard route ([7360e1c](https://github.com/opsydyn/elysia-spectral/commit/7360e1c323328005160598832dbd02b315a0cd2f))
+
+
+### Bug Fixes
+
+* publish dashboard documentation update ([c8d656a](https://github.com/opsydyn/elysia-spectral/commit/c8d656ae1a6bbcd67ce63bd8e430861b07cd216b))
+
 ## [1.1.1](https://github.com/opsydyn/elysia-spectral/compare/v1.1.0...v1.1.1) (2026-04-28)
 
 

package/README.md

@@ -62,6 +62,7 @@ Current package scope:
 - Bruno collection output (OpenCollection YAML or JSON)
 - reusable runtime for CI and tests
 - opt-in healthcheck endpoint for cached and fresh runs
+- opt-in HTML lint dashboard with severity filters, search, and copy-friendly artifact paths
 
 ## Data flow
 
@@ -347,6 +348,54 @@ Behavior:
 - the route returns `503` when findings meet or exceed `failOn`
 - the route is hidden from generated OpenAPI docs
 
+### Add an HTML lint dashboard endpoint
+
+The dashboard route is opt-in and renders the latest lint result as a self-contained HTML page — no JS bundle, no build step, no external assets.
+
+```ts
+spectralPlugin({
+  dashboard: {
+    path: '/__openapi/dashboard'
+  }
+})
+```
+
+`dashboard: {}` mounts the default path (`/__openapi/dashboard`); pass `path` to override.
+
+To gate the dashboard behind a static bearer token, pass `bearerToken`:
+
+```ts
+spectralPlugin({
+  dashboard: {
+    path: '/__openapi/dashboard',
+    bearerToken: process.env.LINT_DASHBOARD_TOKEN
+  }
+})
+```
+
+When `bearerToken` is set the route returns `401 Unauthorized` (with a `WWW-Authenticate: Bearer` header) unless the request carries a matching `Authorization: Bearer <token>` header. Leave `bearerToken` undefined to keep the route open — useful in local dev. This mirrors the bearer pattern documented in the [Elysia OpenAPI guide](https://elysiajs.com/patterns/openapi).
+
+What it surfaces:
+
+- pass / fail banner at the configured `failOn` threshold
+- run metadata (timestamp, source, duration, cache hit)
+- severity summary chips that filter the findings table
+- a search input that matches rule code, operation, message, and JSON pointer
+- copy-to-clipboard buttons next to artifact paths
+- the trademarked `SPEC IS TIGHT, SHIP IT RIGHT` tagline on a clean run
+
+Keyboard shortcuts: `r` re-runs, `/` focuses the filter, `Enter`/`Space` toggles the focused severity chip.
+
+Append `?fresh=1` to force a fresh lint run instead of returning the cached result.
+
+| State | Screenshot |
+| --- | --- |
+| Pass | ![Dashboard pass state](https://raw.githubusercontent.com/opsydyn/elysia-spectral/main/docs/screenshots/dashboard-happy.png) |
+| Fail | ![Dashboard fail state](https://raw.githubusercontent.com/opsydyn/elysia-spectral/main/docs/screenshots/dashboard-unhappy.png) |
+| Recovered | ![Dashboard recovered state](https://raw.githubusercontent.com/opsydyn/elysia-spectral/main/docs/screenshots/dashboard-unhappy-fixed.png) |
+
+The dashboard is hidden from generated OpenAPI docs and is intended for local and internal-only environments. Gate it behind your standard auth or environment checks before exposing it on a public host.
+
 ### Persist JSON reports and OpenAPI snapshots
 
 ```ts
@@ -651,6 +700,7 @@ That starts `apps/dev-app` with:
 - OpenAPI UI at `/openapi`
 - raw OpenAPI JSON at `/openapi/json`
 - opt-in lint healthcheck at `/health/openapi-lint`
+- opt-in HTML lint dashboard at `/api-lint/dashboard`
 - JSON lint report output at `./artifacts/openapi-lint.json`
 - OpenAPI snapshot output at `./elysia-spectral-dev-app.open-api.json`
 
@@ -687,6 +737,7 @@ type SpectralPluginOptions = {
   /** Severity level at which the lint run is considered failed. Defaults to 'error'. */
   failOn?: SeverityThreshold
   healthcheck?: false | { path?: string }
+  dashboard?: false | { path?: string; bearerToken?: string }
   output?: {
     /** Print findings to the console. Default: true. */
     console?: boolean
@@ -973,8 +1024,9 @@ Startup linting and route exposure solve different problems:
 
 - startup linting protects boot and local feedback loops
 - healthchecks expose operational state to external callers
+- the dashboard turns the same cached result into a human-readable page
 
-Separating them avoids a production surprise where enabling linting also adds a route you did not intend to expose.
+Separating them avoids a production surprise where enabling linting also adds a route you did not intend to expose. Each route is opt-in, so dashboards stay off by default and never leak into generated OpenAPI docs.
 
 ### Why repo-level rulesets are the default customization path
 

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { a as createOpenApiLintRuntime, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver } from "../index-Dx83hCT9.mjs";
+import { a as createOpenApiLintRuntime, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver } from "../index-CyJXdIRT.mjs";
 export { LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, shouldFail };

package/dist/{index-Dx83hCT9.d.mts → index-CyJXdIRT.d.mts}

@@ -38,6 +38,7 @@ type SpectralPluginOptions = {
   };
   dashboard?: false | {
     path?: string;
+    bearerToken?: string;
   };
   output?: {
     console?: boolean;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SpectralLogger, C as OpenApiLintRuntime, D as OpenApiLintSinkContext, E as OpenApiLintSink, M as StartupLintMode, O as PresetName, S as OpenApiLintArtifacts, T as OpenApiLintRuntimeStatus, _ as ArtifactWriteFailureMode, a as createOpenApiLintRuntime, b as LintRunSource, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, j as SpectralPluginOptions, k as SeverityThreshold, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver, v as LintFinding, w as OpenApiLintRuntimeFailure, x as LintSeverity, y as LintRunResult } from "./index-Dx83hCT9.mjs";
+import { A as SpectralLogger, C as OpenApiLintRuntime, D as OpenApiLintSinkContext, E as OpenApiLintSink, M as StartupLintMode, O as PresetName, S as OpenApiLintArtifacts, T as OpenApiLintRuntimeStatus, _ as ArtifactWriteFailureMode, a as createOpenApiLintRuntime, b as LintRunSource, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, j as SpectralPluginOptions, k as SeverityThreshold, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver, v as LintFinding, w as OpenApiLintRuntimeFailure, x as LintSeverity, y as LintRunResult } from "./index-CyJXdIRT.mjs";
 import { RulesetDefinition } from "@stoplight/spectral-core";
 import { Elysia } from "elysia";
 

package/dist/index.mjs

@@ -288,7 +288,17 @@ const spectralPlugin = (options = {}) => {
 	}
 	if (options.dashboard) {
 		const dashboardPath = options.dashboard.path ?? "/__openapi/dashboard";
+		const bearerToken = options.dashboard.bearerToken;
 		plugin = plugin.get(dashboardPath, async ({ request, set }) => {
+			if (bearerToken) {
+				const header = request.headers.get("authorization") ?? "";
+				if ((header.startsWith("Bearer ") ? header.slice(7) : "") !== bearerToken) {
+					set.status = 401;
+					set.headers["www-authenticate"] = "Bearer realm=\"elysia-spectral\"";
+					set.headers["content-type"] = "text/plain; charset=utf-8";
+					return "Unauthorized";
+				}
+			}
 			const fresh = new URL(request.url).searchParams.get("fresh") === "1";
 			const threshold = options.failOn ?? "error";
 			const currentApp = hostAppRef.current;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsydyn/elysia-spectral",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Thin Elysia plugin that lints generated OpenAPI documents with Spectral.",
   "packageManager": "bun@1.3.11",
   "publishConfig": {