@enokdev/springdocs-mcp 1.2.8 → 1.4.1

package/build/services/springboot-docs-optimized.js

@@ -1,8 +1,15 @@
-import fetch from 'node-fetch';
 import * as cheerio from 'cheerio';
-import TurndownService from 'turndown';
 import { CacheService } from './cache.js';
+import { fetchWithRetry } from './http.js';
+import { turndownService, extractContent, pageMarkdown } from './markdown.js';
+import { absoluteSpringUrl, assertSafeSegment, normalizeVersion } from './url.js';
+import { fetchSpringGuidesList } from './guides-list.js';
+import { resolveWikiDocument, wikiPageName, wikiPageUrl, expectedWikiTitle, extractWikiMarkdown, selectSections } from './boot-wiki.js';
 import { springProjectsConfig } from './spring-projects-config.js';
+import { SearchIndex } from './search-index.js';
+import { assertRawMarkdown, isMigrationProject, projectDisplayName, rawWikiTitle, rawWikiUrl, resolveRawDocument } from './migration-sources.js';
+/** Below this size an extracted guide is considered empty (a real guide is far longer; the smallest fixture is ~190). */
+const MIN_GUIDE_CHARS = 100;
 /**
  * Spring Documentation Service - Supports multiple Spring projects (Boot, AI, Framework, etc.)
  * Uses ONLY real Spring documentation APIs - no mock data
@@ -14,78 +21,26 @@ export class SpringBootDocsServiceOptimized {
     springProjectsUrl = 'https://spring.io/projects';
     springGuideUrl = 'https://spring.io/guides';
     projectsConfig;
-    turndownService;
     cache;
-    REQUEST_TIMEOUT = 10000;
-    MAX_RETRIES = 3;
-    constructor(projectsConfig = springProjectsConfig) {
+    searchIndex;
+    constructor(projectsConfig = springProjectsConfig, cache = new CacheService(), searchIndex = new SearchIndex()) {
         this.projectsConfig = projectsConfig;
-        this.turndownService = new TurndownService({
-            headingStyle: 'atx',
-            codeBlockStyle: 'fenced',
-        });
-        this.cache = new CacheService();
-        // Cleanup cache every hour
-        setInterval(() => this.cache.cleanup(), 60 * 60 * 1000);
+        this.cache = cache;
+        this.searchIndex = searchIndex;
     }
-    /**
-     * Extract content intelligently based on detail level
-     * Preserves code blocks, key sections, and structure
-     */
-    extractIntelligentContent(markdown, detailLevel = 'medium') {
-        const limits = {
-            'summary': 1500,
-            'medium': 4000,
-            'full': 8000
-        };
-        const maxLength = limits[detailLevel] || limits['medium'];
-        // If content is smaller than limit, return as-is
-        if (markdown.length <= maxLength) {
-            return markdown;
-        }
-        // Extract important sections
-        const lines = markdown.split('\n');
-        let result = '';
-        let inCodeBlock = false;
-        let codeBlockContent = '';
-        let currentLength = 0;
-        for (const line of lines) {
-            // Track code blocks
-            if (line.trim().startsWith('```')) {
-                inCodeBlock = !inCodeBlock;
-                if (!inCodeBlock && codeBlockContent) {
-                    // Keep complete code blocks
-                    const blockToAdd = codeBlockContent + line + '\n';
-                    if (currentLength + blockToAdd.length <= maxLength * 0.8) { // Reserve 20% for text
-                        result += blockToAdd;
-                        currentLength += blockToAdd.length;
-                    }
-                    codeBlockContent = '';
-                }
-                else {
-                    codeBlockContent = line + '\n';
-                }
-                continue;
-            }
-            if (inCodeBlock) {
-                codeBlockContent += line + '\n';
-                continue;
-            }
-            // Keep headers, important lines
-            if (line.startsWith('#') || line.startsWith('-') || line.startsWith('*') || line.trim().startsWith('>')) {
-                if (currentLength + line.length + 1 <= maxLength) {
-                    result += line + '\n';
-                    currentLength += line.length + 1;
-                }
-            }
-            else if (line.trim() && currentLength + line.length + 1 <= maxLength) {
-                result += line + '\n';
-                currentLength += line.length + 1;
-            }
-            if (currentLength >= maxLength)
-                break;
+    /** Feeds the full-text index with a page already fetched; never breaks the read path. */
+    indexPage(docId, title, url, text) {
+        try {
+            this.searchIndex.add(docId, { title, url, text });
         }
-        return result.trim();
+        catch (error) {
+            console.error(`Content index failure for ${docId}:`, error instanceof Error ? error.message : error);
+        }
+    }
+    /** Re-feeds the index from the cache when a page was evicted or read before the index existed. */
+    reindexIfMissing(docId, title, url, text) {
+        if (!this.searchIndex.has(docId))
+            this.indexPage(docId, title, url, text);
     }
     /**
      * Search Spring projects with caching and retry logic - REAL API ONLY
@@ -111,14 +66,14 @@ export class SpringBootDocsServiceOptimized {
                 const $project = $(element);
                 const title = $project.find('h2, h3, .title, .project-title').first().text().trim();
                 const description = $project.find('p, .description, .summary').first().text().trim();
-                const link = $project.find('a').first().attr('href');
-                if (title && (title.toLowerCase().includes(query.toLowerCase()) ||
+                const url = absoluteSpringUrl($project.find('a').first().attr('href'));
+                if (url && title && (title.toLowerCase().includes(query.toLowerCase()) ||
                     description.toLowerCase().includes(query.toLowerCase()))) {
                     projects.push({
                         type: 'spring-project',
                         title: title,
                         description: description,
-                        url: link?.startsWith('http') ? link : `https://spring.io${link}`,
+                        url: url,
                     });
                 }
             });
@@ -128,22 +83,24 @@ export class SpringBootDocsServiceOptimized {
         }
         catch (error) {
             console.error('Error searching Spring projects:', error);
-            return [];
+            throw error;
         }
     }
     /**
-     * Get Spring project details - REAL API ONLY
+     * Get the full markdown of a Spring project page (cached) - REAL API ONLY
      */
-    async getSpringProject(projectName) {
+    async getProjectMarkdown(projectName) {
+        const slug = assertSafeSegment(projectName.toLowerCase().replace(/\s+/g, '-'), 'project name');
         const cacheKey = `project:${projectName}`;
         const cached = this.cache.get(cacheKey);
         if (cached) {
             console.error(`✅ Cache hit for project: ${projectName}`);
+            this.reindexIfMissing(`project:${slug}`, projectName, cached.url, cached.markdown);
             return cached;
         }
         console.error(`🔍 Fetching project: ${projectName}`);
         try {
-            const url = `${this.springProjectsUrl}/${projectName.toLowerCase().replace(/\s+/g, '-')}`;
+            const url = `${this.springProjectsUrl}/${slug}`;
             const response = await this.fetchWithRetry(url);
             if (!response.ok) {
                 throw new Error(`Project not found: ${projectName}`);
@@ -154,17 +111,25 @@ export class SpringBootDocsServiceOptimized {
             if (content.length === 0) {
                 throw new Error('No content found for project');
             }
-            const markdown = this.turndownService.turndown(content.html() || '');
-            const projectUrl = `${this.springProjectsUrl}/${projectName.toLowerCase().replace(/\s+/g, '-')}`;
-            const result = `# ${projectName}\n\n${markdown.substring(0, 1500)}...\n\nFor complete project info, visit: ${projectUrl}`;
-            this.cache.setLongTerm(cacheKey, result);
-            return result;
+            const markdown = turndownService.turndown(content.html() || '');
+            // Cache the full markdown so later pages need no new fetch
+            this.indexPage(`project:${slug}`, projectName, url, markdown);
+            const entry = { markdown, url };
+            this.cache.setLongTerm(cacheKey, entry);
+            return entry;
         }
         catch (error) {
             console.error(`Error fetching project ${projectName}:`, error);
             throw error;
         }
     }
+    /**
+     * Get Spring project details - REAL API ONLY
+     */
+    async getSpringProject(projectName, offset = 0) {
+        const { markdown, url } = await this.getProjectMarkdown(projectName);
+        return this.formatPage(projectName, markdown, url, offset, 'For complete project info, visit');
+    }
     /**
      * Get all Spring guides - REAL API ONLY
      */
@@ -177,57 +142,45 @@ export class SpringBootDocsServiceOptimized {
         }
         console.error(`🔍 Fetching guides for category: ${category || 'all'}`);
         try {
-            const response = await this.fetchWithRetry(this.springGuideUrl);
-            if (!response.ok) {
-                throw new Error('Unable to access Spring guides page');
-            }
-            const html = await response.text();
-            const $ = cheerio.load(html);
-            const guides = [];
-            // Parse actual Spring guides page
-            $('.guide-item, .card, .guide-card, .list-item, .guide').each((_, element) => {
-                const $guide = $(element);
-                const title = $guide.find('h2, h3, .title, .guide-title, a').first().text().trim();
-                const description = $guide.find('p, .description, .summary').first().text().trim();
-                const guideCategory = $guide.find('.category, .badge, .label').first().text().trim();
-                const link = $guide.find('a').first().attr('href');
-                if (title) {
-                    if (!category || guideCategory.toLowerCase().includes(category.toLowerCase())) {
-                        guides.push({
-                            type: 'spring-guide',
-                            title: title,
-                            description: description || 'Spring guide',
-                            category: guideCategory || 'General',
-                            url: link?.startsWith('http') ? link : `https://spring.io${link}`,
-                        });
-                    }
-                }
-            });
+            const guides = await fetchSpringGuidesList(category);
             const results = guides.slice(0, limit);
             this.cache.set(cacheKey, results);
             return results;
         }
         catch (error) {
             console.error('Error retrieving Spring guides:', error);
-            return [];
+            throw error;
         }
     }
     /**
      * Get specific guide content - REAL API ONLY
      */
     async getGuide(guideId, detailLevel = 'medium') {
-        const cacheKey = `guide:${guideId}:${detailLevel}`;
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(guideId) || guideId.includes('..')) {
+            throw new Error(`Invalid guideId "${guideId}": only letters, digits, '.', '_' and '-' are allowed`);
+        }
+        // Getting-started guides live under /guides/gs/<name>/; accept the repository-style "gs-<name>" too
+        const name = guideId.replace(/^gs-/, '');
+        if (!name) {
+            throw new Error(`Invalid guideId "${guideId}": the guide name is empty`);
+        }
+        const safeId = encodeURIComponent(name);
+        const cacheKey = `guide:${name}:${detailLevel}`;
+        const rawKey = `guide-md:${name}`;
         const cached = this.cache.get(cacheKey);
         if (cached) {
             console.error(`✅ Cache hit for guide: ${guideId} (${detailLevel})`);
+            // The formatted text depends on detailLevel: the index is fed from the full markdown kept apart
+            const full = this.cache.get(rawKey);
+            if (full)
+                this.reindexIfMissing(`guide:${name}`, `Guide: ${name}`, full.url, full.markdown);
             return cached;
         }
         console.error(`🔍 Fetching guide: ${guideId} with detail level: ${detailLevel}`);
-        // Try multiple sources for guides
+        // Fallbacks tried in order: getting-started guide, then top-level guide path
         const sources = [
-            { name: 'Spring.io', url: `${this.springGuideUrl}/${guideId}/` },
-            { name: 'GitHub', url: `https://github.com/spring-guides/${guideId}` },
-            { name: 'Spring.io alt', url: `${this.springGuideUrl}/gs/${guideId}/` }
+            { name: 'Spring.io getting-started', url: `${this.springGuideUrl}/gs/${safeId}/` },
+            { name: 'Spring.io', url: `${this.springGuideUrl}/${safeId}/` }
         ];
         let content = '';
         let sourceUrl = '';
@@ -253,7 +206,11 @@ export class SpringBootDocsServiceOptimized {
             throw new Error(`Guide not found: ${guideId}`);
         }
         try {
-            const result = this.processHtmlGuide(content, guideId, sourceUrl, detailLevel);
+            const markdown = this.extractGuideMarkdown(content, sourceUrl);
+            const result = this.formatGuide(markdown, guideId, sourceUrl, detailLevel);
+            // Index the complete text, whatever the detail level of this read
+            this.indexPage(`guide:${name}`, `Guide: ${name}`, sourceUrl, markdown);
+            this.cache.setLongTerm(rawKey, { markdown, url: sourceUrl });
             this.cache.setLongTerm(cacheKey, result);
             return result;
         }
@@ -277,14 +234,22 @@ export class SpringBootDocsServiceOptimized {
      * @param projectId - Project identifier ('boot', 'ai', 'framework', etc.)
      * @param section - Documentation section (e.g., 'web', 'chatclient', 'core')
      * @param subsection - Optional subsection for deeper navigation
+     * @param offset - Character offset for paginated reads
+     * @param version - Optional documentation version ('3.4' or '3.4.2'; omitted/'current' = latest)
      * @returns Formatted markdown documentation with source URL
      */
-    async getSpringReference(projectId, section, subsection) {
-        const cacheKey = `reference:${projectId}:${section}:${subsection || 'main'}`;
+    async getSpringReference(projectId, section, subsection, offset = 0, version) {
+        const safeSection = assertSafeSegment(section, 'section');
+        const safeSubsection = subsection ? assertSafeSegment(subsection, 'subsection') : undefined;
+        // Validate the version before any cache or network access
+        const normalizedVersion = normalizeVersion(version);
+        const baseKey = `reference:${projectId}:${section}:${subsection || 'main'}`;
+        const cacheKey = normalizedVersion ? `${baseKey}:v${normalizedVersion}` : baseKey;
         const cached = this.cache.get(cacheKey);
         if (cached) {
             console.error(`✅ Cache hit for reference: ${projectId}/${section}`);
-            return cached;
+            this.reindexIfMissing(`reference:${projectId}:${normalizedVersion ?? 'current'}:${section}:${subsection ?? 'main'}`, this.referenceTitle(projectId, section, subsection), cached.url, cached.markdown);
+            return this.formatPage(this.referenceTitle(projectId, section, subsection), cached.markdown, cached.url, offset, 'For complete reference, visit');
         }
         console.error(`🔍 Fetching reference: ${projectId}/${section}`);
         try {
@@ -296,9 +261,12 @@ export class SpringBootDocsServiceOptimized {
                 throw new Error(`Invalid section "${section}" for ${project.displayName}. Available sections: ${availableSections}`);
             }
             // Build URL using configuration
-            const url = this.projectsConfig.buildReferenceUrl(projectId, section);
+            const url = this.projectsConfig.buildReferenceUrl(projectId, safeSection, safeSubsection, normalizedVersion);
             const response = await this.fetchWithRetry(url);
             if (!response.ok) {
+                if (normalizedVersion) {
+                    throw new Error(`Reference not found for ${project.displayName} version ${normalizedVersion} (this version may not be published at the current documentation site; omit 'version' for the latest or try a more recent one)`);
+                }
                 throw new Error(`Reference section not found: ${project.displayName} / ${section}`);
             }
             const html = await response.text();
@@ -308,42 +276,146 @@ export class SpringBootDocsServiceOptimized {
             if (content.length === 0) {
                 throw new Error(`No content found in ${project.displayName} reference documentation`);
             }
-            const markdown = this.turndownService.turndown(content.html() || '');
-            const result = `# ${project.displayName} Reference: ${section}\n\n${markdown.substring(0, 1500)}...\n\nFor complete reference, visit: ${url}`;
+            const markdown = turndownService.turndown(content.html() || '');
+            const entry = { markdown, url };
+            this.indexPage(`reference:${projectId}:${normalizedVersion ?? 'current'}:${section}:${subsection ?? 'main'}`, this.referenceTitle(projectId, section, subsection), url, markdown);
             // Use project-specific cache strategy
             const cacheTTL = this.projectsConfig.getCacheTTL(projectId);
             if (project.cacheStrategy === 'long') {
-                this.cache.setLongTerm(cacheKey, result);
+                this.cache.setLongTerm(cacheKey, entry);
             }
             else {
-                this.cache.set(cacheKey, result, cacheTTL);
+                this.cache.set(cacheKey, entry, cacheTTL);
             }
-            return result;
+            return this.formatPage(this.referenceTitle(projectId, section, subsection), markdown, url, offset, 'For complete reference, visit');
         }
         catch (error) {
             console.error(`Error fetching reference ${projectId}/${section}:`, error);
             throw error;
         }
     }
+    /**
+     * Get the Spring Boot migration guide or upgrade release notes from the GitHub wiki
+     *
+     * @param version - Target version ('3.0', '3.4' or '3.4.2'; the patch is ignored)
+     * @param document - 'auto' (migration guide for x.0, release notes otherwise) or an explicit document
+     * @param section - Optional keyword; only matching headings (with sub-sections) are returned
+     * @param offset - Character offset for paginated reads
+     */
+    async getMigrationGuide(version, document = 'auto', section, offset = 0, project = 'spring-boot') {
+        if (!isMigrationProject(project)) {
+            throw new Error(`Unknown project "${project}" for migration guides`);
+        }
+        // Resolve version and document before any cache or network access
+        const normalizedVersion = normalizeVersion(version);
+        if (!normalizedVersion) {
+            throw new Error(`A target ${projectDisplayName(project)} version is required (e.g. "3.0", "3.4" or "4.0")`);
+        }
+        const resolved = project === 'spring-boot'
+            ? resolveWikiDocument(normalizedVersion, document)
+            : resolveRawDocument(project, document);
+        const keyword = section?.trim() || undefined;
+        const cacheKey = project === 'spring-boot'
+            ? `migration:${resolved}:${normalizedVersion}`
+            : `migration:${project}:${resolved}:${normalizedVersion}`;
+        let entry = this.cache.get(cacheKey);
+        if (entry) {
+            console.error(`✅ Cache hit for migration page: ${cacheKey}`);
+            this.reindexIfMissing(cacheKey, entry.title, entry.url, entry.markdown);
+        }
+        else {
+            entry = project === 'spring-boot'
+                ? await this.fetchBootWikiPage(normalizedVersion, resolved)
+                : await this.fetchRawWikiPage(project, normalizedVersion);
+            // Only successful, verified pages are cached and indexed (whole page, not just the requested section)
+            this.indexPage(cacheKey, entry.title, entry.url, entry.markdown);
+            this.cache.setLongTerm(cacheKey, entry);
+        }
+        const markdown = keyword ? selectSections(entry.markdown, keyword, entry.title) : entry.markdown;
+        const title = keyword ? `${entry.title} (section: ${keyword})` : entry.title;
+        return this.formatPage(title, markdown, entry.url, offset, 'For the complete page, visit', Boolean(keyword));
+    }
+    async fetchBootWikiPage(version, document) {
+        const url = wikiPageUrl(wikiPageName(version, document));
+        console.error(`🔍 Fetching migration page: ${url}`);
+        const response = await this.fetchWithRetry(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch Spring Boot wiki page: ${response.status}`);
+        }
+        const html = await response.text();
+        const { markdown, title } = extractWikiMarkdown(html, expectedWikiTitle(version, document), url);
+        return { markdown, url, title };
+    }
+    /** Raw markdown wiki page (Framework, Batch): a missing page is a real 404, an HTML body is never a guide. */
+    async fetchRawWikiPage(project, version) {
+        const url = rawWikiUrl(project, version);
+        const title = rawWikiTitle(project, version);
+        console.error(`🔍 Fetching migration page: ${url}`);
+        const response = await this.fetchWithRetry(url);
+        if (response.status === 404) {
+            throw new Error(`Wiki page not found: ${title} (${url})`);
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to fetch ${title}: ${response.status}`);
+        }
+        const markdown = assertRawMarkdown(await response.text(), title, url);
+        return { markdown, url, title };
+    }
+    referenceTitle(projectId, section, subsection) {
+        const project = this.projectsConfig.getProject(projectId);
+        return `${project.displayName} Reference: ${subsection ? `${section}/${subsection}` : section}`;
+    }
+    /**
+     * Format one page of a full markdown document with a pagination footer
+     */
+    formatPage(title, markdown, url, offset, linkLabel, filtered = false) {
+        const page = pageMarkdown(markdown, offset);
+        if (offset >= page.total) {
+            return `No content at offset ${offset} (total: ${page.total} characters).`;
+        }
+        let result = `# ${title}\n\n${page.content}`;
+        if (page.nextOffset !== null) {
+            const note = filtered ? ' The offset applies to the filtered text (the selected section), not to the full page.' : '';
+            result += `\n\n---\nPart ${page.start}–${page.end} of ${page.total} characters. To continue, call again with offset=${page.nextOffset}.${note}`;
+        }
+        return `${result}\n\n${linkLabel}: ${url}`;
+    }
     /**
      * Search Spring concepts - alias for backward compatibility
      */
-    async searchConcepts(concept, category) {
-        return this.searchSpringConcepts(concept, category);
+    async searchConcepts(concept, version) {
+        return this.searchSpringConcepts(concept, version);
+    }
+    /**
+     * Entry page of the Spring Boot reference documentation: the current docs (legacy URL, unchanged)
+     * or the page of a published version ("3.4" or "3.4.2"; the patch is ignored).
+     */
+    bootReferenceIndexUrl(normalizedVersion) {
+        return normalizedVersion
+            ? `${this.baseUrl}/spring-boot/${normalizedVersion}/reference/index.html`
+            : `${this.baseUrl}/spring-boot/docs/current/reference/html/`;
+    }
+    bootVersionNotFound(normalizedVersion) {
+        return new Error(`Spring Boot documentation for version ${normalizedVersion} not found (this version may not be published at the current documentation site; omit 'version' for the latest or try a more recent one)`);
     }
     /**
      * Search Spring concepts - using real documentation
+     *
+     * @param version - Optional Spring Boot documentation version ('3.4' or '3.4.2'; omitted/'current' = latest)
      */
-    async searchSpringConcepts(concept, category) {
-        const cacheKey = `concepts:${concept}:${category || 'all'}`;
+    async searchSpringConcepts(concept, version) {
+        const normalizedVersion = normalizeVersion(version);
+        const cacheKey = normalizedVersion ? `concepts:${concept}:v${normalizedVersion}` : `concepts:${concept}`;
         const cached = this.cache.get(cacheKey);
         if (cached)
             return cached;
         try {
             // Search in Spring Boot reference documentation
-            const searchUrl = `${this.baseUrl}/spring-boot/docs/current/reference/html/`;
+            const searchUrl = this.bootReferenceIndexUrl(normalizedVersion);
             const response = await this.fetchWithRetry(searchUrl);
             if (!response.ok) {
+                if (normalizedVersion)
+                    throw this.bootVersionNotFound(normalizedVersion);
                 throw new Error('Unable to access Spring Boot documentation');
             }
             const html = await response.text();
@@ -359,7 +431,7 @@ export class SpringBootDocsServiceOptimized {
                 const headingText = heading.text().toLowerCase();
                 if (headingText.includes(concept.toLowerCase())) {
                     const section = heading.parent();
-                    const sectionMarkdown = this.turndownService.turndown(section.html() || '');
+                    const sectionMarkdown = turndownService.turndown(section.html() || '');
                     conceptContent += sectionMarkdown.substring(0, 500) + '\n\n';
                     foundSections++;
                 }
@@ -375,53 +447,110 @@ export class SpringBootDocsServiceOptimized {
         }
         catch (error) {
             console.error('Error searching concepts:', error);
-            return `# Spring Concept Search Error\n\nUnable to search for concept "${concept}": ${error instanceof Error ? error.message : 'Unknown error'}`;
+            throw error;
         }
     }
     /**
      * Search documentation with real API - alias for backward compatibility
      */
-    async searchDocumentation(query, docType = 'all', limit = 10) {
-        return this.searchSpringDocs(query, docType, limit);
+    async searchDocumentation(query, docType = 'all', limit = 10, version) {
+        return this.searchSpringDocs(query, docType, limit, version);
     }
     /**
      * Search documentation with real API
+     *
+     * @param version - Optional Spring Boot documentation version for the Boot reference part
+     *   ('3.4' or '3.4.2'; omitted/'current' = latest). Guides and projects are not versioned and ignore it.
      */
-    async searchSpringDocs(query, docType = 'all', limit = 10) {
-        const cacheKey = `docs:${query}:${docType}:${limit}`;
-        const cached = this.cache.get(cacheKey);
-        if (cached)
-            return cached;
-        const results = [];
+    async searchSpringDocs(query, docType = 'all', limit = 10, version) {
+        const allowedDocTypes = ['guides', 'reference', 'projects', 'content', 'all'];
+        if (!allowedDocTypes.includes(docType)) {
+            throw new Error(`Invalid docType "${docType}". Allowed: ${allowedDocTypes.join(', ')}`);
+        }
+        const normalizedVersion = normalizeVersion(version);
+        const baseKey = `docs:${query}:${docType}:${limit}`;
+        const cacheKey = normalizedVersion ? `${baseKey}:v${normalizedVersion}` : baseKey;
+        // Only the title sources are cached: content hits depend on the current state of the index
+        const titles = this.cache.get(cacheKey) ?? await this.searchTitleSources(query, docType, limit, cacheKey, normalizedVersion);
+        if (docType !== 'all' && docType !== 'content') {
+            return titles.slice(0, limit);
+        }
+        return this.mergeContentResults(titles, query, limit, normalizedVersion);
+    }
+    mergeContentResults(titles, query, limit, normalizedVersion) {
+        const seen = new Set(titles.map(result => result.url));
+        let content = [];
         try {
-            if (docType === 'all' || docType === 'guides') {
-                const guides = await this.getAllSpringGuides(undefined, limit);
-                const filteredGuides = guides.filter(guide => guide.title.toLowerCase().includes(query.toLowerCase()) ||
-                    guide.description.toLowerCase().includes(query.toLowerCase()));
-                results.push(...filteredGuides);
-            }
-            if (docType === 'all' || docType === 'projects') {
-                const projects = await this.searchSpringProjects(query, limit);
-                results.push(...projects);
+            // With a version, Boot reference pages of other versions are left out (each page is indexed
+            // under its own versioned docId); guides, projects and other projects' pages are not versioned
+            const sameVersion = (docId) => !normalizedVersion || !docId.startsWith('reference:boot:') || docId.startsWith(`reference:boot:${normalizedVersion}:`);
+            content = this.searchIndex.search(query, limit, sameVersion)
+                .filter(hit => !seen.has(hit.url))
+                .map(hit => ({ type: 'content', title: hit.title, url: hit.url, description: hit.snippet, score: hit.score }));
+        }
+        catch (error) {
+            console.error('Content search failed:', error instanceof Error ? error.message : error);
+        }
+        // Content takes the slots titles leave free, and at most half of them otherwise
+        const contentSlots = Math.min(content.length, Math.max(Math.floor(limit / 2), limit - titles.length));
+        const merged = [...titles.slice(0, limit - contentSlots), ...content.slice(0, contentSlots)];
+        if (this.searchIndex.size === 0) {
+            merged.push({
+                type: 'note',
+                title: 'Content index is empty',
+                description: 'Full-text search covers pages already read: read a page first (get_spring_project, get_spring_reference or get_spring_guide), then search again.'
+            });
+        }
+        return merged;
+    }
+    async searchTitleSources(query, docType, limit, cacheKey, normalizedVersion) {
+        const results = [];
+        const sources = [];
+        if (docType === 'all' || docType === 'guides') {
+            sources.push(['guides', async () => {
+                    const guides = await this.getAllSpringGuides(undefined, Number.MAX_SAFE_INTEGER);
+                    return guides.filter(guide => guide.title.toLowerCase().includes(query.toLowerCase()) ||
+                        guide.description.toLowerCase().includes(query.toLowerCase())).slice(0, limit);
+                }]);
+        }
+        if (docType === 'all' || docType === 'projects') {
+            sources.push(['projects', () => this.searchSpringProjects(query, limit)]);
+        }
+        if (docType === 'all' || docType === 'reference') {
+            sources.push(['reference', () => this.searchInReference(query, limit, normalizedVersion)]);
+        }
+        // A failing source must not be hidden nor cached: fail if all fail, otherwise return partial results uncached
+        const failures = [];
+        const settled = await Promise.allSettled(sources.map(([, run]) => run()));
+        settled.forEach((outcome, index) => {
+            if (outcome.status === 'fulfilled') {
+                results.push(...outcome.value);
             }
-            if (docType === 'all' || docType === 'reference') {
-                // Search in reference documentation
-                const refResults = await this.searchInReference(query, limit);
-                results.push(...refResults);
+            else {
+                failures.push(sources[index][0]);
+                console.error(`Documentation source "${sources[index][0]}" failed:`, outcome.reason instanceof Error ? outcome.reason.message : outcome.reason);
             }
-            this.cache.set(cacheKey, results);
-            return results.slice(0, limit);
+        });
+        if (sources.length > 0 && failures.length === sources.length) {
+            const reasons = settled
+                .map(outcome => (outcome.status === 'rejected' ? (outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)) : ''))
+                .filter(Boolean);
+            throw new Error(`Unable to search documentation: all sources failed (${failures.join(', ')}): ${reasons.join('; ')}`);
         }
-        catch (error) {
-            console.error('Error searching documentation:', error);
-            return [];
+        if (failures.length === 0) {
+            this.cache.set(cacheKey, results);
         }
+        return results.slice(0, limit);
     }
-    async searchInReference(query, limit) {
+    async searchInReference(query, limit, normalizedVersion) {
         try {
-            const response = await this.fetchWithRetry(`${this.baseUrl}/spring-boot/docs/current/reference/html/`);
-            if (!response.ok)
-                return [];
+            const pageUrl = this.bootReferenceIndexUrl(normalizedVersion);
+            const response = await this.fetchWithRetry(pageUrl);
+            if (!response.ok) {
+                if (normalizedVersion)
+                    throw this.bootVersionNotFound(normalizedVersion);
+                throw new Error('Unable to access Spring Boot reference documentation');
+            }
             const html = await response.text();
             const $ = cheerio.load(html);
             const results = [];
@@ -433,7 +562,9 @@ export class SpringBootDocsServiceOptimized {
                     results.push({
                         type: 'reference',
                         title: `Spring Boot: ${text}`,
-                        url: href.startsWith('http') ? href : `${this.baseUrl}/spring-boot/docs/current/reference/html/${href}`,
+                        url: normalizedVersion
+                            ? new URL(href, pageUrl).href // nav hrefs of the versioned site are relative to the page
+                            : href.startsWith('http') ? href : `${this.baseUrl}/spring-boot/docs/current/reference/html/${href}`,
                         description: `Reference documentation section`
                     });
                 }
@@ -442,55 +573,42 @@ export class SpringBootDocsServiceOptimized {
         }
         catch (error) {
             console.error('Error searching reference:', error);
-            return [];
+            throw error;
         }
     }
-    processHtmlGuide(content, guideId, sourceUrl, detailLevel = 'medium') {
-        console.log(`Processing HTML content with detail level: ${detailLevel}...`);
+    extractGuideMarkdown(content, sourceUrl) {
+        console.error('Processing HTML guide content...');
         const $ = cheerio.load(content);
         // Remove navigation and footer elements
         $('nav, footer, .navbar, .sidebar, #js-sidebar').remove();
         // Get main content
-        const mainContent = $('.content, .guide-content, main, .markdown-body, .guide-body, article').first();
+        // Selectors are tried in priority order: a single comma list would pick the first match in
+        // document order (on spring.io an unrelated <article> card comes before the guide body)
+        const selectors = ['.ascii-doc', '.content', '.guide-content', 'main', '.markdown-body', '.guide-body', 'article'];
+        const mainContent = selectors.map(selector => $(selector).first()).find(match => match.length > 0) ?? $();
         let markdown;
         if (mainContent.length === 0) {
-            console.log('No main content found, using body');
+            console.error('No main content found, using body');
             $('script, style').remove();
-            markdown = this.turndownService.turndown($('body').html() || '');
+            markdown = turndownService.turndown($('body').html() || '');
         }
         else {
-            markdown = this.turndownService.turndown(mainContent.html() || '');
+            markdown = turndownService.turndown(mainContent.html() || '');
+        }
+        const trimmed = markdown.trim();
+        // A near-empty page or a JSON excerpt (client-rendered page data) is not a guide
+        if (trimmed.length < MIN_GUIDE_CHARS || /^[{[]\s*"/.test(trimmed)) {
+            throw new Error(`No content could be extracted from the guide page: ${sourceUrl}`);
         }
+        return markdown;
+    }
+    formatGuide(markdown, guideId, sourceUrl, detailLevel) {
         // Use intelligent extraction
-        const extractedContent = this.extractIntelligentContent(markdown, detailLevel);
-        const needsTruncation = markdown.length > extractedContent.length;
-        return `# Spring Guide: ${guideId}\n\n**Source:** ${sourceUrl}\n**Detail Level:** ${detailLevel}\n\n${extractedContent}${needsTruncation ? '\n\n---\n*Content truncated for brevity. Use detail_level="full" for complete guide or visit the link above.*' : ''}`;
+        const { content: extractedContent, truncated } = extractContent(markdown, detailLevel);
+        return `# Spring Guide: ${guideId}\n\n**Source:** ${sourceUrl}\n**Detail Level:** ${detailLevel}\n\n${extractedContent}${truncated ? (detailLevel === 'full' ? '\n\n---\n*Content truncated at 50,000 characters even in full mode. Visit the link above for the complete guide.*' : '\n\n---\n*Content truncated for brevity. Use detail_level="full" for complete guide or visit the link above.*') : ''}`;
     }
-    async fetchWithRetry(url, timeout = this.REQUEST_TIMEOUT, retries = this.MAX_RETRIES) {
-        for (let attempt = 1; attempt <= retries; attempt++) {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), timeout);
-            try {
-                const response = await fetch(url, {
-                    signal: controller.signal,
-                    headers: {
-                        'User-Agent': 'Spring-Docs-MCP/1.2.4',
-                        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
-                        'Accept-Language': 'en-US,en;q=0.9'
-                    }
-                });
-                clearTimeout(timeoutId);
-                return response;
-            }
-            catch (error) {
-                clearTimeout(timeoutId);
-                if (attempt === retries)
-                    throw error;
-                console.error(`Retry ${attempt}/${retries} for ${url}:`, error instanceof Error ? error.message : 'Unknown error');
-                await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); // Exponential backoff
-            }
-        }
-        throw new Error('All retry attempts failed');
+    fetchWithRetry(url, timeout, retries) {
+        return fetchWithRetry(url, timeout, retries);
     }
 }
 //# sourceMappingURL=springboot-docs-optimized.js.map