@j0hanz/superfetch 2.2.1 → 2.3.0

package/dist/markdown-cleanup.js

@@ -0,0 +1,283 @@
+/**
+ * Markdown cleanup utilities for post-processing converted content.
+ *
+ * Goals:
+ * - Never mutate fenced code blocks (``` / ~~~) content.
+ * - Keep rules localized and readable.
+ * - Avoid multi-pass regexes that accidentally hit code blocks.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Fence state helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function isFenceStart(line) {
+    const trimmed = line.trimStart();
+    return trimmed.startsWith('```') || trimmed.startsWith('~~~');
+}
+function extractFenceMarker(line) {
+    const trimmed = line.trimStart();
+    const match = /^(`{3,}|~{3,})/.exec(trimmed);
+    return match?.[1] ?? '```';
+}
+function isFenceEnd(line, marker) {
+    const trimmed = line.trimStart();
+    return (trimmed.startsWith(marker) && trimmed.slice(marker.length).trim() === '');
+}
+function initialFenceState() {
+    return { inFence: false, marker: '' };
+}
+function advanceFenceState(line, state) {
+    if (!state.inFence && isFenceStart(line)) {
+        state.inFence = true;
+        state.marker = extractFenceMarker(line);
+        return;
+    }
+    if (state.inFence && isFenceEnd(line, state.marker)) {
+        state.inFence = false;
+        state.marker = '';
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Segment utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Split markdown into segments where each segment is either fully inside
+ * a fenced block (including the fence lines), or fully outside.
+ */
+function splitByFences(content) {
+    const lines = content.split('\n');
+    const segments = [];
+    const state = initialFenceState();
+    let current = [];
+    let currentIsFence = false;
+    for (const line of lines) {
+        // Transition into fence: flush outside segment first.
+        if (!state.inFence && isFenceStart(line)) {
+            if (current.length > 0) {
+                segments.push({ content: current.join('\n'), inFence: currentIsFence });
+                current = [];
+            }
+            currentIsFence = true;
+            current.push(line);
+            advanceFenceState(line, state);
+            continue;
+        }
+        current.push(line);
+        const wasInFence = state.inFence;
+        advanceFenceState(line, state);
+        // Transition out of fence: flush fence segment.
+        if (wasInFence && !state.inFence) {
+            segments.push({ content: current.join('\n'), inFence: true });
+            current = [];
+            currentIsFence = false;
+        }
+    }
+    if (current.length > 0) {
+        segments.push({ content: current.join('\n'), inFence: currentIsFence });
+    }
+    return segments;
+}
+/**
+ * Apply a transformation function only to non-fenced content.
+ */
+function mapOutsideFences(content, transform) {
+    const segments = splitByFences(content);
+    return segments
+        .map((seg) => (seg.inFence ? seg.content : transform(seg.content)))
+        .join('\n');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Cleanup rules (OUTSIDE fences only)
+// ─────────────────────────────────────────────────────────────────────────────
+function removeEmptyHeadings(text) {
+    return text.replace(/^#{1,6}[ \t\u00A0]*$\r?\n?/gm, '');
+}
+function fixOrphanHeadings(text) {
+    // Pattern: hashes on their own line, blank line, then a "heading-like" line.
+    return text.replace(/^(.*?)(#{1,6})\s*(?:\r?\n){2}([A-Z][^\r\n]+?)(?:\r?\n)/gm, (_match, prefix, hashes, heading) => {
+        if (heading.length > 150)
+            return _match;
+        const trimmedPrefix = prefix.trim();
+        if (trimmedPrefix === '') {
+            return `${hashes} ${heading}\n\n`;
+        }
+        return `${trimmedPrefix}\n\n${hashes} ${heading}\n\n`;
+    });
+}
+function removeSkipLinksAndEmptyAnchors(text) {
+    const zeroWidthAnchorLink = /\[(?:\s|\u200B)*\]\(#[^)]*\)\s*/g;
+    return text
+        .replace(zeroWidthAnchorLink, '')
+        .replace(/^\[Skip to (?:main )?content\]\(#[^)]*\)\s*$/gim, '')
+        .replace(/^\[Skip to (?:main )?navigation\]\(#[^)]*\)\s*$/gim, '')
+        .replace(/^\[Skip link\]\(#[^)]*\)\s*$/gim, '');
+}
+function ensureBlankLineAfterHeadings(text) {
+    // Heading followed immediately by a fence marker
+    text = text.replace(/(^#{1,6}\s+\w+)```/gm, '$1\n\n```');
+    // Heuristic: Some converters jam words together after a heading
+    text = text.replace(/(^#{1,6}\s+\w*[A-Z])([A-Z][a-z])/gm, '$1\n\n$2');
+    // Any heading line should be followed by a blank line before body
+    return text.replace(/(^#{1,6}\s[^\n]*)\n([^\n])/gm, '$1\n\n$2');
+}
+/**
+ * Remove markdown TOC blocks of the form:
+ * - [Title](#anchor)
+ * outside fenced code blocks.
+ */
+function removeTocBlocks(text) {
+    const tocLine = /^- \[[^\]]+\]\(#[^)]+\)\s*$/;
+    const lines = text.split('\n');
+    const out = [];
+    let skipping = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const prev = i > 0 ? (lines[i - 1] ?? '') : '';
+        const next = i < lines.length - 1 ? (lines[i + 1] ?? '') : '';
+        if (tocLine.test(line)) {
+            const prevIsToc = tocLine.test(prev) || prev.trim() === '';
+            const nextIsToc = tocLine.test(next) || next.trim() === '';
+            if (prevIsToc || nextIsToc) {
+                skipping = true;
+                continue;
+            }
+        }
+        if (skipping) {
+            if (line.trim() === '') {
+                skipping = false;
+            }
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+function tidyLinksAndEscapes(text) {
+    return text
+        .replace(/\]\(([^)]+)\)\[/g, ']($1)\n\n[')
+        .replace(/^Was this page helpful\??\s*$/gim, '')
+        .replace(/(`[^`]+`)\s*\\-\s*/g, '$1 - ')
+        .replace(/\\([[]])/g, '$1');
+}
+function normalizeListsAndSpacing(text) {
+    // Ensure blank line before list starts (bullet/ordered)
+    text = text.replace(/([^\n])\n([-*+] )/g, '$1\n\n$2');
+    text = text.replace(/(\S)\n(\d+\. )/g, '$1\n\n$2');
+    // Collapse excessive blank lines
+    return text.replace(/\n{3,}/g, '\n\n');
+}
+const CLEANUP_STEPS = [
+    fixOrphanHeadings,
+    removeEmptyHeadings,
+    removeSkipLinksAndEmptyAnchors,
+    ensureBlankLineAfterHeadings,
+    removeTocBlocks,
+    tidyLinksAndEscapes,
+    normalizeListsAndSpacing,
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Clean up common markdown artifacts and formatting issues.
+ * IMPORTANT: All rules are applied ONLY outside fenced code blocks.
+ */
+export function cleanupMarkdownArtifacts(content) {
+    if (!content)
+        return '';
+    const cleaned = mapOutsideFences(content, (outside) => {
+        return CLEANUP_STEPS.reduce((text, step) => step(text), outside);
+    });
+    return cleaned.trim();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Heading Promotion (fence-aware)
+// ─────────────────────────────────────────────────────────────────────────────
+const HEADING_KEYWORDS = new Set([
+    'overview',
+    'introduction',
+    'summary',
+    'conclusion',
+    'prerequisites',
+    'requirements',
+    'installation',
+    'configuration',
+    'usage',
+    'features',
+    'limitations',
+    'troubleshooting',
+    'faq',
+    'resources',
+    'references',
+    'changelog',
+    'license',
+    'acknowledgments',
+    'appendix',
+]);
+function isLikelyHeadingLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.length > 80)
+        return false;
+    if (/^#{1,6}\s/.test(trimmed))
+        return false;
+    if (/^[-*+•]\s/.test(trimmed) || /^\d+\.\s/.test(trimmed))
+        return false;
+    if (/[.!?]$/.test(trimmed))
+        return false;
+    if (/^\[.*\]\(.*\)$/.test(trimmed))
+        return false;
+    if (/^(?:example|note|tip|warning|important|caution):\s+\S/i.test(trimmed)) {
+        return true;
+    }
+    const words = trimmed.split(/\s+/);
+    if (words.length >= 2 && words.length <= 6) {
+        const isTitleCase = words.every((w) => /^[A-Z][a-z]*$/.test(w) || /^(?:and|or|the|of|in|for|to|a)$/i.test(w));
+        if (isTitleCase)
+            return true;
+    }
+    if (words.length === 1) {
+        const lower = trimmed.toLowerCase();
+        if (HEADING_KEYWORDS.has(lower) && /^[A-Z]/.test(trimmed))
+            return true;
+    }
+    return false;
+}
+function shouldPromoteToHeading(line, prevLine) {
+    const isPrecededByBlank = prevLine.trim() === '';
+    if (!isPrecededByBlank)
+        return false;
+    return isLikelyHeadingLine(line);
+}
+function formatAsHeading(line) {
+    const trimmed = line.trim();
+    const isExample = /^example:\s/i.test(trimmed);
+    const prefix = isExample ? '### ' : '## ';
+    return prefix + trimmed;
+}
+function processNonFencedLine(line, prevLine) {
+    if (shouldPromoteToHeading(line, prevLine)) {
+        return formatAsHeading(line);
+    }
+    return line;
+}
+/**
+ * Promote standalone lines that look like headings to proper markdown headings.
+ * Fence-aware: never modifies content inside fenced code blocks.
+ */
+export function promoteOrphanHeadings(markdown) {
+    if (!markdown)
+        return '';
+    const lines = markdown.split('\n');
+    const result = [];
+    const state = initialFenceState();
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const prevLine = i > 0 ? (lines[i - 1] ?? '') : '';
+        if (state.inFence || isFenceStart(line)) {
+            result.push(line);
+            advanceFenceState(line, state);
+            continue;
+        }
+        result.push(processNonFencedLine(line, prevLine));
+    }
+    return result.join('\n');
+}

package/dist/mcp-validator.d.ts

@@ -0,0 +1,14 @@
+export type JsonRpcId = string | number | null;
+export interface McpRequestParams {
+    _meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface McpRequestBody {
+    jsonrpc: '2.0';
+    method: string;
+    id?: JsonRpcId;
+    params?: McpRequestParams;
+}
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
+export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;
+export declare function acceptsEventStream(header: string | null | undefined): boolean;

package/dist/mcp-validator.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+// --- Validation ---
+const paramsSchema = z.looseObject({});
+const mcpRequestSchema = z.looseObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number(), z.null()]).optional(),
+    params: paramsSchema.optional(),
+});
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
+}
+export function isMcpRequestBody(body) {
+    return mcpRequestSchema.safeParse(body).success;
+}
+export function acceptsEventStream(header) {
+    if (!header)
+        return false;
+    return header
+        .split(',')
+        .some((value) => value.trim().toLowerCase().startsWith('text/event-stream'));
+}

package/dist/mcp.d.ts

@@ -1,4 +1,3 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function createMcpServer(): McpServer;
 export declare function startStdioServer(): Promise<void>;
-//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -118,4 +118,3 @@ export async function startStdioServer() {
     registerSignalHandlers(createShutdownHandler(server));
     await connectStdioServer(server, transport);
 }
-//# sourceMappingURL=mcp.js.map

package/dist/observability.d.ts

@@ -13,5 +13,5 @@ export declare function logDebug(message: string, meta?: LogMetadata): void;
 export declare function logWarn(message: string, meta?: LogMetadata): void;
 export declare function logError(message: string, error?: Error | LogMetadata): void;
 export declare function redactUrl(rawUrl: string): string;
+export declare function redactHeaders(headers: Record<string, unknown>): Record<string, unknown>;
 export {};
-//# sourceMappingURL=observability.d.ts.map

package/dist/observability.js

@@ -13,7 +13,7 @@ export function getSessionId() {
 export function getOperationId() {
     return requestContext.getStore()?.operationId;
 }
-function formatMetadata(meta) {
+function buildContextMetadata() {
     const requestId = getRequestId();
     const sessionId = getSessionId();
     const operationId = getOperationId();
@@ -24,7 +24,10 @@ function formatMetadata(meta) {
         contextMeta.sessionId = sessionId;
     if (operationId)
         contextMeta.operationId = operationId;
-    const merged = { ...contextMeta, ...meta };
+    return contextMeta;
+}
+function formatMetadata(meta) {
+    const merged = { ...buildContextMetadata(), ...meta };
     return Object.keys(merged).length > 0 ? ` ${JSON.stringify(merged)}` : '';
 }
 function createTimestamp() {
@@ -73,4 +76,13 @@ export function redactUrl(rawUrl) {
         return rawUrl;
     }
 }
-//# sourceMappingURL=observability.js.map
+export function redactHeaders(headers) {
+    const redacted = { ...headers };
+    const sensitiveKeys = ['authorization', 'cookie', 'set-cookie', 'x-api-key'];
+    for (const key of Object.keys(redacted)) {
+        if (sensitiveKeys.includes(key.toLowerCase())) {
+            redacted[key] = '[REDACTED]';
+        }
+    }
+    return redacted;
+}

package/dist/server-tuning.d.ts

@@ -0,0 +1,9 @@
+export interface HttpServerTuningTarget {
+    headersTimeout?: number;
+    requestTimeout?: number;
+    keepAliveTimeout?: number;
+    closeIdleConnections?: () => void;
+    closeAllConnections?: () => void;
+}
+export declare function applyHttpServerTuning(server: HttpServerTuningTarget): void;
+export declare function drainConnectionsOnShutdown(server: HttpServerTuningTarget): void;

package/dist/server-tuning.js

@@ -0,0 +1,30 @@
+import { config } from './config.js';
+import { logDebug } from './observability.js';
+export function applyHttpServerTuning(server) {
+    const { headersTimeoutMs, requestTimeoutMs, keepAliveTimeoutMs } = config.server.http;
+    if (headersTimeoutMs !== undefined) {
+        server.headersTimeout = headersTimeoutMs;
+    }
+    if (requestTimeoutMs !== undefined) {
+        server.requestTimeout = requestTimeoutMs;
+    }
+    if (keepAliveTimeoutMs !== undefined) {
+        server.keepAliveTimeout = keepAliveTimeoutMs;
+    }
+}
+export function drainConnectionsOnShutdown(server) {
+    const { shutdownCloseAllConnections, shutdownCloseIdleConnections } = config.server.http;
+    if (shutdownCloseAllConnections) {
+        if (typeof server.closeAllConnections === 'function') {
+            server.closeAllConnections();
+            logDebug('Closed all HTTP connections during shutdown');
+        }
+        return;
+    }
+    if (shutdownCloseIdleConnections) {
+        if (typeof server.closeIdleConnections === 'function') {
+            server.closeIdleConnections();
+            logDebug('Closed idle HTTP connections during shutdown');
+        }
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,36 @@
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+export interface SessionEntry {
+    readonly transport: StreamableHTTPServerTransport;
+    createdAt: number;
+    lastSeen: number;
+    protocolInitialized: boolean;
+}
+export interface SessionStore {
+    get: (sessionId: string) => SessionEntry | undefined;
+    touch: (sessionId: string) => void;
+    set: (sessionId: string, entry: SessionEntry) => void;
+    remove: (sessionId: string) => SessionEntry | undefined;
+    size: () => number;
+    inFlight: () => number;
+    incrementInFlight: () => void;
+    decrementInFlight: () => void;
+    clear: () => SessionEntry[];
+    evictExpired: () => SessionEntry[];
+    evictOldest: () => SessionEntry | undefined;
+}
+export interface SlotTracker {
+    readonly releaseSlot: () => void;
+    readonly markInitialized: () => void;
+    readonly isInitialized: () => boolean;
+}
+export type CloseHandler = (() => void) | undefined;
+export declare function composeCloseHandlers(first: CloseHandler, second: CloseHandler): CloseHandler;
+export declare function startSessionCleanupLoop(store: SessionStore, sessionTtlMs: number): AbortController;
+export declare function createSessionStore(sessionTtlMs: number): SessionStore;
+export declare function createSlotTracker(store: SessionStore): SlotTracker;
+export declare function reserveSessionSlot(store: SessionStore, maxSessions: number): boolean;
+export declare function ensureSessionCapacity({ store, maxSessions, evictOldest, }: {
+    store: SessionStore;
+    maxSessions: number;
+    evictOldest: (store: SessionStore) => boolean;
+}): boolean;

package/dist/session.js

@@ -0,0 +1,159 @@
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
+import { logInfo, logWarn } from './observability.js';
+export function composeCloseHandlers(first, second) {
+    if (!first)
+        return second;
+    if (!second)
+        return first;
+    return () => {
+        try {
+            first();
+        }
+        finally {
+            second();
+        }
+    };
+}
+// --- Session Store ---
+function getCleanupIntervalMs(sessionTtlMs) {
+    return Math.min(Math.max(Math.floor(sessionTtlMs / 2), 10000), 60000);
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function handleSessionCleanupError(error) {
+    if (isAbortError(error)) {
+        return;
+    }
+    logWarn('Session cleanup loop failed', {
+        error: error instanceof Error ? error.message : 'Unknown error',
+    });
+}
+function moveSessionToEnd(sessions, sessionId, session) {
+    sessions.delete(sessionId);
+    sessions.set(sessionId, session);
+}
+function isSessionExpired(session, now, sessionTtlMs) {
+    return now - session.lastSeen > sessionTtlMs;
+}
+async function runSessionCleanupLoop(store, sessionTtlMs, signal) {
+    const intervalMs = getCleanupIntervalMs(sessionTtlMs);
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
+        signal,
+        ref: false,
+    })) {
+        const evicted = store.evictExpired();
+        for (const session of evicted) {
+            void session.transport.close().catch((err) => {
+                logWarn('Failed to close expired session', {
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            });
+        }
+        if (evicted.length > 0) {
+            logInfo('Expired sessions evicted', {
+                evicted: evicted.length,
+                timestamp: new Date(getNow()).toISOString(),
+            });
+        }
+    }
+}
+export function startSessionCleanupLoop(store, sessionTtlMs) {
+    const controller = new AbortController();
+    void runSessionCleanupLoop(store, sessionTtlMs, controller.signal).catch(handleSessionCleanupError);
+    return controller;
+}
+export function createSessionStore(sessionTtlMs) {
+    const sessions = new Map();
+    let inflight = 0;
+    return {
+        get: (sessionId) => sessions.get(sessionId),
+        touch: (sessionId) => {
+            const session = sessions.get(sessionId);
+            if (session) {
+                session.lastSeen = Date.now();
+                // Move to end (LRU behavior if needed, but Map insertion order)
+                moveSessionToEnd(sessions, sessionId, session);
+            }
+        },
+        set: (sessionId, entry) => {
+            sessions.set(sessionId, entry);
+        },
+        remove: (sessionId) => {
+            const session = sessions.get(sessionId);
+            sessions.delete(sessionId);
+            return session;
+        },
+        size: () => sessions.size,
+        inFlight: () => inflight,
+        incrementInFlight: () => {
+            inflight += 1;
+        },
+        decrementInFlight: () => {
+            if (inflight > 0)
+                inflight -= 1;
+        },
+        clear: () => {
+            const entries = [...sessions.values()];
+            sessions.clear();
+            return entries;
+        },
+        evictExpired: () => {
+            const now = Date.now();
+            const evicted = [];
+            for (const [id, session] of sessions.entries()) {
+                if (isSessionExpired(session, now, sessionTtlMs)) {
+                    sessions.delete(id);
+                    evicted.push(session);
+                }
+            }
+            return evicted;
+        },
+        evictOldest: () => {
+            const oldestEntry = sessions.keys().next();
+            if (oldestEntry.done)
+                return undefined;
+            const oldestId = oldestEntry.value;
+            const session = sessions.get(oldestId);
+            sessions.delete(oldestId);
+            return session;
+        },
+    };
+}
+// --- Slot Tracker ---
+export function createSlotTracker(store) {
+    let slotReleased = false;
+    let initialized = false;
+    return {
+        releaseSlot: () => {
+            if (slotReleased)
+                return;
+            slotReleased = true;
+            store.decrementInFlight();
+        },
+        markInitialized: () => {
+            initialized = true;
+        },
+        isInitialized: () => initialized,
+    };
+}
+export function reserveSessionSlot(store, maxSessions) {
+    if (store.size() + store.inFlight() >= maxSessions) {
+        return false;
+    }
+    store.incrementInFlight();
+    return true;
+}
+export function ensureSessionCapacity({ store, maxSessions, evictOldest, }) {
+    const currentSize = store.size();
+    const isAtCapacity = currentSize + store.inFlight() >= maxSessions;
+    if (!isAtCapacity)
+        return true;
+    // Try to free a slot
+    const canFreeSlot = currentSize >= maxSessions &&
+        currentSize - 1 + store.inFlight() < maxSessions;
+    if (canFreeSlot && evictOldest(store)) {
+        return store.size() + store.inFlight() < maxSessions;
+    }
+    return false;
+}

package/dist/tools.d.ts

@@ -125,4 +125,3 @@ export declare function fetchUrlToolHandler(input: FetchUrlInput, extra?: ToolHa
 export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
 export declare function registerTools(server: McpServer): void;
 export {};
-//# sourceMappingURL=tools.d.ts.map