refactor(web): narrow runtime docs and logging boundaries

Author: devstd2211

ACTIVE_REFACTOR_PLAN.md

@@ -41,23 +41,23 @@ Historical detail is archived elsewhere and should not be copied here.
 9. Do not run separate test-only cleanup campaigns.
 
 ## Latest Completed
-- 2026-06-03: completed `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`.
-- `analytics.routes.ts` now consumes an explicit route dependency bundle split into `journal`, `sessions`, `strategy`, and `curves`, so the HTTP layer no longer depends on one flat file-watcher-shaped read surface.
-- `analytics.constants.ts` now owns analytics route paging, recent-window, and fallback-message constants instead of leaving route magic numbers and fallback strings inline.
-- `route-response.ts` now builds an explicit route response context before writing success or error envelopes, keeping request-id normalization and shared route execution behavior on one runtime seam.
-- `route-response.test.ts` now guards the shared response helper directly, while `web-server.functional.test.ts` proves the analytics route bundle stays on the narrowed delegates.
+- 2026-06-03: completed `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`.
+- `runtime-discovery-guidance.ts` now owns the runtime discovery paragraphs, OpenAPI description assembly, server description copy, and shared docs HTML section so the docs and OpenAPI layers consume one runtime-copy boundary.
+- `request-logging.middleware.ts` now resolves logging config once and delegates finish/error lifecycle logging through focused helpers while still emitting the same shared HTTP log payloads.
+- `swagger.config.ts` now relies on `swagger-contract-helpers.ts` for shared schema, request-body, and envelope builders so the file stays focused on the exported OpenAPI contract surface.
+- `request-logging.middleware.test.ts` now guards config normalization directly, and `web-server.functional.test.ts` continues to prove the runtime discovery and OpenAPI surfaces stay behaviorally stable.
 
 ## Latest Verification
-- 2026-06-03: `npm test -- --runInBand packages/web-server/tests/route-response.test.ts` (1 suite, 4 tests)
+- 2026-06-03: `npm test -- --runInBand packages/web-server/tests/request-logging.middleware.test.ts` (1 suite, 8 tests)
 - 2026-06-03: `npm test -- --runInBand packages/web-server/tests/web-server.functional.test.ts` (1 suite, 53 tests)
 - 2026-06-03: `npm test -- --runInBand position-monitor` (6 suites, 59 tests)
 - 2026-06-03: `npm run build`
 
 ## Next Step
 - Continue with the next active component from `REFACTOR_COMPONENT_CHECKLIST.md`.
-- Start with `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`.
+- Start with `packages/web-server/src/services/config-management.service.ts web server config lifecycle boundary follow-up`.
 - Keep the next batch on the web-server runtime/error boundary stream before returning to the remaining core docs guardrail items.
 
 ## Archive

NEXT_SESSION_PROMPT.md

@@ -14,9 +14,9 @@ Work directly on local `main`. Do not create worktrees. If the current branch is
 
 ## Current Batch
 Start with these three active queue items:
-1. `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`
-2. `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`
-3. `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`
+1. `packages/web-server/src/services/config-management.service.ts web server config lifecycle boundary follow-up`
+2. `packages/web-server/src/services/file-watcher.service.ts web server analytics watcher runtime boundary follow-up`
+3. `packages/web-server/src/middleware/error-handler.middleware.ts web server structured error middleware boundary follow-up`
 
 If one of these turns out to be too small, merge it with the next adjacent runtime,
 initializer, or websocket boundary item from `REFACTOR_COMPONENT_CHECKLIST.md` and keep
@@ -53,15 +53,15 @@ After all three slices are complete:
 5. Commit the batch after tests, smoke, build, and docs updates pass.
 
 ## Last Completed
-- 2026-06-03: completed `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up`.
-- 2026-06-03: completed `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up`.
-- `analytics.routes.ts` now depends on a nested analytics route bundle (`journal`, `sessions`, `strategy`, `curves`) instead of a flat file-watcher-shaped read surface.
-- `analytics.constants.ts` now owns route defaults and fallback strings for analytics paging, recent-history reads, and curve endpoints.
-- `route-response.ts` now creates an explicit route response context before writing shared success/error envelopes, and `route-response.test.ts` directly guards request-id normalization plus fallback error behavior.
+- 2026-06-03: completed `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`.
+- 2026-06-03: completed `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`.
+- `runtime-discovery-guidance.ts` now owns the runtime discovery paragraph set, docs HTML section, OpenAPI description assembly, and default runtime server description instead of leaving those strings split across `index.ts` and `swagger.config.ts`.
+- `request-logging.middleware.ts` now resolves logging config through one shared boundary and delegates finish/error event logging through focused helpers over the existing request-scoped payload builders.
+- `swagger.config.ts` now consumes `swagger-contract-helpers.ts` for shared OpenAPI envelope, schema-alias, and request-body builders so the file stays focused on the exported contract map.
 
 ## Last Verification
