@taurgis/bonsai 1.0.0

package/dist/lib/research/url.js

@@ -0,0 +1,121 @@
+import { isIP } from 'node:net';
+/**
+ * Checks if a literal IPv4 address is in a safe range.
+ * Rejects loopback, private RFC1918, and link-local ranges.
+ */
+export function isSafeIpv4(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(isNaN))
+        return false;
+    const [a, b, c] = parts;
+    if (a === undefined || b === undefined || c === undefined)
+        return false;
+    // Loopback: 127.0.0.0/8
+    if (a === 127)
+        return false;
+    // Private (RFC1918): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+    if (a === 10)
+        return false;
+    if (a === 172 && b >= 16 && b <= 31)
+        return false;
+    if (a === 192 && b === 168)
+        return false;
+    // Link-local: 169.254.0.0/16
+    if (a === 169 && b === 254)
+        return false;
+    return true;
+}
+/**
+ * Checks if a literal IPv6 address is in a safe range.
+ * Rejects loopback, unspecified, link-local, and mapped unsafe IPv4 ranges.
+ */
+export function isSafeIpv6(ip) {
+    const cleanIp = ip.toLowerCase().trim();
+    // Loopback: ::1
+    if (cleanIp === '::1' || cleanIp === '0:0:0:0:0:0:0:1')
+        return false;
+    // Unspecified: ::
+    if (cleanIp === '::' || cleanIp === '0:0:0:0:0:0:0:0')
+        return false;
+    // Link-local: fe80::/10 (fe80 to febf)
+    if (cleanIp.startsWith('fe8') ||
+        cleanIp.startsWith('fe9') ||
+        cleanIp.startsWith('fea') ||
+        cleanIp.startsWith('feb')) {
+        return false;
+    }
+    // IPv4-mapped IPv6: ::ffff:127.0.0.1
+    if (cleanIp.startsWith('::ffff:')) {
+        const ipv4Part = ip.slice(7);
+        if (isIP(ipv4Part) === 4) {
+            return isSafeIpv4(ipv4Part);
+        }
+    }
+    return true;
+}
+/**
+ * Checks if a literal IP address is a safe public IP.
+ * Returns false for loopback, private, link-local, or unspecified ranges.
+ */
+export function isSafeIp(ip) {
+    const version = isIP(ip);
+    if (version === 4)
+        return isSafeIpv4(ip);
+    if (version === 6)
+        return isSafeIpv6(ip);
+    return false;
+}
+/**
+ * Validates a hostname to ensure it is not blocked (e.g. localhost or literal private IP).
+ */
+export function validateHostname(hostname) {
+    const lower = hostname.toLowerCase().trim();
+    if (lower === 'localhost' || lower.endsWith('.localhost')) {
+        throw new Error(`Hostname "${hostname}" is a blocked local target.`);
+    }
+    let ipToCheck = lower;
+    if (ipToCheck.startsWith('[') && ipToCheck.endsWith(']')) {
+        ipToCheck = ipToCheck.slice(1, -1);
+    }
+    if (isIP(ipToCheck) !== 0) {
+        if (!isSafeIp(ipToCheck)) {
+            throw new Error(`IP address "${ipToCheck}" is a blocked local or private target.`);
+        }
+    }
+}
+/**
+ * Parses and normalizes a URL. Strips fragments, credentials, default ports,
+ * and sorts query parameters lexicographically.
+ */
+export function normalizeUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch (err) {
+        throw new Error(`Invalid URL "${input}": ${err.message}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Unsupported protocol "${url.protocol}". Only http: and https: are supported.`);
+    }
+    if (url.username || url.password) {
+        throw new Error('URLs containing usernames or passwords are rejected.');
+    }
+    validateHostname(url.hostname);
+    // Clear default ports
+    if (url.protocol === 'https:' && url.port === '443') {
+        url.port = '';
+    }
+    if (url.protocol === 'http:' && url.port === '80') {
+        url.port = '';
+    }
+    // Strip plain anchor fragments, but PRESERVE SPA hash routes (e.g. Docsify "#/guide/intro",
+    // "#!/path") so client-rendered docs get a distinct, consistent cache key per page (T-28).
+    if (!/^#!?\//.test(url.hash)) {
+        url.hash = '';
+    }
+    // Sort query parameters
+    const params = Array.from(url.searchParams.entries()).sort((a, b) => a[0].localeCompare(b[0]) || a[1].localeCompare(b[1]));
+    url.search = new URLSearchParams(params).toString();
+    return url.toString();
+}

