@zintrust/core 0.1.28 → 0.1.29

package/src/routes/doc.js

@@ -0,0 +1,110 @@
+/**
+ * Documentation Routes
+ * Serves static files from /doc/* paths with relaxed CSP headers.
+ */
+import { HTTP_HEADERS } from '../config/constants.js';
+import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from './common.js';
+import { ErrorRouting } from './error.js';
+import { getPublicRootAsync } from './publicRoot.js';
+import { Router } from './Router.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import * as fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+export { MIME_TYPES_MAP } from './common.js';
+/**
+ * Find the package root directory
+ */
+// Backward-compatible re-exports
+export { findPackageRoot, findPackageRootAsync, getFrameworkPublicRoots, getFrameworkPublicRootsAsync, getPublicRoot, getPublicRootAsync, } from './publicRoot.js';
+const mapStaticPathAsync = async (urlPath) => {
+    const publicRoot = await getPublicRootAsync();
+    const normalize = (p) => (p.startsWith('/') ? p.slice(1) : p);
+    if (urlPath === '/doc' || urlPath === '/doc/')
+        return publicRoot;
+    if (urlPath.startsWith('/doc/')) {
+        const rawRelative = urlPath.slice('/doc/'.length);
+        const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
+        return resolveSafePath(publicRoot, normalize(normalizedRelative));
+    }
+    const normalized = tryDecodeURIComponent(urlPath).replaceAll('\\', '/');
+    return resolveSafePath(publicRoot, normalize(normalized));
+};
+/**
+ * Set relaxed CSP headers for docs (allows external assets like Tailwind CDN, Google Fonts)
+ */
+export const setDocumentationCSPHeaders = (response) => {
+    response.setHeader(HTTP_HEADERS.CONTENT_SECURITY_POLICY, "default-src 'self'; " +
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.tailwindcss.com; " +
+        "script-src-elem 'self' 'unsafe-inline' https://cdn.tailwindcss.com; " +
+        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+        "style-src-elem 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+        "img-src 'self' data: https:; " +
+        "font-src 'self' data: https://fonts.gstatic.com;");
+};
+/**
+ * Serve a documentation static file (async)
+ */
+export const serveDocumentationFileAsync = async (urlPath, response) => {
+    let filePath = await mapStaticPathAsync(urlPath);
+    if (filePath === undefined) {
+        return false;
+    }
+    try {
+        try {
+            const stats = await fs.fsPromises.stat(filePath);
+            if (stats.isDirectory()) {
+                filePath = path.join(filePath, 'index.html');
+            }
+        }
+        catch {
+            // ignore
+        }
+        const exists = async (p) => {
+            try {
+                await fs.fsPromises.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        if (!(await exists(filePath)) && !path.extname(filePath)) {
+            const htmlPath = `${filePath}.html`;
+            if (await exists(htmlPath)) {
+                filePath = htmlPath;
+            }
+        }
+        if (await exists(filePath)) {
+            const ext = path.extname(filePath).toLowerCase();
+            const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
+            const content = await fs.fsPromises.readFile(filePath);
+            response.setStatus(200);
+            response.setHeader('Content-Type', contentType);
+            response.send(content);
+            return true;
+        }
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError(`Error serving documentation file ${filePath}`, error);
+    }
+    return false;
+};
+const handleDocRequest = async (req, res) => {
+    setDocumentationCSPHeaders(res);
+    const urlPath = req.getPath();
+    if (await serveDocumentationFileAsync(urlPath, res))
+        return;
+    ErrorRouting.handleNotFound(req, res);
+};
+export const registerDocRoutes = (router) => {
+    // Root docs entrypoints.
+    Router.get(router, '/doc', handleDocRequest);
+    Router.get(router, '/doc/', handleDocRequest);
+    // Greedy path match for nested assets like /doc/assets/app.js
+    Router.get(router, '/doc/:path*', handleDocRequest);
+};
+export default {
+    registerDocRoutes,
+    setDocumentationCSPHeaders,
+    serveDocumentationFileAsync,
+};

package/src/routes/error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error Routing
+ * Centralizes 404/500 handling and HTML error page rendering.
+ */
+import type { IRouter } from './Router';
+import type { IRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+import type * as http from '../node-singletons/http';
+/**
+ * Debug routes to always render 404/500 responses.
+ */
+export declare const registerErrorRoutes: (router: IRouter) => void;
+export declare const ErrorRouting: Readonly<{
+    getPublicRoot: () => string;
+    registerErrorRoutes: (router: IRouter) => void;
+    handleNotFound: (request: IRequest, response: IResponse, requestId?: string) => void;
+    handleInternalServerErrorWithWrappers: (request: IRequest, response: IResponse, error: unknown, requestId?: string) => void;
+    handleInternalServerErrorRaw: (res: http.ServerResponse) => void;
+}>;
+export default ErrorRouting;
+//# sourceMappingURL=error.d.ts.map

package/src/routes/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/routes/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAyJnD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,IAGrD,CAAC;AAEF,eAAO,MAAM,YAAY;;kCALmB,OAAO,KAAG,IAAI;8BAlGzB,QAAQ,YAAY,SAAS,cAAc,MAAM,KAAG,IAAI;qDAiB9E,QAAQ,YACP,SAAS,SACZ,OAAO,cACF,MAAM,KACjB,IAAI;wCA0DoC,IAAI,CAAC,cAAc,KAAG,IAAI;EA8BnE,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/routes/error.js

@@ -0,0 +1,127 @@
+/**
+ * Error Routing
+ * Centralizes 404/500 handling and HTML error page rendering.
+ */
+import { appConfig } from '../config/app.js';
+import { HTTP_HEADERS, MIME_TYPES } from '../config/constants.js';
+import { getPublicRoot } from './publicRoot.js';
+import { Router } from './Router.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { ErrorPageRenderer } from '../http/error-pages/ErrorPageRenderer.js';
+import { ErrorResponse } from '../http/ErrorResponse.js';
+// Cache Set at module level to avoid repeated creation
+const REDACTED_HEADERS = new Set(['authorization', 'cookie', 'set-cookie', 'x-api-key']);
+const redactHeaders = (headers) => {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (REDACTED_HEADERS.has(key.toLowerCase())) {
+            out[key] = '[redacted]';
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+};
+const safeJsonStringify = (value) => {
+    try {
+        return JSON.stringify(value, null, 2) ?? '';
+    }
+    catch {
+        return '';
+    }
+};
+const trySendHtmlErrorPage = (request, response, input) => {
+    if (!ErrorPageRenderer.shouldSendHtml(request))
+        return false;
+    const publicRoot = getPublicRoot();
+    const html = ErrorPageRenderer.renderHtml(publicRoot, {
+        statusCode: input.statusCode,
+        errorName: input.errorName,
+        errorMessage: input.errorMessage,
+        requestPath: request.getPath(),
+        stackPretty: input.stackPretty,
+        stackRaw: input.stackRaw,
+        requestPretty: input.requestPretty,
+        requestRaw: input.requestRaw,
+    });
+    if (html === undefined)
+        return false;
+    response.html(html);
+    return true;
+};
+const handleNotFound = (request, response, requestId) => {
+    response.setStatus(404);
+    if (trySendHtmlErrorPage(request, response, {
+        statusCode: 404,
+        errorName: 'Not Found',
+        errorMessage: 'The page you requested could not be found.',
+    })) {
+        return;
+    }
+    response.json(ErrorResponse.notFound('Route', requestId));
+};
+const handleInternalServerErrorWithWrappers = (request, response, error, requestId) => {
+    response.setStatus(500);
+    const isDev = appConfig.isDevelopment();
+    const err = error instanceof Error ? error : ErrorFactory.createGeneralError('Unknown error', error);
+    const errorName = isDev ? err.name || 'Error' : 'Internal Server Error';
+    const errorMessage = isDev
+        ? err.message || 'An error has occurred'
+        : 'Something went wrong while handling your request.';
+    const requestObj = isDev
+        ? {
+            method: request.getMethod(),
+            path: request.getPath(),
+            query: request.getQuery(),
+            headers: redactHeaders(request.getHeaders()),
+        }
+        : undefined;
+    const requestPretty = requestObj === undefined
+        ? undefined
+        : `Request\n\nMethod: ${requestObj.method}\nPath: ${requestObj.path}\n\nHeaders:\n${safeJsonStringify(requestObj.headers)}\n\nQuery:\n${safeJsonStringify(requestObj.query)}`;
+    const requestRaw = requestObj === undefined ? undefined : safeJsonStringify(requestObj);
+    const stackPretty = isDev ? (err.stack ?? '') : undefined;
+    const stackRaw = isDev
+        ? safeJsonStringify({ name: err.name, message: err.message, stack: err.stack })
+        : undefined;
+    if (trySendHtmlErrorPage(request, response, {
+        statusCode: 500,
+        errorName,
+        errorMessage,
+        stackPretty,
+        stackRaw,
+        requestPretty,
+        requestRaw,
+    })) {
+        return;
+    }
+    response.json(ErrorResponse.internalServerError('Internal server error', requestId, isDev ? err.stack : undefined));
+};
+const handleInternalServerErrorRaw = (res) => {
+    res.writeHead(500, { [HTTP_HEADERS.CONTENT_TYPE]: MIME_TYPES.JSON });
+    res.end(JSON.stringify(ErrorResponse.internalServerError('Internal server error')));
+};
+const handleForced404 = (req, res) => {
+    handleNotFound(req, res);
+};
+const handleForced500 = (req, res) => {
+    const forced = ErrorFactory.createGeneralError('Forced 500 route', {
+        route: '/500',
+    });
+    handleInternalServerErrorWithWrappers(req, res, forced);
+};
+/**
+ * Debug routes to always render 404/500 responses.
+ */
+export const registerErrorRoutes = (router) => {
+    Router.get(router, '/404', handleForced404);
+    Router.get(router, '/500', handleForced500);
+};
+export const ErrorRouting = Object.freeze({
+    getPublicRoot,
+    registerErrorRoutes,
+    handleNotFound,
+    handleInternalServerErrorWithWrappers,
+    handleInternalServerErrorRaw,
+});
+export default ErrorRouting;

package/src/routes/errorPages.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error Pages Static Assets
+ * Serves /error-pages/* assets (CSS/JS/SVG/etc) used by HTML error templates.
+ */
+import type { IRouter } from './Router';
+import type { IResponse } from '../http/Response';
+export declare const serveErrorPagesFile: (urlPath: string, response: IResponse) => boolean;
+export declare const registerErrorPagesRoutes: (router: IRouter) => void;
+declare const _default: {
+    registerErrorPagesRoutes: (router: IRouter) => void;
+    serveErrorPagesFile: (urlPath: string, response: IResponse) => boolean;
+};
+export default _default;
+//# sourceMappingURL=errorPages.d.ts.map

package/src/routes/errorPages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorPages.d.ts","sourceRoot":"","sources":["../../../src/routes/errorPages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAkChD,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,EAAE,UAAU,SAAS,KAAG,OAsD1E,CAAC;AAeF,eAAO,MAAM,wBAAwB,GAAI,QAAQ,OAAO,KAAG,IAO1D,CAAC;;uCAP+C,OAAO,KAAG,IAAI;mCArElB,MAAM,YAAY,SAAS,KAAG,OAAO;;AA8ElF,wBAAiE"}

package/src/routes/errorPages.js

@@ -0,0 +1,103 @@
+/**
+ * Error Pages Static Assets
+ * Serves /error-pages/* assets (CSS/JS/SVG/etc) used by HTML error templates.
+ */
+import { HTTP_HEADERS, MIME_TYPES } from '../config/constants.js';
+import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from './common.js';
+import { getPublicRoot } from './publicRoot.js';
+import { Router } from './Router.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import * as fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+const servePublicRootFile = (relativePath, response, contentType) => {
+    const publicRoot = getPublicRoot();
+    const filePath = path.join(publicRoot, relativePath);
+    try {
+        if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+            response.setStatus(404);
+            response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+            response.send('Not Found');
+            return;
+        }
+        const content = fs.readFileSync(filePath);
+        response.setStatus(200);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
+        response.send(content);
+        return;
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError(`Error serving public file ${filePath}`, error);
+        response.setStatus(500);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+        response.send('Internal Server Error');
+        return;
+    }
+};
+export const serveErrorPagesFile = (urlPath, response) => {
+    if (urlPath === '/error-pages' || urlPath === '/error-pages/') {
+        response.setStatus(404);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+        response.send('Not Found');
+        return true;
+    }
+    if (!urlPath.startsWith('/error-pages/'))
+        return false;
+    const publicRoot = getPublicRoot();
+    const baseDir = path.join(publicRoot, 'error-pages');
+    const rawRelative = urlPath.slice('/error-pages/'.length);
+    const normalizedRelative = tryDecodeURIComponent(rawRelative).replaceAll('\\', '/');
+    const filePath = resolveSafePath(baseDir, normalizedRelative);
+    if (filePath === undefined) {
+        response.setStatus(404);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+        response.send('Not Found');
+        return true;
+    }
+    try {
+        if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+            response.setStatus(404);
+            response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+            response.send('Not Found');
+            return true;
+        }
+        if (!fs.existsSync(filePath)) {
+            response.setStatus(404);
+            response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+            response.send('Not Found');
+            return true;
+        }
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
+        const content = fs.readFileSync(filePath);
+        response.setStatus(200);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, contentType);
+        response.send(content);
+        return true;
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError(`Error serving error-pages file ${filePath}`, error);
+        response.setStatus(500);
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+        response.send('Internal Server Error');
+        return true;
+    }
+};
+const handleErrorPagesRequest = (req, res) => {
+    const urlPath = req.getPath();
+    if (serveErrorPagesFile(urlPath, res))
+        return;
+    res.setStatus(404);
+    res.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+    res.send('Not Found');
+};
+const handleZintrustSvgRequest = (_req, res) => {
+    servePublicRootFile('zintrust.svg', res, MIME_TYPES.SVG);
+};
+export const registerErrorPagesRoutes = (router) => {
+    Router.get(router, '/error-pages', handleErrorPagesRequest);
+    Router.get(router, '/error-pages/', handleErrorPagesRequest);
+    Router.get(router, '/error-pages/:path*', handleErrorPagesRequest);
+    // Used by the HTML error templates (logo in footer).
+    Router.get(router, '/zintrust.svg', handleZintrustSvgRequest);
+};
+export default { registerErrorPagesRoutes, serveErrorPagesFile };

