@j0hanz/superfetch 2.2.0 → 2.2.2

package/dist/http-utils.d.ts

@@ -0,0 +1,61 @@
+import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+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 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 declare function normalizeHost(value: string): string | null;
+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 isJsonRpcBatchRequest(body: unknown): boolean;
+export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;
+export declare function acceptsEventStream(header: string | null | undefined): boolean;
+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;
+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;
+//# sourceMappingURL=http-utils.d.ts.map

package/dist/http-utils.d.ts.map

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

package/dist/http-utils.js

@@ -0,0 +1,252 @@
+import { isIP } from 'node:net';
+import { setInterval as setIntervalPromise } from 'node:timers/promises';
+import { z } from 'zod';
+import { config } from './config.js';
+import { logDebug, logInfo, logWarn } from './observability.js';
+// --- Host Normalization ---
+export function normalizeHost(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const first = takeFirstHostValue(trimmed);
+    if (!first)
+        return null;
+    const ipv6 = stripIpv6Brackets(first);
+    if (ipv6)
+        return stripTrailingDots(ipv6);
+    if (isIpV6Literal(first)) {
+        return stripTrailingDots(first);
+    }
+    return stripTrailingDots(stripPortIfPresent(first));
+}
+function takeFirstHostValue(value) {
+    const first = value.split(',')[0];
+    if (!first)
+        return null;
+    const trimmed = first.trim();
+    return trimmed ? trimmed : null;
+}
+function stripIpv6Brackets(value) {
+    if (!value.startsWith('['))
+        return null;
+    const end = value.indexOf(']');
+    if (end === -1)
+        return null;
+    return value.slice(1, end);
+}
+function stripPortIfPresent(value) {
+    const colonIndex = value.indexOf(':');
+    if (colonIndex === -1)
+        return value;
+    return value.slice(0, colonIndex);
+}
+function isIpV6Literal(value) {
+    return isIP(value) === 6;
+}
+function stripTrailingDots(value) {
+    let result = value;
+    while (result.endsWith('.')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+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',
+    });
+}
+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();
+                sessions.delete(sessionId); // Move to end (LRU behavior if needed, but Map insertion order)
+                sessions.set(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 (now - session.lastSeen > 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;
+        },
+    };
+}
+// --- 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'));
+}
+// --- 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;
+}
+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');
+        }
+    }
+}
+//# sourceMappingURL=http-utils.js.map

