@j0hanz/superfetch 2.5.2 → 2.6.0

package/dist/index.js

@@ -1,13 +1,59 @@
 #!/usr/bin/env node
+import process from 'node:process';
 import { parseArgs } from 'node:util';
+import { serverVersion } from './config.js';
 import { startHttpServer } from './http-native.js';
 import { startStdioServer } from './mcp.js';
 import { logError } from './observability.js';
-const { values } = parseArgs({
-    options: {
-        stdio: { type: 'boolean', default: false },
-    },
-});
+function printUsage() {
+    process.stdout.write([
+        'superfetch MCP server',
+        '',
+        'Usage:',
+        '  superfetch [--stdio] [--help] [--version]',
+        '',
+        'Options:',
+        '  --stdio    Run in stdio mode (no HTTP server).',
+        '  --help     Show this help message.',
+        '  --version  Show server version.',
+        '',
+    ].join('\n'));
+}
+const FORCE_EXIT_TIMEOUT_MS = 10_000;
+let forcedExitTimer;
+function scheduleForcedExit(reason) {
+    if (forcedExitTimer)
+        return;
+    forcedExitTimer = setTimeout(() => {
+        process.stderr.write(`${reason}; forcing exit.\n`);
+        process.exit(1);
+    }, FORCE_EXIT_TIMEOUT_MS);
+    forcedExitTimer.unref();
+}
+let values;
+try {
+    ({ values } = parseArgs({
+        options: {
+            stdio: { type: 'boolean', default: false },
+            help: { type: 'boolean', default: false },
+            version: { type: 'boolean', default: false },
+        },
+    }));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Invalid arguments: ${message}\n\n`);
+    printUsage();
+    process.exit(1);
+}
+if (values.help) {
+    printUsage();
+    process.exit(0);
+}
+if (values.version) {
+    process.stdout.write(`${serverVersion}\n`);
+    process.exit(0);
+}
 const isStdioMode = values.stdio;
 let isShuttingDown = false;
 const shutdownHandlerRef = {};
@@ -21,14 +67,26 @@ function attemptShutdown(signal) {
     process.stderr.write('Attempting graceful shutdown...\n');
     void shutdownHandlerRef.current(signal);
 }
+function registerHttpSignalHandlers() {
+    process.once('SIGINT', () => {
+        if (shouldAttemptShutdown())
+            attemptShutdown('SIGINT');
+    });
+    process.once('SIGTERM', () => {
+        if (shouldAttemptShutdown())
+            attemptShutdown('SIGTERM');
+    });
+}
 function handleFatalError(label, error, signal) {
     logError(label, error);
     process.stderr.write(`${label}: ${error.message}\n`);
+    process.exitCode = 1;
     if (shouldAttemptShutdown()) {
         attemptShutdown(signal);
+        scheduleForcedExit('Graceful shutdown timed out');
         return;
     }
-    process.exit(1);
+    scheduleForcedExit('Fatal error without shutdown handler');
 }
 process.on('uncaughtException', (error) => {
     handleFatalError('Uncaught exception', error, 'UNCAUGHT_EXCEPTION');
@@ -44,11 +102,13 @@ try {
     else {
         const { shutdown } = await startHttpServer();
         shutdownHandlerRef.current = shutdown;
+        registerHttpSignalHandlers();
     }
 }
 catch (error) {
     logError('Failed to start server', error instanceof Error ? error : undefined);
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(`Failed to start server: ${message}\n`);
-    process.exit(1);
+    process.exitCode = 1;
+    scheduleForcedExit('Startup failure');
 }

package/dist/instructions.md

@@ -1,44 +1,58 @@
-# superFetch Instructions
+# SUPERFETCH INSTRUCTIONS
 
-> **Guidance for the Agent:** These instructions are available as a resource (`internal://instructions`) or prompt (`get-help`). Load them when unsure about tool usage.
+Available as resource (internal://instructions) or prompt (get-help). Load when unsure about tool usage.
 
-## 1. Core Capability
+---
 
-- **Domain:** Fetch public web pages and convert HTML to clean, LLM-readable Markdown.
-- **Primary Resources:** Markdown content, cached snapshots (`superfetch://cache/...`).
-- **Tools:** `fetch-url` (**Read-only**; no write tools exist).
+## CORE CAPABILITY
 
-## 2. The "Golden Path" Workflows (Critical)
+- Domain: Fetch public web pages and convert HTML to clean, LLM-readable Markdown.
+- Primary Resources: Markdown content, cached snapshots (superfetch://cache/...).
+- Tools: fetch-url (READ-ONLY; no write tools exist).
 
-### Workflow A: Standard Fetch
+---
 
-1. Call `fetch-url` with `{ "url": "https://..." }`.
-2. Read the `markdown` field from `structuredContent`.
-3. **If truncated** (ends with `...[truncated]`): read the `resource_link` URI to get full content.
-   > Constraint: Never guess URIs; always use the one returned.
+## THE “GOLDEN PATH” WORKFLOWS (CRITICAL)
 
-### Workflow B: Async Execution (Large Sites / Timeouts)
+### WORKFLOW A: STANDARD FETCH
 
-1. Call `tools/call` with `task: { ttl: ... }` to start a background fetch.
-2. Poll `tasks/get` until `status` is `completed` or `failed`.
-3. Retrieve result via `tasks/result`.
+- Call fetch-url with: { "url": "https://..." }
+- Read the “markdown” field from “structuredContent”.
+- If truncated (ends with "...[truncated]"): read the "resource_link" URI to get full content.
+  NOTE: Never guess URIs; always use the one returned.
 
-## 3. Tool Nuances & Gotchas
+### WORKFLOW B: ASYNC EXECUTION (LARGE SITES / TIMEOUTS)
 
-- **`fetch-url`**
-  - **Purpose:** Fetch a URL and return Markdown.
-  - **Inputs:** `url` (required; 1–2048 chars; `https?://` only).
-  - **Side effects:** None (read-only, idempotent). Populates cache automatically.
-  - **Limits:** Inline content capped at 20,000 chars; larger content offloaded to `superfetch://cache/...`.
-  - **Blocked targets:** `localhost`, private IPs (`10.x`, `172.16–31.x`, `192.168.x`), cloud metadata endpoints.
+- Call tools/call with task: { ttl: ... } to start a background fetch.
+- Poll tasks/get until status is “completed” or “failed”.
+- Retrieve result via tasks/result.
 
-## 4. Error Handling Strategy
+---
 
-- **`VALIDATION_ERROR`:** URL invalid or blocked. **Do not retry.**
-- **`FETCH_ERROR`:** Network/upstream failure. **Retry once** with backoff.
-- **`queue_full`:** Worker pool busy. Wait briefly, then retry or use Task interface.
+## TOOL NUANCES & GOTCHAS
 
-## 5. Resources
+fetch-url
 
-- `internal://config` — Current server limits (secrets redacted).
-- `superfetch://cache/{key}` — Immutable cached snapshots. Re-fetch for fresh content.
+- Purpose: Fetch a URL and return Markdown.
+- Input: { "url": "https://..." }
+- Optional: skipNoiseRemoval (bool, keeps nav/footers), forceRefresh (bool, bypasses cache).
+- Side effects: None (read-only, idempotent). Populates cache automatically.
+- Limits: HTML capped at 10 MB (MAX_HTML_BYTES). Inline content unlimited by default; set MAX_INLINE_CONTENT_CHARS to cap.
+- Blocked: localhost, private IPs (10.x, 172.16–31.x, 192.168.x), cloud metadata endpoints.
+- Quality: Varies by HTML structure. Best with articles/docs. Always verify output.
+
+---
+
+## ERROR HANDLING STRATEGY
+
+- VALIDATION_ERROR: URL invalid or blocked. Do not retry.
+- FETCH_ERROR: Network/upstream failure. Retry once with backoff.
+- queue_full: Worker pool busy. Wait briefly, then retry or use Task interface.
+
+---
+
+## RESOURCES
+
+- internal://instructions — This document.
+- internal://config — Current server limits (secrets redacted).
+- superfetch://cache/{key} — Immutable cached snapshots. Re-fetch for fresh content.

package/dist/ip-blocklist.d.ts

@@ -0,0 +1,8 @@
+import { BlockList } from 'node:net';
+type IpFamily = 'ipv4' | 'ipv6';
+export declare function createDefaultBlockList(): BlockList;
+export declare function normalizeIpForBlockList(input: string): {
+    ip: string;
+    family: IpFamily;
+} | null;
+export {};

package/dist/ip-blocklist.js

@@ -0,0 +1,65 @@
+import { BlockList, isIP } from 'node:net';
+function buildIpv4(parts) {
+    return parts.join('.');
+}
+function buildIpv6(parts) {
+    return parts.map(String).join(':');
+}
+const IPV6_ZERO = buildIpv6([0, 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_LOOPBACK = buildIpv6([0, 0, 0, 0, 0, 0, 0, 1]);
+const IPV6_64_FF9B = buildIpv6(['64', 'ff9b', 0, 0, 0, 0, 0, 0]);
+const IPV6_64_FF9B_1 = buildIpv6(['64', 'ff9b', 1, 0, 0, 0, 0, 0]);
+const IPV6_2001 = buildIpv6(['2001', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_2002 = buildIpv6(['2002', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FC00 = buildIpv6(['fc00', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FE80 = buildIpv6(['fe80', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FF00 = buildIpv6(['ff00', 0, 0, 0, 0, 0, 0, 0]);
+const BLOCKED_SUBNETS = [
+    { subnet: buildIpv4([0, 0, 0, 0]), prefix: 8, family: 'ipv4' },
+    { subnet: buildIpv4([10, 0, 0, 0]), prefix: 8, family: 'ipv4' },
+    { subnet: buildIpv4([100, 64, 0, 0]), prefix: 10, family: 'ipv4' },
+    { subnet: buildIpv4([127, 0, 0, 0]), prefix: 8, family: 'ipv4' },
+    { subnet: buildIpv4([169, 254, 0, 0]), prefix: 16, family: 'ipv4' },
+    { subnet: buildIpv4([172, 16, 0, 0]), prefix: 12, family: 'ipv4' },
+    { subnet: buildIpv4([192, 168, 0, 0]), prefix: 16, family: 'ipv4' },
+    { subnet: buildIpv4([224, 0, 0, 0]), prefix: 4, family: 'ipv4' },
+    { subnet: buildIpv4([240, 0, 0, 0]), prefix: 4, family: 'ipv4' },
+    { subnet: IPV6_ZERO, prefix: 128, family: 'ipv6' },
+    { subnet: IPV6_LOOPBACK, prefix: 128, family: 'ipv6' },
+    { subnet: IPV6_64_FF9B, prefix: 96, family: 'ipv6' },
+    { subnet: IPV6_64_FF9B_1, prefix: 48, family: 'ipv6' },
+    { subnet: IPV6_2001, prefix: 32, family: 'ipv6' },
+    { subnet: IPV6_2002, prefix: 16, family: 'ipv6' },
+    { subnet: IPV6_FC00, prefix: 7, family: 'ipv6' },
+    { subnet: IPV6_FE80, prefix: 10, family: 'ipv6' },
+    { subnet: IPV6_FF00, prefix: 8, family: 'ipv6' },
+];
+export function createDefaultBlockList() {
+    const list = new BlockList();
+    for (const entry of BLOCKED_SUBNETS) {
+        list.addSubnet(entry.subnet, entry.prefix, entry.family);
+    }
+    return list;
+}
+function extractMappedIpv4(ip) {
+    const prefix = '::ffff:';
+    if (!ip.startsWith(prefix))
+        return null;
+    const mapped = ip.slice(prefix.length);
+    return isIP(mapped) === 4 ? mapped : null;
+}
+export function normalizeIpForBlockList(input) {
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const ipType = isIP(trimmed);
+    if (ipType === 4)
+        return { ip: trimmed, family: 'ipv4' };
+    if (ipType === 6) {
+        const mapped = extractMappedIpv4(trimmed);
+        if (mapped)
+            return { ip: mapped, family: 'ipv4' };
+        return { ip: trimmed, family: 'ipv6' };
+    }
+    return null;
+}

package/dist/json.js

@@ -7,21 +7,26 @@ function processValue(obj, depth, seen) {
     if (depth > MAX_DEPTH) {
         throw new Error(`stableStringify: Max depth (${MAX_DEPTH}) exceeded`);
     }
-    // Cycle detection
+    // Cycle detection (track active recursion stack only).
     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));
+    try {
+        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;
     }
-    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);
+    finally {
+        seen.delete(obj);
     }
-    return sortedObj;
 }
 export function stableStringify(obj, depth = 0, seen = new WeakSet()) {
     const processed = processValue(obj, depth, seen);

package/dist/language-detection.d.ts

@@ -1,12 +1,3 @@
-/**
- * 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 extractLanguageFromClassName(className: string): string | undefined;
 export declare function resolveLanguageFromAttributes(className: string, dataLang: string): string | undefined;
+export declare function detectLanguageFromCode(code: string): string | undefined;