-- `npm test -- --runInBand packages/web-server/tests/route-response.test.ts`
+- `npm test -- --runInBand packages/web-server/tests/request-logging.middleware.test.ts`
 - `npm test -- --runInBand packages/web-server/tests/web-server.functional.test.ts`
 - `npm test -- --runInBand position-monitor`
 - `npm run build`

REFACTOR_COMPONENT_CHECKLIST.md

@@ -15,23 +15,26 @@ Legend:
 - `func` = functional test exists
 
 ## Active Components
-- [ ] `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up`
-- [ ] `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up`
 - [ ] `packages/web-server/src/services/config-management.service.ts web server config lifecycle boundary follow-up`
 - [ ] `packages/web-server/src/services/file-watcher.service.ts web server analytics watcher runtime boundary follow-up`
-- [ ] `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up`
 - [ ] `packages/web-server/tests/request-logging.middleware.test.ts web server runtime logging guardrail follow-up`
 - [ ] `packages/web-server/src/middleware/error-handler.middleware.ts web server structured error middleware boundary follow-up`
 - [ ] `packages/web-server/tests/error-handler.middleware.test.ts web server structured error middleware guardrail follow-up`
 - [ ] `packages/web-server/src/errors/api-error-response.ts web server structured error contract boundary follow-up`
 - [ ] `packages/web-server/tests/api-error-response.test.ts web server structured error contract guardrail follow-up`
 - [ ] `packages/web-server/src/logging/request-scoped-error-log.ts web server request-scoped logging contract boundary follow-up`
+- [ ] `packages/web-server/src/swagger-contract-helpers.ts web server OpenAPI shared builder boundary follow-up`
+- [ ] `packages/web-server/tests/web-server.functional.test.ts web server runtime docs and logging guardrail follow-up`
+- [ ] `packages/web-server/src/index.ts web server docs helper delegate boundary follow-up`
 - [ ] `packages/core/src/__tests__/web/web-boundary.test.ts web server adapter contract guardrail follow-up`
 - [ ] `packages/core/src/__tests__/core/readme-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
 - [ ] `packages/core/src/__tests__/core/architecture-entrypoint-boundary.functional.test.ts runtime handoff docs guardrail follow-up`
 - [ ] `packages/core/src/__tests__/core/legacy-entrypoint.functional.test.ts legacy wrapper runtime barrel guardrail follow-up`
 
 ## Completed History
+- [x] `packages/web-server/src/swagger.config.ts web server OpenAPI contract surface boundary follow-up` | prod: yes | tests: yes | func: yes
+- [x] `packages/web-server/src/runtime-discovery-guidance.ts web server runtime discovery guidance boundary follow-up` | prod: yes | tests: yes | func: yes
+- [x] `packages/web-server/src/middleware/request-logging.middleware.ts web server runtime logging boundary follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/src/routes/analytics.routes.ts analytics route runtime adapter boundary follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/src/routes/route-response.ts web server shared route response runtime boundary follow-up` | prod: yes | tests: yes | func: yes
 - [x] `packages/web-server/src/routes/analytics.constants.ts analytics route runtime constants boundary follow-up` | prod: yes | tests: yes | func: yes

packages/web-server/src/index.ts

@@ -49,9 +49,9 @@ import {
 import { createRuntimeServiceLogPayload } from './logging/request-scoped-error-log.js';
 import {
   API_DOCS_PATH,
+  createDocsRuntimeDiscoverySectionHtml,
   OPENAPI_DOCUMENT_PATH,
   RUNTIME_CONFIG_PATH,
-  RUNTIME_DISCOVERY_GUIDANCE_LINES,
 } from './runtime-discovery-guidance.js';
 import type { ServerRuntimePorts } from './routes/config-route-contracts.js';
 
@@ -67,6 +67,7 @@ export interface WebServerConfig {
 
 export type { IBotInstance } from './services/bot-bridge.service.js';
 export type { IWebApiAdapter } from './services/web-api-adapter.types.js';
+export { createDocsRuntimeDiscoverySectionHtml } from './runtime-discovery-guidance.js';
 
 type WebServerRuntimeConfig = Required<WebServerConfig>;
 type ShutdownProcess = Pick<NodeJS.Process, 'on' | 'off' | 'exit'>;
@@ -145,16 +146,6 @@ export function createDocsQuickReferenceHtml(): string {
   return DOCS_QUICK_REFERENCE_ENDPOINTS.map((endpoint) => createDocsEndpointCardHtml(endpoint)).join('');
 }
 
-export function createDocsRuntimeDiscoverySectionHtml(): string {
-  return `
-            <div class="endpoint" style="margin-top: 20px;">
-              <h3>Browser Runtime Discovery</h3>
-              <p>${RUNTIME_DISCOVERY_GUIDANCE_LINES.sameOrigin}</p>
-              <p>${RUNTIME_DISCOVERY_GUIDANCE_LINES.websocketFallback}</p>
-              <p>${RUNTIME_DISCOVERY_GUIDANCE_LINES.legacyRetry}</p>
-            </div>`;
-}
-
 export function createDocsOpenApiLinkHtml(): string {
   return `
             <div class="swagger-ui-link">