package/dist/sites/index.d.ts

@@ -0,0 +1,4 @@
+import type { SiteModule } from './types.js';
+export declare const SITES: SiteModule[];
+export declare function detectSite(url: string): SiteModule | undefined;
+export declare function getSiteModuleById(id: string): SiteModule | undefined;

package/dist/sites/index.js

@@ -0,0 +1,28 @@
+import { salesforce } from './salesforce/index.js';
+import { salesforceDeveloper } from './salesforce-developer/index.js';
+// The known documentation sites. A plain constant, not a registry: these ship
+// with the CLI, so there is nothing to register at runtime. Sites with custom
+// fetch/search behavior live in their own module (e.g. ./salesforce). Salesforce Help and
+// Salesforce Developer are separate modules — different domains, different extraction.
+export const SITES = [
+    { id: 'react', name: 'React', domains: ['react.dev', 'legacy.reactjs.org'] },
+    salesforce,
+    salesforceDeveloper,
+    // TanStack docs embed a GitHub "edit this page" link, so capture resolves the page's source
+    // Markdown (code blocks intact) and only falls back to the browser when no source is found.
+    // Forcing rendered here bypassed that and dropped fenced code samples (e.g. useQueries).
+    { id: 'tanstack', name: 'TanStack', domains: ['tanstack.com'] },
+];
+export function detectSite(url) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    return SITES.find((site) => site.domains.includes(hostname));
+}
+export function getSiteModuleById(id) {
+    return SITES.find((site) => site.id === id);
+}

package/dist/sites/salesforce/browser-search.d.ts

@@ -0,0 +1,7 @@
+import type { SiteSearchResult } from '../types.js';
+/**
+ * Searches Salesforce Help via Coveo. Reuses a cached token for a direct API call when
+ * possible; otherwise drives a headless browser, reads the page's own Coveo search response,
+ * and caches the Coveo token (intercepted from the page's Aura call) for the next run.
+ */
+export declare function searchSalesforce(query: string, limit?: number): Promise<SiteSearchResult[]>;

package/dist/sites/salesforce/browser-search.js