package/src/routes/health.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Health Routes - Re-export from shared module
+ * This file maintains backward compatibility while eliminating duplication
+ */
+export { registerHealthRoutes } from '../common/HealthRoutes';
+//# sourceMappingURL=health.d.ts.map

package/src/routes/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../src/routes/health.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/src/routes/health.js

@@ -0,0 +1,5 @@
+/**
+ * Health Routes - Re-export from shared module
+ * This file maintains backward compatibility while eliminating duplication
+ */
+export { registerHealthRoutes } from '../common/HealthRoutes.js';

package/src/routes/metrics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metrics Routes
+ *
+ * Exposes Prometheus metrics when enabled.
+ */
+import { type IRouter } from './Router';
+export declare function registerMetricsRoutes(router: IRouter): void;
+export default registerMetricsRoutes;
+//# sourceMappingURL=metrics.d.ts.map

package/src/routes/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,qBAAqB,CAAC;AAE3D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAW3D;AAED,eAAe,qBAAqB,CAAC"}

package/src/routes/metrics.js

@@ -0,0 +1,20 @@
+/**
+ * Metrics Routes
+ *
+ * Exposes Prometheus metrics when enabled.
+ */
+import { PrometheusMetrics } from '../observability/PrometheusMetrics.js';
+import { Env } from '../config/env.js';
+import { Router } from './Router.js';
+export function registerMetricsRoutes(router) {
+    if (Env.getBool('METRICS_ENABLED', false) === false)
+        return;
+    const pathFromEnv = Env.get('METRICS_PATH', '/metrics').trim();
+    const path = pathFromEnv === '' ? '/metrics' : pathFromEnv;
+    Router.get(router, path, async (_req, res) => {
+        const { contentType, body } = await PrometheusMetrics.getMetricsText();
+        res.setHeader('Content-Type', contentType);
+        res.send(body);
+    });
+}
+export default registerMetricsRoutes;