packages/web-server/src/middleware/request-logging.middleware.ts

@@ -24,29 +24,37 @@ export interface LoggingConfig {
   maxBodyLength?: number;
 }
 
-const defaultConfig: LoggingConfig = {
+export const DEFAULT_LOGGING_CONFIG: Required<LoggingConfig> = {
   logBody: false,
   logHeaders: false,
   excludePaths: ['/health'],
   maxBodyLength: 500,
 };
 
+export function resolveLoggingConfig(config: LoggingConfig = {}): Required<LoggingConfig> {
+  return {
+    ...DEFAULT_LOGGING_CONFIG,
+    ...config,
+    excludePaths: config.excludePaths ?? DEFAULT_LOGGING_CONFIG.excludePaths,
+  };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function getRequestBodyLogData(req: Request, config: LoggingConfig): unknown {
+function getRequestBodyLogData(req: Request, config: Required<LoggingConfig>): unknown {
   if (!config.logBody || !isRecord(req.body) || Object.keys(req.body).length === 0) {
     return undefined;
   }
 
   const bodyStr = JSON.stringify(req.body);
-  return bodyStr.length > (config.maxBodyLength || 500)
+  return bodyStr.length > config.maxBodyLength
     ? bodyStr.substring(0, config.maxBodyLength) + '...'
     : req.body;
 }
 
-function getHeaderLogData(req: Request, config: LoggingConfig): Record<string, unknown> | undefined {
+function getHeaderLogData(req: Request, config: Required<LoggingConfig>): Record<string, unknown> | undefined {
   if (!config.logHeaders) {
     return undefined;
   }
@@ -64,73 +72,92 @@ export function createRequestLogEntry(
   config: LoggingConfig,
   responseBody: unknown,
 ): Record<string, unknown> {
+  const resolvedConfig = resolveLoggingConfig(config);
   return createHttpLogPayload({
     method: req.method,
     path: req.path,
     query: Object.keys(req.query).length > 0 ? req.query : undefined,
     statusCode: res.statusCode,
     durationMs,
     responseSize: res.get('content-length') || 'unknown',
-    requestBody: getRequestBodyLogData(req, config),
-    headers: getHeaderLogData(req, config),
+    requestBody: getRequestBodyLogData(req, resolvedConfig),
+    headers: getHeaderLogData(req, resolvedConfig),
     requestId: resolveRequestId(req.headers['x-request-id']),
     responseBody,
   });
 }
 
+function shouldSkipRequestLogging(req: Request, config: Required<LoggingConfig>): boolean {
+  return config.excludePaths.some((path) => req.path === path);
+}
+
+function createResponseFinishLogger(
+  req: Request,
+  res: Response,
+  config: Required<LoggingConfig>,
+  startHrTime: [number, number],
+  getResponseBody: () => unknown,
+): () => void {
+  return () => {
+    const [seconds, nanoseconds] = process.hrtime(startHrTime);
+    const durationMs = seconds * 1000 + nanoseconds / 1000000;
+    const logData = createRequestLogEntry(req, res, durationMs, config, getResponseBody());
+
+    if (res.statusCode >= 400) {
+      console.error(`[HTTP] ${res.statusCode} ${req.method} ${req.path}`, logData);
+      return;
+    }
+
+    console.log(`[HTTP] ${res.statusCode} ${req.method} ${req.path}`, logData);
+  };
+}
+
+function createResponseErrorLogger(
+  req: Request,
+  res: Response,
+  startTime: number,
+  getResponseBody: () => unknown,
+): (error: unknown) => void {
+  return (error: unknown) => {
+    const duration = Date.now() - startTime;
+    const logData = createHttpResponseErrorLogPayload({
+      method: req.method,
+      path: req.path,
+      statusCode: res.statusCode,
+      durationMs: duration,
+      requestId: resolveRequestId(req.headers['x-request-id']),
+      error,
+      responseBody: getResponseBody(),
+    });
+    console.error(`[HTTP_ERROR] ${req.method} ${req.path}`, logData);
+  };
+}
+
 /**
  * Create request/response logging middleware
  */
 export function createRequestLoggingMiddleware(config: LoggingConfig = {}) {
-  const finalConfig = { ...defaultConfig, ...config };
+  const finalConfig = resolveLoggingConfig(config);
 
   return (req: Request, res: Response, next: NextFunction) => {
-    // Skip excluded paths
-    if (finalConfig.excludePaths?.some((path) => req.path === path)) {
+    if (shouldSkipRequestLogging(req, finalConfig)) {
       return next();
     }
 
-    // Start timer
     const startTime = Date.now();
     const startHrTime = process.hrtime();
 
-    // Capture response
     const originalSend = res.send;
     let responseBody: unknown = null;
+    const getResponseBody = () => responseBody;
 
     res.send = function (data: unknown) {
       responseBody = data;
       return originalSend.call(this, data);
     };
 
-    // Log on response finish
-    res.on('finish', () => {
-      const [seconds, nanoseconds] = process.hrtime(startHrTime);
-      const durationMs = seconds * 1000 + nanoseconds / 1000000;
-      const logData = createRequestLogEntry(req, res, durationMs, finalConfig, responseBody);
-
-      // Log response
-      if (res.statusCode >= 400) {
-        console.error(`[HTTP] ${res.statusCode} ${req.method} ${req.path}`, logData);
-      } else {
-        console.log(`[HTTP] ${res.statusCode} ${req.method} ${req.path}`, logData);
-      }
-    });
-
-    // Log on error
-    res.on('error', (error: unknown) => {
-      const duration = Date.now() - startTime;
-      const logData = createHttpResponseErrorLogPayload({
-        method: req.method,
-        path: req.path,
-        statusCode: res.statusCode,
-        durationMs: duration,
-        requestId: resolveRequestId(req.headers['x-request-id']),
-        error,
-        responseBody,
-      });
-      console.error(`[HTTP_ERROR] ${req.method} ${req.path}`, logData);
-    });
+    res.on('finish', createResponseFinishLogger(req, res, finalConfig, startHrTime, getResponseBody));
+    res.on('error', createResponseErrorLogger(req, res, startTime, getResponseBody));
 
     next();
   };

packages/web-server/src/runtime-discovery-guidance.ts

@@ -1,17 +1,39 @@
 export const API_DOCS_PATH = '/api/docs';
 export const OPENAPI_DOCUMENT_PATH = `${API_DOCS_PATH}/openapi.json`;
 export const RUNTIME_CONFIG_PATH = '/api/config/server';
+export const RUNTIME_DISCOVERY_GUIDANCE_HEADING = 'Browser Runtime Discovery';
 
 export const RUNTIME_DISCOVERY_GUIDANCE_LINES = {
   sameOrigin: 'Web clients resolve the API from the current origin first, then fall back to the default runtime port.',
   websocketFallback: 'WebSocket fallbacks should match the active browser protocol when runtime discovery is unavailable.',
   legacyRetry: 'The legacy compatibility config endpoint is retried only if runtime discovery fails.',
 } as const;
 
-export const RUNTIME_DISCOVERY_GUIDANCE_DESCRIPTION = [
+export const RUNTIME_DISCOVERY_GUIDANCE_PARAGRAPHS = [
   RUNTIME_DISCOVERY_GUIDANCE_LINES.sameOrigin,
   RUNTIME_DISCOVERY_GUIDANCE_LINES.websocketFallback,
   RUNTIME_DISCOVERY_GUIDANCE_LINES.legacyRetry,
-].join(' ');
+];
 
-export const DEFAULT_RUNTIME_API_SERVER_DESCRIPTION = `Default runtime API server. ${RUNTIME_DISCOVERY_GUIDANCE_LINES.sameOrigin}`;
+export function createRuntimeDiscoveryGuidanceDescription(
+  paragraphs: readonly string[] = RUNTIME_DISCOVERY_GUIDANCE_PARAGRAPHS,
+): string {
+  return paragraphs.join(' ');
+}
+
+export function createRuntimeApiServerDescription(): string {
+  return `Default runtime API server. ${RUNTIME_DISCOVERY_GUIDANCE_LINES.sameOrigin}`;
+}
+
+export function createDocsRuntimeDiscoverySectionHtml(
+  paragraphs: readonly string[] = RUNTIME_DISCOVERY_GUIDANCE_PARAGRAPHS,
+): string {
+  return `
+            <div class="endpoint" style="margin-top: 20px;">
+              <h3>${RUNTIME_DISCOVERY_GUIDANCE_HEADING}</h3>
+              ${paragraphs.map((paragraph) => `<p>${paragraph}</p>`).join('\n              ')}
+            </div>`;
+}
+
+export const RUNTIME_DISCOVERY_GUIDANCE_DESCRIPTION = createRuntimeDiscoveryGuidanceDescription();
+export const DEFAULT_RUNTIME_API_SERVER_DESCRIPTION = createRuntimeApiServerDescription();