@wix/mcp 1.0.94 → 1.0.95

package/build/dts/docs/get-to-know.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import dedent from 'dedent';
-import { fetchArticleContent, RECIPES_INDEX_URL } from './fetch-article.js';
+import { fetchArticleContent, fetchSourceContent, RECIPES_INDEX_URL } from './fetch-article.js';
 import { getSkillsByPortal } from './fetch-skills.js';
 import { REST_PORTAL_ID } from '../constants.js';
 // import { generateDocsNavigationTree } from './normalize-menu-content.js';
@@ -8,8 +8,13 @@ import { rethrowIfUnauthorized } from '../auth/index.js';
 import { defaultToolDescriptions, defaultReadmeDocs } from '../config/default-config.js';
 import { getDynamicContext } from '@wix/dynamic-context-enricher';
 import { desc } from '../config/param-descriptions.js';
+import { isMintlifyDocsSite, rewriteDocsLinks } from './mintlify-docs.js';
 export { getDynamicContext };
-export function addGetSiteContextTool({ server, authStrategy, toolDescriptions }) {
+// The management index as authored in ax-skills, which also holds skills its
+// public mirror (and so the published article) leaves out.
+const AX_SKILLS_REPO = 'wix-private/ax-skills';
+const AX_SKILLS_INDEX_PATH = 'skills/wix-manage/SKILL.md';
+export function addGetSiteContextTool({ server, authStrategy, includeCompanionApp = false, toolDescriptions }) {
     const d = desc('GetSiteContext');
     server.tool('GetSiteContext', toolDescriptions?.['GetSiteContext'] ??
         defaultToolDescriptions.GetSiteContext, {
@@ -35,7 +40,8 @@ export function addGetSiteContextTool({ server, authStrategy, toolDescriptions }
         try {
             context = await getDynamicContext(authStrategy, httpClient, filter, {
                 partnerContextEnabled: false,
-                includeAccountContext: false
+                includeAccountContext: false,
+                includeCompanionApp
             });
         }
         catch (err) {
@@ -61,14 +67,19 @@ export function addGetSiteContextTool({ server, authStrategy, toolDescriptions }
         };
     });
 }
-export async function addGetToKnowTools({ server, disableTools = [], toolDescriptions, readmeDocs, authStrategy, skillsPortalUrl, dynamicContextEnabled, repo, commitHash, skillsTags }) {
+export async function addGetToKnowTools({ server, disableTools = [], toolDescriptions, readmeDocs, authStrategy, skillsPortalUrl, dynamicContextEnabled, repo, commitHash, skillsTags, readmeRecipesIndexEnabled = true, docsSite }) {
     if (disableTools.includes('WixREADME')) {
         return;
     }
     // Use provided docs or fall back to defaults. The Recipes block is appended
     // at the end so the hand-authored wix-usage-guide stays on top.
     const baseDocs = readmeDocs ?? defaultReadmeDocs;
-    const baseDocsWithoutRecipes = baseDocs.filter((doc) => doc.url !== RECIPES_INDEX_URL);
+    // The list's page and its .md form are the same document.
+    const isRecipesIndex = (doc) => doc.url?.replace(/\.md$/, '') === RECIPES_INDEX_URL;
+    const baseDocsWithoutRecipes = baseDocs.filter((doc) => !isRecipesIndex(doc));
+    const recipesIndexDocs = readmeRecipesIndexEnabled
+        ? baseDocs.filter(isRecipesIndex)
+        : [];
     server.tool('WixREADME', toolDescriptions?.['WixREADME'] ?? defaultToolDescriptions.WixREADME, {}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args, { httpClient }) => {
         // The schema is intentionally argless so the LLM always calls WixREADME
         // account-wide. A specific site can still be targeted programmatically
@@ -130,6 +141,15 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
                 if (!url) {
                     throw new Error('URL is required for "include" action');
                 }
+                const readsAxSkills = isRecipesIndex({ action, url }) &&
+                    !skillsPortalUrl &&
+                    (repo ? repo === AX_SKILLS_REPO : !commitHash);
+                if (readsAxSkills) {
+                    return {
+                        type: 'text',
+                        text: await fetchSourceContent(httpClient, AX_SKILLS_REPO, AX_SKILLS_INDEX_PATH, repo === AX_SKILLS_REPO ? commitHash : undefined)
+                    };
+                }
                 const fetchedContent = await fetchArticleContent(httpClient, url, 'article', true, skillsPortalUrl, repo, commitHash);
                 return {
                     type: 'text',
@@ -169,9 +189,6 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
         //     return '';
         //   });
         const baseContentsPromise = Promise.all(baseDocsWithoutRecipes.map(fetchDoc));
-        // Filtered lists still come from the portal. The full management index is
-        // authored alongside the recipes and is fetched like any other article,
-        // using its commit version when a PR override is configured.
         const skillsContentPromise = skillsTags?.length
             ? getSkillsByPortal(httpClient, {
                 portalId: REST_PORTAL_ID,
@@ -182,7 +199,9 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
                 console.error('[WixREADME] Failed to fetch skills by portal:', err);
                 return null;
             })
-            : fetchDoc({ action: 'include', url: RECIPES_INDEX_URL }).then((doc) => doc?.text ?? null);
+            : readmeRecipesIndexEnabled
+                ? fetchDoc({ action: 'include', url: RECIPES_INDEX_URL }).then((doc) => doc?.text ?? null)
+                : Promise.resolve(null);
         // Auto-inject site context. With no site targeted this is the account-wide
         // view: single-site accounts "just work", and accounts with more than the
         // cap show the first N sites plus a note to use GetSiteContext for the rest.
@@ -207,7 +226,7 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
         const recipesIntro = dedent `
           Reusable how-to guides for common ${isVisitorFlow ? 'Wix site visitor' : 'Wix management'} tasks, grouped by product area. Each recipe is a Wix docs article that bundles the right endpoints, request shapes, field names, and step ordering for one real-world use case.
 
-          Scan the index below and open any relevant article with \`ReadFullDocsArticle\`. If the article contains a code example that fits the user's intent — a **complete** example (not a truncated \`... N more lines ...\` snippet) that matches your exact case, same variant/shape — call the API directly. If the closest example is truncated or omits a field your case needs, do NOT call the API off it — continue discovery first: \`ReadFullDocsArticle\` for the complete example, or \`SearchWixAPISpec\` for the exact schema. On query and search methods an example proves only the fields and operators it uses; the endpoint's own declared list covers the rest. Otherwise (no fitting recipe, no usable code example, or persistent errors after retrying), fall back to docs discovery: \`SearchWixRESTDocumentation\` or \`BrowseWixRESTDocsMenu\` to find the right method, then \`SearchWixAPISpec\` for the exact schema.
+          Open the recipe that matches the task with \`ReadFullDocsArticle\` and follow it. When its example for a call matches your case (the same variant and shape), call from it; when it doesn't, or leaves out a field your case needs, read the method's schema with \`SearchWixAPISpec\` first. On query and search methods an example proves only the fields and operators it uses; the method's own declared list covers the rest. When no recipe fits, find the method with \`SearchWixRESTDocumentation\` or \`BrowseWixRESTDocsMenu\`, then \`SearchWixAPISpec\` for its schema.
         `;
         const recipesContents = skillsContent !== null
             ? [
@@ -217,9 +236,7 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
                     content: `${recipesIntro}\n\n${skillsContent}`
                 })
             ]
-            : await Promise.all(baseDocs
-                .filter((doc) => doc.url === RECIPES_INDEX_URL)
-                .map(fetchDoc));
+            : await Promise.all(recipesIndexDocs.map(fetchDoc));
         // Cross-recipe steering that applies to a family of recipes rather than
         // any single article; rendered right after the index. Gated on the note's
         // target family actually appearing in the rendered index — this also
@@ -244,7 +261,12 @@ export async function addGetToKnowTools({ server, disableTools = [], toolDescrip
                 .map((item) => item.text),
             ...(dynamicContext ? [dynamicContext] : [])
         ];
-        const text = parts.join('\n\n');
+        const joined = parts.join('\n\n');
+        // Mintlify docs: the README links docs pages on dev.wix.com; resolve
+        // them to their Mintlify pages, as the docs tools do.
+        const text = isMintlifyDocsSite(docsSite)
+            ? (await rewriteDocsLinks(joined, { label: 'readme WixREADME' })).text
+            : joined;
         return {
             content: [{ type: 'text', text }]
         };

package/build/dts/docs/mintlify-docs.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Mintlify docs, `mintlify-links` mode (wix-private/docs:
+ * documentation/mintlify-migration/tasks/mcp-pipeline.md).
+ *
+ * The KBs and every backend stay as they are. With `docsSite: 'mintlify-links'`,
+ * the docs tools resolve each dev.wix.com docs link in their output to its page
+ * on the Mintlify site, and ReadFullDocsArticle reads pages from Mintlify's
+ * `.md`. Off unless a caller passes the option.
+ */
+export declare const MINTLIFY_LINKS_DOCS_SITE = "mintlify-links";
+/** Stage 2: the same, with search on the Mintlify KBs indexed from the Mintlify site. */
+export declare const MINTLIFY_DOCS_SITE = "mintlify";
+export type DocsSite = typeof MINTLIFY_LINKS_DOCS_SITE | typeof MINTLIFY_DOCS_SITE;
+export declare const MINTLIFY_HOST = "https://wix-internal.mintlify.site";
+export declare const MAX_CHECK_ENTRIES = 5000;
+export declare function isMintlifyDocsSite(docsSite: string | undefined): boolean;
+/** The Mintlify document types a search tool uses in stage 2, or undefined to search as today. */
+export declare function mintlifyDocumentTypes(docsSite: string | undefined, toolName: string): string[] | undefined;
+export declare function isMintlifyUrl(url: string): boolean;
+/** The URL prefixes the docs tools accept in Mintlify mode, besides dev.wix.com. */
+export declare const MINTLIFY_URL_PREFIXES: string[];
+export interface MintlifyCandidate {
+    /** Canonical Mintlify page URL: host + path, no query, anchor or `.md`. */
+    url: string;
+    path: string;
+    /** `sdk` when the source link asked for the SDK view (`?apiView=SDK`). */
+    flavour: 'rest' | 'sdk';
+}
+/**
+ * Maps a dev.wix.com docs URL, or a Mintlify URL on any alias host, to its
+ * Mintlify page by rule: drop `/docs`, map the portal slug to its tab, drop
+ * the query, the anchor and `.md`. Returns null for anything else.
+ */
+export declare function toMintlifyCandidate(rawUrl: string): MintlifyCandidate | null;
+/**
+ * Maps a Mintlify URL back to its dev.wix.com docs URL, keeping `?apiView=SDK`.
+ * For the REST portal the paths are the same, so the backends that only know
+ * dev.wix.com (ingvar, the docs menu) can serve it.
+ */
+export declare function toDevWixUrl(rawUrl: string): string;
+export type ResolveOutcome = 'identity' | 'redirect' | 'missing' | 'other-portal' | 'not-docs' | 'error';
+export interface ResolvedLink {
+    outcome: ResolveOutcome;
+    /** The URL to hand out: the Mintlify page when resolved, else the input. */
+    url: string;
+}
+interface PageCheck {
+    outcome: 'identity' | 'redirect' | 'missing' | 'error';
+    /** Final page path on the Mintlify site, when the page exists. */
+    path?: string;
+}
+/** For tests. */
+export declare function mintlifyCheckCacheSize(): number;
+/** For tests. */
+export declare function clearMintlifyCheckCache(): void;
+/**
+ * Asks the Mintlify site whether a page exists, following its own redirects
+ * (moves, and containers that send you to their first page) without
+ * following them blindly: a page is a 200 at the end of at most 3 hops.
+ */
+export declare function checkMintlifyPage(path: string): Promise<PageCheck>;
+/**
+ * Resolves one docs link to its Mintlify page. With `verify: false` the
+ * mapping is by rule only, which suits menu links (the menu and the Mintlify
+ * navigation come from the same Portal Service tree).
+ */
+export declare function resolveDocsLink(rawUrl: string, { verify }?: {
+    verify?: boolean;
+}): Promise<ResolvedLink>;
+/**
+ * Maps every Mintlify page link in `text` back to its dev.wix.com docs URL, keeping
+ * `?apiView=SDK` and the anchor. Run before {@link rewriteDocsLinks} on text whose
+ * Mintlify links came by rule rather than from a checked page (SearchWixAPISpec's
+ * index), so a page the site doesn't have ends up on dev.wix.com, not a dead link.
+ */
+export declare function toDevWixHostText(text: string): string;
+export interface RewriteStats {
+    links: number;
+    byOutcome: Partial<Record<ResolveOutcome, number>>;
+    misses: string[];
+}
+/**
+ * Rewrites every docs link in `text` to its Mintlify page. Links with no
+ * Mintlify page stay as they are, so the agent can still read them through
+ * today's backends. Logs one coverage line per call.
+ */
+export declare function rewriteDocsLinks(text: string, { verify, label }?: {
+    verify?: boolean;
+    label?: string;
+}): Promise<{
+    text: string;
+    stats: RewriteStats;
+}>;
+/**
+ * Light cleanup of a method page's .md: drop inlined snippet source, and keep
+ * only the tab the reader asked for (REST, or SDK for `?apiView=SDK`). A
+ * method page carries both, which roughly doubles its size. Pages without
+ * exactly one REST and one SDK tab are left as they are.
+ */
+export declare function cleanMintlifyMarkdown(markdown: string, flavour: 'rest' | 'sdk'): string;
+/**
+ * Tool and parameter descriptions with their docs URLs on the Mintlify host. The
+ * model copies the examples' host when it cites a page, so with dev.wix.com in
+ * the descriptions it rewrites Mintlify links back to dev.wix.com.
+ */
+export declare function toMintlifyHostText(text: string): string;
+/**
+ * Mintlify's .md links the site's own pages by path (`[Order Object](/api-reference/…)`).
+ * Make them absolute, so the model doesn't have to guess the host (it picks dev.wix.com).
+ */
+export declare function absolutizeSiteLinks(markdown: string): string;
+/**
+ * Reads a page from the Mintlify site as Markdown. Returns null when the site
+ * has no page for the URL, so the caller can fall back to today's backend.
+ */
+export declare function readMintlifyMarkdown(rawUrl: string): Promise<{
+    url: string;
+    markdown: string;
+} | null>;
+export {};
+//# sourceMappingURL=mintlify-docs.d.ts.map

package/build/dts/docs/mintlify-docs.js

@@ -0,0 +1,391 @@
+import { logger } from '../infra/logger.js';
+/**
+ * Mintlify docs, `mintlify-links` mode (wix-private/docs:
+ * documentation/mintlify-migration/tasks/mcp-pipeline.md).
+ *
+ * The KBs and every backend stay as they are. With `docsSite: 'mintlify-links'`,
+ * the docs tools resolve each dev.wix.com docs link in their output to its page
+ * on the Mintlify site, and ReadFullDocsArticle reads pages from Mintlify's
+ * `.md`. Off unless a caller passes the option.
+ */
+export const MINTLIFY_LINKS_DOCS_SITE = 'mintlify-links';
+/** Stage 2: the same, with search on the Mintlify KBs indexed from the Mintlify site. */
+export const MINTLIFY_DOCS_SITE = 'mintlify';
+export const MINTLIFY_HOST = 'https://wix-internal.mintlify.site';
+const MINTLIFY_HOSTNAMES = new Set([
+    'wix-internal.mintlify.site',
+    'wix-internal.mintlify.app'
+]);
+const DEV_WIX_DOCS = 'https://dev.wix.com/docs';
+// dev.wix.com portal slug -> Mintlify tab base, where the two differ.
+const PORTAL_SLUG_TO_TAB = {
+    rest: 'api-reference',
+    'mintlify-sandbox': 'sandbox'
+};
+const TAB_TO_PORTAL_SLUG = {
+    sandbox: 'mintlify-sandbox'
+};
+// The tabs the Mintlify site serves. A dev.wix.com link into any other portal
+// (sdk, velo, build-apps, ...) has no page there yet.
+const MINTLIFY_TABS = new Set(['api-reference', 'sandbox', 'kb']);
+// The skills registry is served on dev.wix.com/docs/skills and is not part of
+// the docs site, so its links are left alone.
+const NON_DOCS_SLUGS = new Set(['skills', 'kb-only', 'api']);
+const CHECK_TTL_MS = 10 * 60 * 1000;
+// Bounds the page-check cache, so many distinct paths can't grow it without limit.
+export const MAX_CHECK_ENTRIES = 5000;
+const CHECK_TIMEOUT_MS = 5000;
+const MAX_REDIRECTS = 3;
+const CHECK_CONCURRENCY = 8;
+export function isMintlifyDocsSite(docsSite) {
+    return (docsSite === MINTLIFY_LINKS_DOCS_SITE || docsSite === MINTLIFY_DOCS_SITE);
+}
+// docs-search-server document types that read the Mintlify KBs instead of today's.
+const MINTLIFY_DOCUMENT_TYPES = {
+    REST: ['MINTLIFY_REST'], // includes the skills, as REST + SKILLS does today
+    SDK: ['MINTLIFY_SDK']
+};
+/** The Mintlify document types a search tool uses in stage 2, or undefined to search as today. */
+export function mintlifyDocumentTypes(docsSite, toolName) {
+    return docsSite === MINTLIFY_DOCS_SITE
+        ? MINTLIFY_DOCUMENT_TYPES[toolName]
+        : undefined;
+}
+export function isMintlifyUrl(url) {
+    try {
+        return MINTLIFY_HOSTNAMES.has(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The URL prefixes the docs tools accept in Mintlify mode, besides dev.wix.com. */
+export const MINTLIFY_URL_PREFIXES = [...MINTLIFY_HOSTNAMES].map((host) => `https://${host}/`);
+function cleanPath(pathname) {
+    const path = pathname.replace(/\.md$/, '').replace(/\/+$/, '');
+    return path === '' ? '/' : path;
+}
+function flavourOf(url) {
+    return url.searchParams.get('apiView')?.toUpperCase() === 'SDK'
+        ? 'sdk'
+        : 'rest';
+}
+/**
+ * Maps a dev.wix.com docs URL, or a Mintlify URL on any alias host, to its
+ * Mintlify page by rule: drop `/docs`, map the portal slug to its tab, drop
+ * the query, the anchor and `.md`. Returns null for anything else.
+ */
+export function toMintlifyCandidate(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return null;
+    }
+    if (MINTLIFY_HOSTNAMES.has(url.hostname)) {
+        const path = cleanPath(url.pathname);
+        return { url: `${MINTLIFY_HOST}${path}`, path, flavour: flavourOf(url) };
+    }
+    if (url.hostname !== 'dev.wix.com' || !url.pathname.startsWith('/docs/')) {
+        return null;
+    }
+    const segments = cleanPath(url.pathname.slice('/docs'.length))
+        .split('/')
+        .filter(Boolean);
+    if (segments.length === 0 || NON_DOCS_SLUGS.has(segments[0])) {
+        return null;
+    }
+    segments[0] = PORTAL_SLUG_TO_TAB[segments[0]] ?? segments[0];
+    const path = `/${segments.join('/')}`;
+    return { url: `${MINTLIFY_HOST}${path}`, path, flavour: flavourOf(url) };
+}
+/**
+ * Maps a Mintlify URL back to its dev.wix.com docs URL, keeping `?apiView=SDK`.
+ * For the REST portal the paths are the same, so the backends that only know
+ * dev.wix.com (ingvar, the docs menu) can serve it.
+ */
+export function toDevWixUrl(rawUrl) {
+    const url = new URL(rawUrl);
+    const segments = cleanPath(url.pathname).split('/').filter(Boolean);
+    if (segments.length > 0) {
+        segments[0] = TAB_TO_PORTAL_SLUG[segments[0]] ?? segments[0];
+    }
+    const query = flavourOf(url) === 'sdk' ? '?apiView=SDK' : '';
+    return `${DEV_WIX_DOCS}/${segments.join('/')}${query}`;
+}
+const checkCache = new Map();
+/** Caches a page check, dropping expired entries, then the oldest, once full. */
+function rememberCheck(path, result) {
+    const now = Date.now();
+    checkCache.delete(path);
+    if (checkCache.size >= MAX_CHECK_ENTRIES) {
+        for (const [key, entry] of checkCache) {
+            if (entry.expires <= now)
+                checkCache.delete(key);
+        }
+    }
+    while (checkCache.size >= MAX_CHECK_ENTRIES) {
+        const oldest = checkCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        checkCache.delete(oldest);
+    }
+    checkCache.set(path, { result, expires: now + CHECK_TTL_MS });
+}
+/** For tests. */
+export function mintlifyCheckCacheSize() {
+    return checkCache.size;
+}
+/** For tests. */
+export function clearMintlifyCheckCache() {
+    checkCache.clear();
+}
+async function headOnce(url) {
+    return fetch(url, {
+        method: 'HEAD',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS)
+    });
+}
+/**
+ * Asks the Mintlify site whether a page exists, following its own redirects
+ * (moves, and containers that send you to their first page) without
+ * following them blindly: a page is a 200 at the end of at most 3 hops.
+ */
+export async function checkMintlifyPage(path) {
+    const cached = checkCache.get(path);
+    if (cached && cached.expires > Date.now()) {
+        return cached.result;
+    }
+    if (cached)
+        checkCache.delete(path);
+    let result;
+    try {
+        let current = path;
+        let hops = 0;
+        for (;;) {
+            const response = await headOnce(`${MINTLIFY_HOST}${current}`);
+            if (response.status === 200) {
+                result = {
+                    outcome: hops === 0 ? 'identity' : 'redirect',
+                    path: current
+                };
+                break;
+            }
+            const location = response.headers.get('location');
+            if (response.status >= 300 &&
+                response.status < 400 &&
+                location &&
+                hops < MAX_REDIRECTS) {
+                current = cleanPath(new URL(location, MINTLIFY_HOST).pathname);
+                hops++;
+                continue;
+            }
+            result = { outcome: response.status === 404 ? 'missing' : 'error' };
+            break;
+        }
+    }
+    catch (error) {
+        logger.error(`[mintlify] page check failed for ${path}: ${error}`);
+        result = { outcome: 'error' };
+    }
+    rememberCheck(path, result);
+    return result;
+}
+/**
+ * Resolves one docs link to its Mintlify page. With `verify: false` the
+ * mapping is by rule only, which suits menu links (the menu and the Mintlify
+ * navigation come from the same Portal Service tree).
+ */
+export async function resolveDocsLink(rawUrl, { verify = true } = {}) {
+    const candidate = toMintlifyCandidate(rawUrl);
+    if (!candidate) {
+        return { outcome: 'not-docs', url: rawUrl };
+    }
+    const tab = candidate.path.split('/')[1];
+    if (!MINTLIFY_TABS.has(tab)) {
+        return { outcome: 'other-portal', url: rawUrl };
+    }
+    const query = candidate.flavour === 'sdk' ? '?apiView=SDK' : '';
+    if (!verify) {
+        return { outcome: 'identity', url: `${candidate.url}${query}` };
+    }
+    const check = await checkMintlifyPage(candidate.path);
+    if (check.path) {
+        return {
+            outcome: check.outcome,
+            url: `${MINTLIFY_HOST}${check.path}${query}`
+        };
+    }
+    return { outcome: check.outcome, url: rawUrl };
+}
+// A docs link inside text: markdown targets, bare URLs and "fallback::" forms.
+// Stops at whitespace and markdown/HTML delimiters.
+const DOCS_LINK_PATTERN = /https:\/\/(?:dev\.wix\.com\/docs|wix-internal\.mintlify\.(?:site|app))\/[^\s)\]"'<>`]*/g;
+function trimTrailingPunctuation(url) {
+    return url.replace(/[.,;:!?*]+$/, '');
+}
+// A Mintlify page link inside text, with the same delimiters as DOCS_LINK_PATTERN.
+const MINTLIFY_LINK_PATTERN = /https:\/\/wix-internal\.mintlify\.(?:site|app)\/[^\s)\]"'<>`]*/g;
+/**
+ * Maps every Mintlify page link in `text` back to its dev.wix.com docs URL, keeping
+ * `?apiView=SDK` and the anchor. Run before {@link rewriteDocsLinks} on text whose
+ * Mintlify links came by rule rather than from a checked page (SearchWixAPISpec's
+ * index), so a page the site doesn't have ends up on dev.wix.com, not a dead link.
+ */
+export function toDevWixHostText(text) {
+    return text.replace(MINTLIFY_LINK_PATTERN, (match) => {
+        const link = trimTrailingPunctuation(match);
+        let url;
+        try {
+            url = new URL(link);
+        }
+        catch {
+            return match;
+        }
+        // Only docs pages: other paths on the host (llms.txt, assets) have no
+        // dev.wix.com twin, and rewriteDocsLinks leaves them as they are.
+        if (!MINTLIFY_TABS.has(url.pathname.split('/')[1] ?? ''))
+            return match;
+        return toDevWixUrl(link) + url.hash + match.slice(link.length);
+    });
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Rewrites every docs link in `text` to its Mintlify page. Links with no
+ * Mintlify page stay as they are, so the agent can still read them through
+ * today's backends. Logs one coverage line per call.
+ */
+export async function rewriteDocsLinks(text, { verify = true, label = 'text' } = {}) {
+    const found = [
+        ...new Set((text.match(DOCS_LINK_PATTERN) ?? []).map(trimTrailingPunctuation))
+    ];
+    const stats = {
+        links: found.length,
+        byOutcome: {},
+        misses: []
+    };
+    if (found.length === 0) {
+        return { text, stats };
+    }
+    const resolved = await mapWithConcurrency(found, CHECK_CONCURRENCY, (url) => resolveDocsLink(url, { verify }));
+    const replacements = new Map();
+    found.forEach((url, i) => {
+        const { outcome, url: target } = resolved[i];
+        stats.byOutcome[outcome] = (stats.byOutcome[outcome] ?? 0) + 1;
+        if (outcome === 'identity' || outcome === 'redirect') {
+            if (target !== url)
+                replacements.set(url, target);
+        }
+        else if (outcome !== 'not-docs') {
+            stats.misses.push(`${outcome} ${url}`);
+        }
+    });
+    // Rewrite each match in place, so a link never changes through a shorter
+    // link it starts with.
+    const rewritten = text.replace(DOCS_LINK_PATTERN, (match) => {
+        const url = trimTrailingPunctuation(match);
+        const target = replacements.get(url);
+        return target ? target + match.slice(url.length) : match;
+    });
+    logger.log(`[mintlify] ${label}: ${stats.links} links ${JSON.stringify(stats.byOutcome)}` +
+        (stats.misses.length
+            ? ` misses: ${stats.misses.slice(0, 10).join(' | ')}`
+            : ''));
+    return { text: rewritten, stats };
+}
+// The index banner Mintlify puts at the top of every .md page.
+const INDEX_BANNER = /^> ## Documentation Index\n(?:>.*\n)*\n?/;
+// Mintlify inlines the source of every imported snippet component
+// (`export const WixEndpoint = (...) => { ... };`): code, not docs.
+const INLINED_SNIPPET = /^export const \w+ = [\s\S]*?^};\n/gm;
+const REST_TAB = /<Tab title="REST">([\s\S]*?)<\/Tab>/;
+const SDK_TAB = /<Tab title="SDK">([\s\S]*?)<\/Tab>/;
+/**
+ * Light cleanup of a method page's .md: drop inlined snippet source, and keep
+ * only the tab the reader asked for (REST, or SDK for `?apiView=SDK`). A
+ * method page carries both, which roughly doubles its size. Pages without
+ * exactly one REST and one SDK tab are left as they are.
+ */
+export function cleanMintlifyMarkdown(markdown, flavour) {
+    const text = markdown.replace(INLINED_SNIPPET, '');
+    const rest = text.match(REST_TAB);
+    const sdk = text.match(SDK_TAB);
+    if (!rest || !sdk || (text.match(/<Tab title=/g) ?? []).length !== 2) {
+        return text;
+    }
+    const start = text.lastIndexOf('<Tabs>', rest.index);
+    const end = text.indexOf('</Tabs>', sdk.index);
+    if (start === -1 || end === -1) {
+        return text;
+    }
+    const kept = (flavour === 'sdk' ? sdk : rest)[1];
+    const note = flavour === 'sdk'
+        ? '_This is the SDK view. Drop `?apiView=SDK` from the URL for the REST view._'
+        : '_This is the REST view. Add `?apiView=SDK` to the URL for the JavaScript SDK view._';
+    return `${text.slice(0, start)}${note}\n\n${kept.trim()}\n${text.slice(end + '</Tabs>'.length)}`;
+}
+// A docs URL in tool text that the Mintlify site has: API Reference, or a `…` placeholder.
+// Skills URLs (dev.wix.com/docs/skills) are the skills registry and stay.
+const DOCS_URL_IN_TEXT = /https:\/\/dev\.wix\.com\/docs\/(?=api-reference\b|\.\.\.)/g;
+/**
+ * Tool and parameter descriptions with their docs URLs on the Mintlify host. The
+ * model copies the examples' host when it cites a page, so with dev.wix.com in
+ * the descriptions it rewrites Mintlify links back to dev.wix.com.
+ */
+export function toMintlifyHostText(text) {
+    return text.replace(DOCS_URL_IN_TEXT, `${MINTLIFY_HOST}/`);
+}
+// A Markdown link or an href to a path on the same site: `](/…` or `href="/…`.
+const SITE_RELATIVE_LINK = /(\]\(|href=["'])\/(?!\/)/g;
+/**
+ * Mintlify's .md links the site's own pages by path (`[Order Object](/api-reference/…)`).
+ * Make them absolute, so the model doesn't have to guess the host (it picks dev.wix.com).
+ */
+export function absolutizeSiteLinks(markdown) {
+    return markdown.replace(SITE_RELATIVE_LINK, (_, open) => `${open}${MINTLIFY_HOST}/`);
+}
+/**
+ * Reads a page from the Mintlify site as Markdown. Returns null when the site
+ * has no page for the URL, so the caller can fall back to today's backend.
+ */
+export async function readMintlifyMarkdown(rawUrl) {
+    const resolved = await resolveDocsLink(rawUrl);
+    if (resolved.outcome !== 'identity' && resolved.outcome !== 'redirect') {
+        return null;
+    }
+    const pageUrl = new URL(resolved.url);
+    const response = await fetch(`${MINTLIFY_HOST}${pageUrl.pathname}.md`, {
+        headers: { accept: 'text/markdown' },
+        redirect: 'follow',
+        signal: AbortSignal.timeout(15000)
+    });
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Mintlify returned ${response.status} for ${pageUrl.pathname}.md`);
+    }
+    const flavour = toMintlifyCandidate(rawUrl)?.flavour ?? 'rest';
+    const cleaned = cleanMintlifyMarkdown((await response.text()).replace(INDEX_BANNER, ''), flavour);
+    // The page body still links other pages on dev.wix.com; resolve those too.
+    const { text: rewritten } = await rewriteDocsLinks(cleaned, {
+        label: `read ${pageUrl.pathname}`
+    });
+    const markdown = absolutizeSiteLinks(rewritten);
+    logger.log(`[mintlify] read ${pageUrl.pathname}.md (${markdown.length} chars) for ${rawUrl}`);
+    return { url: `${MINTLIFY_HOST}${pageUrl.pathname}`, markdown };
+}
+//# sourceMappingURL=mintlify-docs.js.map

package/build/dts/docs/semanticSearch.d.ts

@@ -1,6 +1,6 @@
 import type { DocsTool } from './docs.js';
 export declare const DEFAULT_MAX_RESULTS = 15;
-export declare const runSemanticSearchAndFormat: ({ toolName, toolParams, maxResults, rerank, linesInEachResult, usePlatformizedSearch, extraDocumentTypes }: {
+export declare const runSemanticSearchAndFormat: ({ toolName, toolParams, maxResults, rerank, linesInEachResult, usePlatformizedSearch, extraDocumentTypes, documentTypes }: {
     toolName: DocsTool;
     toolParams: Record<string, string>;
     maxResults?: number;
@@ -8,5 +8,6 @@ export declare const runSemanticSearchAndFormat: ({ toolName, toolParams, maxRes
     linesInEachResult?: number | undefined;
     usePlatformizedSearch?: boolean;
     extraDocumentTypes?: string[];
+    documentTypes?: string[];
 }) => Promise<string>;
 //# sourceMappingURL=semanticSearch.d.ts.map