package/src/routes/openapi.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAPI Routes
+ *
+ * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
+ */
+import { type IRouter } from './Router';
+export declare function registerOpenApiRoutes(router: IRouter): void;
+export default registerOpenApiRoutes;
+//# sourceMappingURL=openapi.d.ts.map

package/src/routes/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/routes/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,qBAAqB,CAAC;AA2C3D,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAuC3D;AAED,eAAe,qBAAqB,CAAC"}

package/src/routes/openapi.js

@@ -0,0 +1,76 @@
+/**
+ * OpenAPI Routes
+ *
+ * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
+ */
+import { OpenApiGenerator } from '../openapi/OpenApiGenerator.js';
+import { Env } from '../config/env.js';
+import { Router } from './Router.js';
+import { RouteRegistry } from './RouteRegistry.js';
+const getServerUrl = () => {
+    const explicit = Env.BASE_URL;
+    if (explicit.trim() !== '')
+        return explicit;
+    const host = Env.HOST;
+    const port = Env.PORT;
+    if (host.trim() === '' || Number.isNaN(port) || port <= 0)
+        return undefined;
+    return `http://${host}:${port}`;
+};
+const getDocsHtml = (specUrl) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${Env.APP_NAME} API Docs</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      html, body { margin: 0; padding: 0; }
+      #swagger-ui { box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function () {
+        window.ui = SwaggerUIBundle({
+          url: ${JSON.stringify(specUrl)},
+          dom_id: '#swagger-ui',
+          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+          layout: 'BaseLayout'
+        });
+      };
+    </script>
+  </body>
+</html>`;
+export function registerOpenApiRoutes(router) {
+    Router.get(router, '/openapi.json', (_req, res) => {
+        // Convert readonly to mutable array for OpenApiGenerator
+        const routes = Array.from(RouteRegistry.list());
+        const doc = OpenApiGenerator.generate(routes, {
+            title: Env.APP_NAME,
+            version: Env.get('APP_VERSION', '0.0.0'),
+            serverUrl: getServerUrl(),
+            excludePaths: ['/openapi.json', '/docs'],
+        });
+        res.json(doc);
+    }, {
+        meta: {
+            summary: 'OpenAPI spec',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+    Router.get(router, '/docs', (_req, res) => {
+        res.html(getDocsHtml('/openapi.json'));
+    }, {
+        meta: {
+            summary: 'Swagger UI',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+}
+export default registerOpenApiRoutes;

package/src/routes/publicRoot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public Root Resolution
+ * Determines where framework/app static assets live (public/ or dist/public).
+ */
+/**
+ * Find the package root directory.
+ */
+export declare const findPackageRoot: (startDir: string) => string;
+/**
+ * Find the package root directory (async).
+ */
+export declare const findPackageRootAsync: (startDir: string) => Promise<string>;
+/**
+ * Framework public roots (dist/public preferred).
+ */
+export declare const getFrameworkPublicRoots: () => string[];
+export declare const getFrameworkPublicRootsAsync: () => Promise<string[]>;
+/**
+ * Resolve the effective public root.
+ * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
+ */
+export declare const getPublicRoot: () => string;
+/**
+ * Resolve the effective public root (async).
+ */
+export declare const getPublicRootAsync: () => Promise<string>;
+//# sourceMappingURL=publicRoot.d.ts.map

package/src/routes/publicRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicRoot.d.ts","sourceRoot":"","sources":["../../../src/routes/publicRoot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,MAalD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAkB3E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,MAAM,EAIhD,CAAC;AAEF,eAAO,MAAM,4BAA4B,QAAa,OAAO,CAAC,MAAM,EAAE,CAIrE,CAAC;AAKF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAO,MAgBhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,MAAM,CA+BzD,CAAC"}

package/src/routes/publicRoot.js

@@ -0,0 +1,112 @@
+/**
+ * Public Root Resolution
+ * Determines where framework/app static assets live (public/ or dist/public).
+ */
+import { esmDirname } from '../common/index.js';
+import * as fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+/**
+ * Find the package root directory.
+ */
+export const findPackageRoot = (startDir) => {
+    let current = startDir;
+    for (let i = 0; i < 10; i++) {
+        try {
+            if (fs.existsSync(path.join(current, 'package.json')))
+                return current;
+        }
+        catch {
+            // ignore access errors
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return startDir;
+};
+/**
+ * Find the package root directory (async).
+ */
+export const findPackageRootAsync = async (startDir) => {
+    const findUp = async (current, depth) => {
+        if (depth >= 10)
+            return startDir;
+        try {
+            await fs.fsPromises.access(path.join(current, 'package.json'));
+            return current;
+        }
+        catch {
+            // ignore
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return startDir;
+        return findUp(parent, depth + 1);
+    };
+    return findUp(startDir, 0);
+};
+/**
+ * Framework public roots (dist/public preferred).
+ */
+export const getFrameworkPublicRoots = () => {
+    const thisDir = esmDirname(import.meta.url);
+    const packageRoot = findPackageRoot(thisDir);
+    return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
+};
+export const getFrameworkPublicRootsAsync = async () => {
+    const thisDir = esmDirname(import.meta.url);
+    const packageRoot = await findPackageRootAsync(thisDir);
+    return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
+};
+// Cache process.cwd() at module load time
+const projectCwd = process.cwd();
+/**
+ * Resolve the effective public root.
+ * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
+ */
+export const getPublicRoot = () => {
+    const appRoots = [path.join(projectCwd, 'public')];
+    const candidates = [...appRoots, ...getFrameworkPublicRoots()];
+    // Prefer a root that contains an index.html (common for docs + dev portal).
+    const hasIndex = (root) => fs.existsSync(path.join(root, 'index.html'));
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && hasIndex(candidate))
+            return candidate;
+    }
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+};
+/**
+ * Resolve the effective public root (async).
+ */
+export const getPublicRootAsync = async () => {
+    const appRoots = [path.join(projectCwd, 'public')];
+    const fwRoots = await getFrameworkPublicRootsAsync();
+    const candidates = [...appRoots, ...fwRoots];
+    const exists = async (p) => {
+        try {
+            await fs.fsPromises.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasIndex = async (root) => exists(path.join(root, 'index.html'));
+    const checks = await Promise.all(candidates.map(async (candidate) => {
+        const rootExists = await exists(candidate);
+        const indexExists = rootExists ? await hasIndex(candidate) : false;
+        return { candidate, rootExists, indexExists };
+    }));
+    const withIndex = checks.find((c) => c.indexExists);
+    if (withIndex)
+        return withIndex.candidate;
+    const firstExisting = checks.find((c) => c.rootExists);
+    if (firstExisting)
+        return firstExisting.candidate;
+    return candidates[0];
+};