@@ -0,0 +1,82 @@
+import { openCdpPage, waitForLoad, ResponseCapture } from '../../lib/research/browser.js';
+import { checkDnsSafety } from '../../lib/research/fetcher.js';
+import { buildSearchPageUrl, extractCoveoResults, searchCoveoDirect, COVEO_SEARCH_PATH, AURA_PATH, } from './coveo.js';
+import { loadToken, storeToken, isTokenValid, parseAuraToken } from './token.js';
+const DEFAULT_LIMIT = 10;
+const PAGE_LOAD_TIMEOUT_MS = 15_000;
+const COVEO_WAIT_MS = 30_000;
+const TOKEN_WAIT_MS = 5_000;
+const DEBUG = Boolean(process.env.RESEARCH_DEBUG);
+function dbg(message) {
+    if (DEBUG)
+        console.error(`[salesforce-search] ${message}`);
+}
+// Salesforce gates content behind a OneTrust cookie banner; dismissing it lets the page run.
+const ACCEPT_CONSENT_EXPRESSION = "(() => { const b = document.querySelector('#onetrust-accept-btn-handler'); if (b) b.click(); })()";
+/**
+ * Searches Salesforce Help via Coveo. Reuses a cached token for a direct API call when
+ * possible; otherwise drives a headless browser, reads the page's own Coveo search response,
+ * and caches the Coveo token (intercepted from the page's Aura call) for the next run.
+ */
+export async function searchSalesforce(query, limit = DEFAULT_LIMIT) {
+    const cached = loadToken();
+    if (cached && isTokenValid(cached.expiresAtMs)) {
+        dbg('using cached token (direct Coveo call)');
+        const results = extractCoveoResults(await searchCoveoDirect(cached, query, limit), limit);
+        if (results.length)
+            return results;
+        dbg('cached token returned no results; falling back to browser');
+    }
+    return searchViaBrowser(query, limit);
+}
+async function searchViaBrowser(query, limit) {
+    await checkDnsSafety('help.salesforce.com');
+    const page = await openCdpPage();
+    try {
+        // No asset blocking: the search SPA must fully boot to run its query and mint its token.
+        const capture = new ResponseCapture(page, [
+            { key: 'coveo', test: ({ url }) => url.includes(COVEO_SEARCH_PATH) },
+            // help.salesforce.com runs on LWR (no global $A to mint a token ourselves), so we
+            // intercept the page's own Aura token response — the one whose body parses to a token.
+            {
+                key: 'token',
+                test: ({ url }) => url.includes(AURA_PATH),
+                accept: (body) => parseAuraToken(body) !== null,
+            },
+        ]);
+        await page.client.send('Page.navigate', { url: buildSearchPageUrl(query) }, page.sessionId);
+        await waitForLoad(page.client, page.sessionId, PAGE_LOAD_TIMEOUT_MS).catch(() => { });
+        await page.client
+            .send('Runtime.evaluate', { expression: ACCEPT_CONSENT_EXPRESSION }, page.sessionId)
+            .catch(() => { });
+        const coveoBody = await capture.waitFor('coveo', COVEO_WAIT_MS);
+        await cacheToken(capture);
+        if (!coveoBody) {
+            dbg('no Coveo search response captured');
+            return [];
+        }
+        return extractCoveoResults(parseJson(coveoBody), limit);
+    }
+    finally {
+        await page.close();
+    }
+}
+async function cacheToken(capture) {
+    const tokenBody = await capture.waitFor('token', TOKEN_WAIT_MS);
+    const token = tokenBody ? parseAuraToken(tokenBody) : null;
+    if (token) {
+        storeToken(token);
+        dbg('cached Coveo token for next run');
+    }
+    else {
+        dbg('no Aura token response intercepted; next run will use the browser again');
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sites/salesforce/coveo.d.ts

@@ -0,0 +1,23 @@
+import type { SiteSearchResult } from '../types.js';
+import { type TokenInfo } from './token.js';
+export declare const ALLOWED_DOC_HOSTS: Set<string>;
+export declare const SEARCH_PAGE_URL = "https://help.salesforce.com/s/search-result";
+export declare const COVEO_SEARCH_PATH = "/services/apexrest/coveo/analytics/rest/search/v2";
+export declare const DEFAULT_LANGUAGE = "en_US";
+export declare const AURA_PATH = "/s/sfsites/aura";
+export declare function isAllowedDocHost(hostname: string): boolean;
+/** The search page reads its query from the URL hash, so this URL is browser-only (never normalized). */
+export declare function buildSearchPageUrl(query: string, language?: string): string;
+/**
+ * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
+ * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ */
+export declare function normalizeHelpDocContentUrl(rawUrl: string): string;
+/** Maps a raw Coveo response into deduped, host-validated search results. */
+export declare function extractCoveoResults(data: unknown, limit: number): SiteSearchResult[];
+/**
+ * Direct Coveo Search API call using a cached token — the no-browser fast path.
+ * Tries a bearer header first, then falls back to a query-string token on auth rejection.
+ * Returns the parsed response body (with a `results` array) or null on failure.
+ */
+export declare function searchCoveoDirect(tokenInfo: TokenInfo, query: string, limit: number, language?: string, timeoutMs?: number): Promise<unknown | null>;

package/dist/sites/salesforce/coveo.js

@@ -0,0 +1,161 @@
+import { COVEO_DEFAULTS } from './token.js';
+export const ALLOWED_DOC_HOSTS = new Set(['help.salesforce.com', 'developer.salesforce.com']);
+export const SEARCH_PAGE_URL = 'https://help.salesforce.com/s/search-result';
+// Path of the XHR the search page fires; we intercept its response as a fallback.
+export const COVEO_SEARCH_PATH = '/services/apexrest/coveo/analytics/rest/search/v2';
+export const DEFAULT_LANGUAGE = 'en_US';
+// The page mints its Coveo token via an Aura action on this path; we intercept the response
+// (identified by whether its body parses to a token) to cache it for the no-browser fast path.
+export const AURA_PATH = '/s/sfsites/aura';
+export function isAllowedDocHost(hostname) {
+    return ALLOWED_DOC_HOSTS.has(hostname.toLowerCase());
+}
+/** The search page reads its query from the URL hash, so this URL is browser-only (never normalized). */
+export function buildSearchPageUrl(query, language = DEFAULT_LANGUAGE) {
+    const url = new URL(SEARCH_PAGE_URL);
+    if (language)
+        url.searchParams.set('language', language);
+    if (query) {
+        url.hash = new URLSearchParams({ q: query, t: 'allResultsTab', sort: 'relevancy' }).toString();
+    }
+    return url.toString();
+}
+/**
+ * Coveo indexes Help articles under an internal `/help_doccontent` URL; rewrite it to the
+ * canonical `/s/articleView` page a human (or our fetcher) can actually open.
+ */
+export function normalizeHelpDocContentUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return rawUrl;
+    }
+    if (url.hostname.toLowerCase() !== 'help.salesforce.com')
+        return rawUrl;
+    if (!url.pathname.toLowerCase().startsWith('/help_doccontent'))
+        return rawUrl;
+    const id = url.searchParams.get('id');
+    if (!id)
+        return rawUrl;
+    const articleUrl = new URL('https://help.salesforce.com/s/articleView');
+    articleUrl.searchParams.set('id', id.endsWith('.htm') ? id : `${id}.htm`);
+    articleUrl.searchParams.set('type', '5');
+    for (const key of ['release', 'language']) {
+        const value = url.searchParams.get(key);
+        if (value)
+            articleUrl.searchParams.set(key, value);
+    }
+    return articleUrl.toString();
+}
+const SKIP_URLS = new Set([
+    'https://help.salesforce.com/',
+    'https://help.salesforce.com/s',
+    'https://help.salesforce.com/s/',
+    'https://help.salesforce.com/s/login',
+]);
+function resultUrl(result) {
+    const raw = result.raw || {};
+    return (result.clickUri ||
+        result.uri ||
+        raw.clickuri ||
+        raw.uri ||
+        raw.sourceurl ||
+        raw.document_uri ||
+        raw.sfurl ||
+        raw.sfdcurl ||
+        null);
+}
+/** Maps a raw Coveo response into deduped, host-validated search results. */
+export function extractCoveoResults(data, limit) {
+    const results = Array.isArray(data?.results)
+        ? data.results
+        : [];
+    const items = [];
+    const seen = new Set();
+    for (const result of results) {
+        const candidate = resultUrl(result);
+        if (!candidate)
+            continue;
+        const url = normalizeHelpDocContentUrl(candidate);
+        let hostname;
+        try {
+            hostname = new URL(url).hostname;
+        }
+        catch {
+            continue;
+        }
+        if (!isAllowedDocHost(hostname) || SKIP_URLS.has(url) || seen.has(url))
+            continue;
+        seen.add(url);
+        items.push({
+            url,
+            title: result.title || result.raw?.title || url,
+            ...(result.excerpt ? { snippet: result.excerpt } : {}),
+        });
+        if (items.length >= limit)
+            break;
+    }
+    return items;
+}
+function buildCoveoPayload(tokenInfo, query, language, limit) {
+    const payload = {
+        q: query,
+        numberOfResults: limit,
+        firstResult: 0,
+        searchHub: tokenInfo.searchHub,
+        locale: language,
+        tab: 'allResultsTab',
+        sortCriteria: 'relevancy',
+    };
+    if (tokenInfo.filterer)
+        payload.aq = tokenInfo.filterer;
+    return payload;
+}
+/**
+ * Direct Coveo Search API call using a cached token — the no-browser fast path.
+ * Tries a bearer header first, then falls back to a query-string token on auth rejection.
+ * Returns the parsed response body (with a `results` array) or null on failure.
+ */
+export async function searchCoveoDirect(tokenInfo, query, limit, language = DEFAULT_LANGUAGE, timeoutMs = 15_000) {
+    const clientBase = (tokenInfo.clientUri || COVEO_DEFAULTS.clientUri).replace(/\/$/, '');
+    const payload = JSON.stringify(buildCoveoPayload(tokenInfo, query, language, limit));
+    const attempt = async (mode) => {
+        const url = new URL(`${clientBase}/rest/search/v2`);
+        // ponytail: query-string token is a documented Coveo fallback for clients that strip the
+        // Authorization header. It can land in proxy logs, but this is an anonymous public search
+        // token (no user identity), so the exposure is acceptable; revisit if the token ever binds a user.
+        if (mode === 'query')
+            url.searchParams.set('access_token', tokenInfo.accessToken);
+        const headers = { 'content-type': 'application/json' };
+        if (mode === 'header')
+            headers.authorization = `Bearer ${tokenInfo.accessToken}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: payload,
+                signal: controller.signal,
+            });
+            const data = response.ok ? await response.json().catch(() => null) : null;
+            return { status: response.status, data };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    try {
+        const primary = await attempt('header');
+        if (primary.data)
+            return primary.data;
+        if (![400, 401, 403].includes(primary.status))
+            return null;
+        return (await attempt('query')).data;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sites/salesforce/fetch-page.d.ts

@@ -0,0 +1,6 @@
+import type { SiteFetchResult } from '../types.js';
+/**
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten
+ * to the canonical /s/articleView page first; the shared LWR fetcher does the rest.
+ */
+export declare function fetchSalesforcePage(url: string): Promise<SiteFetchResult>;

package/dist/sites/salesforce/fetch-page.js

@@ -0,0 +1,42 @@
+import { fetchSalesforceDoc } from '../salesforce-doc-fetch.js';
+import { normalizeHelpDocContentUrl } from './coveo.js';
+// Containers a Help article renders into (inside shadow DOM); the shared fetcher pierces
+// shadow roots to find them, falling back to the page body when none match.
+const CONTENT_SELECTORS = [
+    'c-hc-documentation-article',
+    '.markdown-content',
+    '.ht-body',
+    '.slds-rich-text-editor__output',
+    '.article-body',
+    'article',
+    'main',
+    '.cHCPortalTheme',
+];
+/**
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten
+ * to the canonical /s/articleView page first; the shared LWR fetcher does the rest.
+ */
+export async function fetchSalesforcePage(url) {
+    return fetchSalesforceDoc(normalizeHelpDocContentUrl(url), {
+        allowedHost: 'help.salesforce.com',
+        contentSelectors: CONTENT_SELECTORS,
+        removeSelectors: [
+            // The "Did this article solve your issue?" widget appears on every article.
+            'c-hc-article-feedback',
+            // The left-hand docs navigation tree (table of contents). Keyed by class, not an
+            // aria-label, so it escapes the shared chrome filter — and it can be 100k+ chars of
+            // link text, which the container pick would otherwise capture as content.
+            '.toc-container',
+            // In-article navigation chrome that sits inside the article container: the collapsed
+            // "Show Table of Contents" control and the "You are here" breadcrumb trail.
+            'c-hc-table-of-content',
+            '[class*="breadcrumb" i]',
+            // Screen-reader-only labels (visually hidden) — "You are here:", a duplicate title, toggle
+            // labels. innerText skips them so they don't show on screen, but the serializer captures
+            // hidden nodes; they are always redundant a11y text, never primary content.
+            '.slds-assistive-text',
+            '.ht-foot',
+            '.ht-footer',
+        ],
+    });
+}

package/dist/sites/salesforce/index.d.ts

@@ -0,0 +1,2 @@
+import type { SiteModule } from '../types.js';
+export declare const salesforce: SiteModule;

package/dist/sites/salesforce/index.js

@@ -0,0 +1,16 @@
+import { fetchSalesforcePage } from './fetch-page.js';
+import { searchSalesforce } from './browser-search.js';
+// Scoped to help.salesforce.com — an LWR Experience site with light-DOM article content and
+// Coveo (HTCommunity) search. developer.salesforce.com is intentionally NOT routed here: its
+// API-reference docs render inside shadow DOM with tabbed/code content that needs a different
+// extraction strategy, so it belongs in its own module when built — not bolted onto this one.
+// (developer.salesforce.com URLs that appear in Help search results are still surfaced; see
+// ALLOWED_DOC_HOSTS in coveo.ts.)
+export const salesforce = {
+    id: 'salesforce',
+    name: 'Salesforce Help',
+    domains: ['help.salesforce.com'],
+    defaults: { rendered: true },
+    fetchPage: fetchSalesforcePage,
+    search: searchSalesforce,
+};

package/dist/sites/salesforce/token.d.ts

@@ -0,0 +1,26 @@
+export declare const COVEO_DEFAULTS: {
+    readonly organizationId: "org62salesforce";
+    readonly searchHub: "HTCommunity";
+    readonly endpointBase: "https://help.salesforce.com/services/apexrest/coveo";
+    readonly clientUri: "https://platform.cloud.coveo.com";
+};
+export interface TokenInfo {
+    accessToken: string;
+    organizationId: string;
+    searchHub: string;
+    endpointBase: string;
+    clientUri: string;
+    filterer: string | null;
+    expiresAtMs: number;
+}
+export declare function isTokenValid(expiresAtMs: number | null | undefined): boolean;
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+export declare function getTokenExpiryMs(accessToken: string): number | null;
+export declare function applyTokenExpiry(tokenInfo: TokenInfo): TokenInfo;
+/**
+ * Parses the access token out of a Salesforce Aura `getToken` response body.
+ * Returns null when the payload is missing, errored, or lacks a token.
+ */
+export declare function parseAuraToken(rawResponseBody: string): TokenInfo | null;
+export declare function loadToken(): TokenInfo | null;
+export declare function storeToken(tokenInfo: TokenInfo): void;