package/dist/http-utils.js.map

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

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
-import { startHttpServer } from './http.js';
+import { startHttpServer } from './http-native.js';
 import { startStdioServer } from './mcp.js';
 import { logError } from './observability.js';
 const { values } = parseArgs({

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE;QACP,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;KAC3C;CACF,CAAC,CAAC;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;AACjC,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B,MAAM,kBAAkB,GAAoD,EAAE,CAAC;AAE/E,SAAS,qBAAqB;IAC5B,OAAO,CAAC,cAAc,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,CAAC,kBAAkB,CAAC,OAAO;QAAE,OAAO;IACxC,cAAc,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC1D,KAAK,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,KAAY,EAAE,MAAc;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IAErD,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC5B,eAAe,CAAC,MAAM,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE;IACxC,gBAAgB,CAAC,oBAAoB,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC;AACtE,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;IAC1C,MAAM,KAAK,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,gBAAgB,CAAC,qBAAqB,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC;AACxE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,gBAAgB,EAAE,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,eAAe,EAAE,CAAC;QAC7C,kBAAkB,CAAC,OAAO,GAAG,QAAQ,CAAC;IACxC,CAAC;AACH,CAAC;AAAC,OAAO,KAAc,EAAE,CAAC;IACxB,QAAQ,CACN,wBAAwB,EACxB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE;QACP,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;KAC3C;CACF,CAAC,CAAC;AACH,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;AACjC,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B,MAAM,kBAAkB,GAAoD,EAAE,CAAC;AAE/E,SAAS,qBAAqB;IAC5B,OAAO,CAAC,cAAc,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,CAAC,kBAAkB,CAAC,OAAO;QAAE,OAAO;IACxC,cAAc,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC1D,KAAK,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,KAAY,EAAE,MAAc;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IAErD,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC5B,eAAe,CAAC,MAAM,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE;IACxC,gBAAgB,CAAC,oBAAoB,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC;AACtE,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;IAC1C,MAAM,KAAK,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,gBAAgB,CAAC,qBAAqB,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC;AACxE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,gBAAgB,EAAE,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,eAAe,EAAE,CAAC;QAC7C,kBAAkB,CAAC,OAAO,GAAG,QAAQ,CAAC;IACxC,CAAC;AACH,CAAC;AAAC,OAAO,KAAc,EAAE,CAAC;IACxB,QAAQ,CACN,wBAAwB,EACxB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC3C,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/instructions.md

@@ -1,39 +1,41 @@
-# superFetch Instructions
-
-> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`). Load them when you are confused about tool usage.
-
-## 1. Core Capability
-
-- **Domain:** Fetch public http(s) URLs, extract readable content, and return clean Markdown.
-- **Primary Resources:** `fetch-url` output (`markdown`, `title`, `url`) and cache resources (`superfetch://cache/markdown/{urlHash}`).
-
-## 2. The "Golden Path" Workflows (Critical)
-
-### Workflow A: Fetch and Read
-
-1. Call `fetch-url` with a public http(s) URL.
-2. Read `structuredContent.markdown` and `structuredContent.title`.
-3. Cite using `resolvedUrl` or `url` from the response.
-
-### Workflow B: Large Content / Cache Resource
-
-1. If the response includes a `resource_link`, read that resource URI.
-2. If content is missing, list resources and select the matching `superfetch://cache/markdown/{urlHash}` entry.
-   > **Constraint:** Never guess resource URIs. Use the returned `resource_link` or list resources first.
-
-## 3. Tool Nuances & "Gotchas"
-
-- **`fetch-url`**:
-  - **Latency:** Network-bound; expect slower responses for large pages.
-  - **Side Effects:** Calls external websites (open-world).
-  - **Input:** `url` must be public http/https. Private/internal addresses are blocked.
-  - **Output:** Large content may return a `resource_link` instead of full inline markdown.
-- **Cache resources (`superfetch://cache/markdown/{urlHash}`)**:
-  - **Namespace:** Only `markdown` is valid.
-  - **Discovery:** Use resource listing or the `resource_link` returned by `fetch-url`.
-
-## 4. Error Handling Strategy
-
-- **`VALIDATION_ERROR`**: URL is invalid or blocked. Confirm it is a public http(s) URL.
-- **`FETCH_ERROR`**: Network/HTTP failure. Retry or verify the site is reachable.
-- **Cache miss (`Content not found`)**: Re-run `fetch-url` or verify the cache entry exists.
+# superFetch Instructions
+
+> Guidance for the Agent: These instructions are available as a resource (`internal://instructions`) or prompt (`get-help`). Load them when you are unsure about tool usage.
+
+## 1. Core Capability
+
+- **Domain:** Fetch public http(s) URLs, extract readable content, and return clean Markdown.
+- **Primary Resources:** `fetch-url` output (`markdown`, `title`, `url`) and cache resources (`superfetch://cache/markdown/{urlHash}`).
+
+## 2. The "Golden Path" Workflows (Critical)
+
+_Describe the standard order of operations using ONLY tools that exist._
+
+### Workflow A: Fetch and Read
+
+1. Call `fetch-url` with `url`.
+2. Read `structuredContent.markdown` and `structuredContent.title` from the result.
+3. If content is truncated (look for `...[truncated]`), follow the returned `resource_link` URI.
+   > Constraint: Never guess resource URIs. Use the returned `resource_link` or list resources first.
+
+### Workflow B: Retrieve Cached Content
+
+1. List resources to find available cached pages (`superfetch://cache/...`).
+2. Read the specific `superfetch://cache/markdown/{urlHash}` URI.
+
+## 3. Tool Nuances & Gotchas
+
+_Do NOT repeat JSON schema. Focus on behavior and pitfalls._
+
+- **`fetch-url`**
+  - **Purpose:** Fetches a webpage and converts it to clean Markdown format.
+  - **Inputs:** `url` (Must be public http/https. Private patterns like localhost/127.0.0.1 are blocked).
+  - **Side effects:** Open world network request; writes to internal LRU cache.
+  - **Latency/limits:** Network-bound. Large content exceeds inline limits and returns a `resource_link`.
+  - **Common failure modes:** `VALIDATION_ERROR` (private/blocked URL), `FETCH_ERROR` (network timeout/404).
+
+## 4. Error Handling Strategy
+
+- **`VALIDATION_ERROR`**: Ensure the URL is valid and publicly accessible.
+- **`FETCH_ERROR`**: Retry once. If persistent, the site may be blocking automated requests.
+- **Truncation**: If `isError` is false but content ends in `...[truncated]`, you MUST read the provided `resource_link` URI to get the full markdown.

package/dist/json.d.ts

@@ -0,0 +1,2 @@
+export declare function stableStringify(obj: unknown, depth?: number, seen?: WeakSet<object>): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAqCA,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,EACZ,KAAK,SAAI,EACT,IAAI,kBAAgB,GACnB,MAAM,CAGR"}

package/dist/json.js

@@ -0,0 +1,30 @@
+const MAX_DEPTH = 20;
+function processValue(obj, depth, seen) {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    // Depth guard
+    if (depth > MAX_DEPTH) {
+        throw new Error(`stableStringify: Max depth (${MAX_DEPTH}) exceeded`);
+    }
+    // Cycle detection
+    if (seen.has(obj)) {
+        throw new Error('stableStringify: Circular reference detected');
+    }
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+        return obj.map((item) => processValue(item, depth + 1, seen));
+    }
+    const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
+    const record = obj;
+    const sortedObj = {};
+    for (const key of keys) {
+        sortedObj[key] = processValue(record[key], depth + 1, seen);
+    }
+    return sortedObj;
+}
+export function stableStringify(obj, depth = 0, seen = new WeakSet()) {
+    const processed = processValue(obj, depth, seen);
+    return JSON.stringify(processed);
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,SAAS,YAAY,CACnB,GAAY,EACZ,KAAa,EACb,IAAqB;IAErB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAED,cAAc;IACd,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,YAAY,CAAC,CAAC;IACxE,CAAC;IAED,kBAAkB;IAClB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEd,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,SAAS,GAA4B,EAAE,CAAC;IAE9C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,SAAS,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,GAAY,EACZ,KAAK,GAAG,CAAC,EACT,IAAI,GAAG,IAAI,OAAO,EAAE;IAEpB,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;AACnC,CAAC"}

package/dist/language-detection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Language detection for code blocks.
+ * Detects programming languages from code content and HTML attributes.
+ */
+/**
+ * Detect programming language from code content using heuristics.
+ */
+export declare function detectLanguageFromCode(code: string): string | undefined;
+/**
+ * Resolve language from HTML attributes (class name and data-language).
+ */
+export declare function resolveLanguageFromAttributes(className: string, dataLang: string): string | undefined;
+//# sourceMappingURL=language-detection.d.ts.map

package/dist/language-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-detection.d.ts","sourceRoot":"","sources":["../src/language-detection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmSH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMvE;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAGpB"}