@webda/debug 4.0.0-beta.3

package/LICENSE

@@ -0,0 +1,166 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

package/README.md

@@ -0,0 +1,95 @@
+# @webda/debug module
+
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+# @webda/debug
+
+> Development debug server for Webda — live request log, real-time WebSocket event feed, log buffer, and an introspection API to inspect models, routes, services, and operations while `webda debug` is running.
+
+## When to use it
+
+- You are running `webda debug` locally and want a dashboard that shows incoming HTTP requests, live logs, and application structure in real time.
+- You need programmatic access to the Webda application's routes, models, services, and operations via an HTTP introspection API during development.
+- You want structured request tracing (method, URL, status, duration) without adding production observability overhead.
+
+## Install
+
+```bash
+pnpm add @webda/debug
+```
+
+## Configuration
+
+```json
+{
+  "services": {
+    "debugService": {
+      "type": "DebugService"
+    }
+  }
+}
+```
+
+`DebugService` listens on port **18181** by default. No additional parameters are required for basic use — the service auto-wires to core events on `resolve()`.
+
+## Usage
+
+```typescript
+// Typically you don't instantiate DebugService directly.
+// It is auto-registered when you run:
+//   webda debug
+//
+// The service exposes:
+//   GET  http://localhost:18181/         → Serves the built-in debug web UI
+//   GET  http://localhost:18181/api/...  → Introspection endpoints:
+//     /api/routes     — registered routes
+//     /api/models     — model definitions
+//     /api/services   — active services
+//     /api/operations — registered operations
+//     /api/config     — resolved configuration
+//   WS   ws://localhost:18181/ws         → Live event push (requests + logs)
+
+// To manually start the debug server in tests:
+import { DebugService } from "@webda/debug";
+import { Core } from "@webda/core";
+
+const debug = await new DebugService(Core.get(), "debugService").resolve().init();
+// Connects to port 18181 — open http://localhost:18181 in a browser
+await debug.stop();
+```
+
+## Reference
+
+- API reference: see the auto-generated typedoc at `docs/pages/Modules/debug/`.
+- Source: [`packages/debug`](https://github.com/loopingz/webda.io/tree/main/packages/debug)
+- Related: [`@webda/otel`](../otel) for production-grade OpenTelemetry tracing; [`@webda/workout`](../workout) for the logging system whose output this service buffers.
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/bodycapture.d.ts

@@ -0,0 +1,66 @@
+import type { RequestLogBody } from "./requestlog.js";
+/**
+ * Decide whether a Content-Type header value indicates a text payload.
+ *
+ * Matches `text/*`, JSON-shaped types (including `+json` suffix variants
+ * like `application/vnd.foo+json`), urlencoded forms, XML, JS, and ECMAScript.
+ *
+ * @param contentType - The Content-Type header value (or `undefined`).
+ * @returns `true` if the type is a known text type, `false` otherwise.
+ */
+export declare function isTextContentType(contentType: string | undefined): boolean;
+/**
+ * Heuristic: sniff a buffer to see if it looks like text.
+ *
+ * Used when the Content-Type header is missing. We declare a buffer text-y if
+ * the inspected prefix consists entirely of printable ASCII / common
+ * whitespace bytes; the presence of a NUL byte or a high-bit byte that is not
+ * part of valid UTF-8 multibyte sequences flips it to binary.
+ *
+ * The conservative behavior is fine — if we get it wrong we still emit a
+ * usable representation.
+ *
+ * @param buffer - The buffer to inspect.
+ * @param sample - Maximum bytes to inspect (default 1024).
+ * @returns `true` if the prefix looks like text, `false` otherwise.
+ */
+export declare function looksLikeText(buffer: Buffer, sample?: number): boolean;
+/**
+ * Format the first `count` bytes of a buffer as a lowercase hex string.
+ *
+ * Used to give a fingerprint for binary payloads (e.g. `89504e47` for PNG)
+ * without storing the raw bytes.
+ *
+ * @param buffer - The buffer to read from.
+ * @param count - Number of bytes to include in the preview.
+ * @returns A hex string of the first `count` bytes (or the whole buffer if shorter).
+ */
+export declare function hexPreview(buffer: Buffer, count: number): string;
+/**
+ * Convert a buffer + content-type into a `RequestLogBody` capture record.
+ *
+ * Rules:
+ * - Empty buffer → `{ kind: "empty" }`.
+ * - Text (by Content-Type or sniff): store as `text` if size ≤ `bodyLimit`,
+ *   else `text-truncated` with the first `bodyLimit` bytes as `content`.
+ * - Binary: `{ kind: "binary", size, preview }` — only the byte length and a
+ *   short hex preview are kept.
+ *
+ * @param buffer - Buffer holding the payload (may be empty).
+ * @param contentType - Value of the Content-Type header, if known.
+ * @param bodyLimit - Maximum number of bytes to keep inline for text payloads.
+ * @param binaryPreview - Number of bytes to include in the hex preview for binary payloads.
+ * @returns A normalized `RequestLogBody` describing the payload.
+ */
+export declare function captureBody(buffer: Buffer, contentType: string | undefined, bodyLimit: number, binaryPreview: number): RequestLogBody;
+/**
+ * Normalize a request/response headers record into `Record<string, string>`.
+ *
+ * - `undefined`/`null` values are dropped.
+ * - Array values (e.g. multiple Set-Cookie) are joined with `, `.
+ * - Other values are coerced via `String()`.
+ *
+ * @param headers - The raw headers object (may be `undefined`).
+ * @returns A flat string-valued record (always an object, possibly empty).
+ */
+export declare function normalizeHeaders(headers: Record<string, string | string[] | number | undefined> | undefined): Record<string, string>;

package/lib/bodycapture.js

@@ -0,0 +1,162 @@
+/**
+ * Content types that we treat as text (and therefore store inline up to the
+ * configured size limit). Anything not matched here is treated as binary
+ * — only its size and a short hex preview are kept.
+ */
+const TEXT_CONTENT_TYPES = [
+    "application/json",
+    "application/x-www-form-urlencoded",
+    "application/xml",
+    "application/javascript",
+    "application/ecmascript"
+];
+/**
+ * Decide whether a Content-Type header value indicates a text payload.
+ *
+ * Matches `text/*`, JSON-shaped types (including `+json` suffix variants
+ * like `application/vnd.foo+json`), urlencoded forms, XML, JS, and ECMAScript.
+ *
+ * @param contentType - The Content-Type header value (or `undefined`).
+ * @returns `true` if the type is a known text type, `false` otherwise.
+ */
+export function isTextContentType(contentType) {
+    if (!contentType)
+        return false;
+    const ct = contentType.split(";")[0].trim().toLowerCase();
+    if (!ct)
+        return false;
+    if (ct.startsWith("text/"))
+        return true;
+    if (ct.endsWith("+json") || ct.endsWith("+xml"))
+        return true;
+    return TEXT_CONTENT_TYPES.includes(ct);
+}
+/**
+ * Heuristic: sniff a buffer to see if it looks like text.
+ *
+ * Used when the Content-Type header is missing. We declare a buffer text-y if
+ * the inspected prefix consists entirely of printable ASCII / common
+ * whitespace bytes; the presence of a NUL byte or a high-bit byte that is not
+ * part of valid UTF-8 multibyte sequences flips it to binary.
+ *
+ * The conservative behavior is fine — if we get it wrong we still emit a
+ * usable representation.
+ *
+ * @param buffer - The buffer to inspect.
+ * @param sample - Maximum bytes to inspect (default 1024).
+ * @returns `true` if the prefix looks like text, `false` otherwise.
+ */
+export function looksLikeText(buffer, sample = 1024) {
+    if (buffer.length === 0)
+        return true;
+    const limit = Math.min(buffer.length, sample);
+    let i = 0;
+    while (i < limit) {
+        const byte = buffer[i];
+        // Null bytes are a strong signal that this is binary
+        if (byte === 0)
+            return false;
+        // Tab, LF, CR, and printable ASCII range
+        if (byte === 0x09 || byte === 0x0a || byte === 0x0d || (byte >= 0x20 && byte <= 0x7e)) {
+            i++;
+            continue;
+        }
+        // High-bit byte: must begin a valid UTF-8 multibyte sequence
+        let extra = 0;
+        if (byte >= 0xc2 && byte <= 0xdf)
+            extra = 1; // 2-byte sequence
+        else if (byte >= 0xe0 && byte <= 0xef)
+            extra = 2; // 3-byte sequence
+        else if (byte >= 0xf0 && byte <= 0xf4)
+            extra = 3; // 4-byte sequence
+        else
+            return false;
+        if (i + extra >= limit) {
+            // Sequence extends past the inspected window — accept the prefix as text.
+            return true;
+        }
+        for (let k = 1; k <= extra; k++) {
+            const cont = buffer[i + k];
+            if (cont < 0x80 || cont > 0xbf)
+                return false;
+        }
+        i += extra + 1;
+    }
+    return true;
+}
+/**
+ * Format the first `count` bytes of a buffer as a lowercase hex string.
+ *
+ * Used to give a fingerprint for binary payloads (e.g. `89504e47` for PNG)
+ * without storing the raw bytes.
+ *
+ * @param buffer - The buffer to read from.
+ * @param count - Number of bytes to include in the preview.
+ * @returns A hex string of the first `count` bytes (or the whole buffer if shorter).
+ */
+export function hexPreview(buffer, count) {
+    if (count <= 0 || buffer.length === 0)
+        return "";
+    return buffer.subarray(0, Math.min(count, buffer.length)).toString("hex");
+}
+/**
+ * Convert a buffer + content-type into a `RequestLogBody` capture record.
+ *
+ * Rules:
+ * - Empty buffer → `{ kind: "empty" }`.
+ * - Text (by Content-Type or sniff): store as `text` if size ≤ `bodyLimit`,
+ *   else `text-truncated` with the first `bodyLimit` bytes as `content`.
+ * - Binary: `{ kind: "binary", size, preview }` — only the byte length and a
+ *   short hex preview are kept.
+ *
+ * @param buffer - Buffer holding the payload (may be empty).
+ * @param contentType - Value of the Content-Type header, if known.
+ * @param bodyLimit - Maximum number of bytes to keep inline for text payloads.
+ * @param binaryPreview - Number of bytes to include in the hex preview for binary payloads.
+ * @returns A normalized `RequestLogBody` describing the payload.
+ */
+export function captureBody(buffer, contentType, bodyLimit, binaryPreview) {
+    if (!buffer || buffer.length === 0) {
+        return { kind: "empty" };
+    }
+    const isText = contentType ? isTextContentType(contentType) : looksLikeText(buffer);
+    if (!isText) {
+        return { kind: "binary", size: buffer.length, preview: hexPreview(buffer, binaryPreview) };
+    }
+    // Text path
+    if (buffer.length <= bodyLimit) {
+        return { kind: "text", content: buffer.toString("utf8"), size: buffer.length };
+    }
+    return {
+        kind: "text-truncated",
+        content: buffer.subarray(0, bodyLimit).toString("utf8"),
+        size: buffer.length
+    };
+}
+/**
+ * Normalize a request/response headers record into `Record<string, string>`.
+ *
+ * - `undefined`/`null` values are dropped.
+ * - Array values (e.g. multiple Set-Cookie) are joined with `, `.
+ * - Other values are coerced via `String()`.
+ *
+ * @param headers - The raw headers object (may be `undefined`).
+ * @returns A flat string-valued record (always an object, possibly empty).
+ */
+export function normalizeHeaders(headers) {
+    const result = {};
+    if (!headers)
+        return result;
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            result[key] = value.join(", ");
+        }
+        else {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=bodycapture.js.map

package/lib/bodycapture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodycapture.js","sourceRoot":"","sources":["../src/bodycapture.ts"],"names":[],"mappings":"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"}

package/lib/debugservice.service.d.ts

@@ -0,0 +1,166 @@
+import { Service, ServiceParameters } from "@webda/core";
+import { RequestLog } from "./requestlog.js";
+import { CancelablePromise } from "@webda/utils";
+/**
+ * Determine whether the given Origin header value is allowed to access the debug API.
+ *
+ * Allowed origins:
+ * - http://localhost:3000 (docs dev server)
+ * - http://127.0.0.1:3000 (docs dev server, alternate address)
+ * - https://webda.io (production docs)
+ * - https://*.webda.io (any HTTPS subdomain of webda.io)
+ *
+ * @param origin - The value of the HTTP `Origin` request header.
+ * @returns `true` if the origin is allowed, `false` otherwise.
+ */
+export declare function isAllowedOrigin(origin: string | undefined): boolean;
+/**
+ * Configuration parameters for the {@link DebugService}.
+ *
+ * All capture knobs default to safe values — capture is enabled with a
+ * 64 KB inline body limit and a 4-byte hex preview for binary payloads.
+ */
+export declare class DebugServiceParameters extends ServiceParameters {
+    /**
+     * Whether to capture request/response headers and bodies for the debug UI.
+     * If `false`, only status code and duration are recorded.
+     */
+    captureRequests: boolean;
+    /**
+     * Maximum number of bytes to keep inline for text bodies. Larger payloads
+     * are truncated to this size and reported as `text-truncated`.
+     */
+    captureBodyLimit: number;
+    /**
+     * Number of leading bytes to include in the hex preview for binary bodies.
+     */
+    captureBinaryPreview: number;
+}
+/**
+ * Debug dashboard service that provides an HTTP API for introspection
+ * and a WebSocket feed of live request events.
+ *
+ * @WebdaModda
+ */
+export declare class DebugService extends Service<DebugServiceParameters> {
+    static Parameters: typeof DebugServiceParameters;
+    /** Ring buffer of recent HTTP requests */
+    requestLog: RequestLog;
+    /** Ring buffer of application log entries */
+    private logBuffer;
+    /** HTTP server for the debug API */
+    private server?;
+    /** WebSocket server for live event push */
+    private wss?;
+    /** Connected WebSocket clients */
+    private clients;
+    /** Unsubscribe functions for core event listeners */
+    private unsubscribers;
+    /** Terminal UI of the running debug command */
+    private tui?;
+    /** Settle the running debug command */
+    private running?;
+    /** Timing map: requestId -> start timestamp */
+    private timings;
+    /**
+     * Resolve the typed parameters and the capture knobs (with safe defaults
+     * when the surrounding test environment does not load real parameters).
+     *
+     * @returns The effective `{ captureRequests, captureBodyLimit, captureBinaryPreview }` triple.
+     */
+    private getCaptureSettings;
+    /**
+     * Subscribe to core events to populate the request log.
+     * @returns this for chaining
+     */
+    resolve(): this;
+    /**
+     * Wire up core event listeners for request tracking.
+     */
+    private subscribeToEvents;
+    /**
+     * Collect headers, bodies, and any error from a finished context.
+     *
+     * Returns `undefined` if capture is disabled via configuration. Resolves
+     * once both request body (read via the HttpContext, which caches its
+     * Buffer after the first read) and response body (read from the
+     * WebContext's buffered output stream) have been captured. Failures
+     * during capture (e.g. a body that can't be read or that times out) are
+     * swallowed so the debug service never breaks the request itself.
+     *
+     * @param ctx - The finished web context.
+     * @returns A {@link RequestLogDetails} payload, or `undefined` when capture is off.
+     */
+    private collectDetails;
+    /**
+     * Start the application HTTP server and the debug HTTP+WS server.
+     *
+     * @param port - Port for the debug dashboard API
+     * @param servePort - Port for the application HTTP server
+     * @param web - Disable TUI and only serve the web dashboard
+     * @returns a promise settled once the service stops or the TUI quits
+     */
+    debug(
+    /** @alias p @description Debug dashboard port */
+    port?: number, 
+    /** @alias s @description Application server port */
+    servePort?: number, 
+    /** @description Disable TUI and only serve the web dashboard */
+    web?: boolean): CancelablePromise<void>;
+    /**
+     * Start the application server, the debug server and the TUI or browser
+     *
+     * @param port - Port for the debug dashboard API
+     * @param servePort - Port for the application HTTP server
+     * @param web - Disable TUI and only serve the web dashboard
+     */
+    protected startDebug(port: number, servePort: number, web?: boolean): Promise<void>;
+    /**
+     * Settle the running debug command
+     */
+    private settle;
+    /**
+     * Open a URL in the default browser.
+     * @param url - URL to open
+     */
+    private openBrowser;
+    /**
+     * Create and start the debug HTTP server with WebSocket support.
+     * @param port - Port to listen on
+     */
+    startDebugServer(port: number): Promise<void>;
+    /**
+     * Route incoming HTTP requests to introspection handlers.
+     * @param req - Incoming HTTP request
+     * @param res - Server response
+     */
+    private handleRequest;
+    /**
+     * Build an OpenAPI spec from the router.
+     * @returns OpenAPI document or a stub if the router is unavailable
+     */
+    private getOpenAPISpec;
+    /**
+     * Serve a static file from the webui directory.
+     * Falls back to index.html for SPA-style routing.
+     * @param pathname - Request pathname
+     * @param res - Server response
+     */
+    private serveStaticFile;
+    /**
+     * Write a JSON response.
+     * @param res - Server response
+     * @param data - Data to serialize
+     * @param statusCode - HTTP status code
+     */
+    private sendJson;
+    /**
+     * Broadcast a message to all connected WebSocket clients.
+     * @param data - Data to send (will be JSON-serialized)
+     */
+    broadcast(data: unknown): void;
+    /**
+     * Clean up HTTP server and WebSocket connections.
+     */
+    stop(): Promise<void>;
+}