@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/lib/text.d.ts

@@ -1,27 +1,33 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export declare const NO_TOPIC_LABEL = "(no topic)";
+export declare const CONTROL_CHAR_PATTERN: RegExp;
+/**
+ * Strip ANSI escape codes and other control characters from a cached metadata string before it
+ * reaches a human-readable terminal line. Fields like `topic` and section headings can originate
+ * from fetched web content or agent-supplied notes — both untrusted per the repo's trust-boundary
+ * rules — so a value containing raw escape bytes must never be echoed as-is to a TTY. Newlines and
+ * tabs collapse to a single space rather than being stripped outright, so injected content can't
+ * fake extra output lines while still being removed. JSON output is unaffected: `JSON.stringify`
+ * already escapes control characters, so this only needs to run on the human-readable path.
+ */
+export declare function sanitizeForTerminal(value: string): string;
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
  * rather than derived.
  */
 export declare function pluralize(count: number, singular: string, plural: string): string;
-/** How a command labels a result listing, so its heading and truncation notice stay consistent. */
+/** Shared "Tip: " prefix for contextual next-step suggestions in human-mode output. */
+export declare function formatTip(message: string): string;
+/** How a command labels a result listing, so its heading stays consistent. */
 export interface ResultListLabels {
     /** Noun phrase after the count, e.g. "cached research"; the "entry/entries" plural is appended. */
     noun: string;
     /** Ordering word shown when truncated: "first" (recency order) or "top" (ranked order). */
     order: 'first' | 'top';
-    /** The command's --limit ceiling, surfaced in the truncation hint. */
-    maxLimit: number;
 }
 /** Heading for a result listing; notes truncation inline when more matched than are shown. */
 export declare function resultListHeading(total: number, shown: number, labels: ResultListLabels): string;
-/**
- * One-line truncation notice for stderr, or null when nothing was cut. Used under --json, where the
- * stdout heading is suppressed and an agent would otherwise get no signal that results were capped.
- */
-export declare function truncationNotice(total: number, shown: number, labels: ResultListLabels): string | null;
 /** Max edit distance for a plausible typo; scales with input length. */
 export declare function maxFuzzyDistance(input: string): number;
 /**
@@ -35,3 +41,8 @@ export declare function levenshtein(s1: string, s2: string): number;
  * gets no correction rather than an absurd one.
  */
 export declare function closestMatch(input: string, candidates: readonly string[], maxDistance: number): string | null;
+/**
+ * Plausible option-value corrections: edit-distance first, then prefix matches for truncated enums
+ * (`stale` → `stale_grace` / `stale_expired`) where Levenshtein alone is too far.
+ */
+export declare function closestOptionValues(input: string, options: readonly string[]): string[];

package/dist/lib/text.js

@@ -1,5 +1,22 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export const NO_TOPIC_LABEL = '(no topic)';
+// Unicode "Control" category (C0 + C1) covers ANSI/terminal escape sequences: the ESC control
+// character that starts them is a member, so stripping this category is what keeps injected
+// control bytes from reaching a real terminal. Exported so `prompt-injection.ts`'s
+// multi-line-content variant (which preserves tab/newline/CR) shares this one definition.
+export const CONTROL_CHAR_PATTERN = /\p{Cc}/gu;
+/**
+ * Strip ANSI escape codes and other control characters from a cached metadata string before it
+ * reaches a human-readable terminal line. Fields like `topic` and section headings can originate
+ * from fetched web content or agent-supplied notes — both untrusted per the repo's trust-boundary
+ * rules — so a value containing raw escape bytes must never be echoed as-is to a TTY. Newlines and
+ * tabs collapse to a single space rather than being stripped outright, so injected content can't
+ * fake extra output lines while still being removed. JSON output is unaffected: `JSON.stringify`
+ * already escapes control characters, so this only needs to run on the human-readable path.
+ */
+export function sanitizeForTerminal(value) {
+    return value.replace(/[\t\n\r]/g, ' ').replace(CONTROL_CHAR_PATTERN, '');
+}
 /**
  * Pick the singular or plural noun for a count so human-readable output stays grammatical
  * ("1 entry" / "2 entries"). English has irregular plurals, so the plural is passed explicitly
@@ -8,6 +25,10 @@ export const NO_TOPIC_LABEL = '(no topic)';
 export function pluralize(count, singular, plural) {
     return count === 1 ? singular : plural;
 }
+/** Shared "Tip: " prefix for contextual next-step suggestions in human-mode output. */
+export function formatTip(message) {
+    return `Tip: ${message}`;
+}
 /** Heading for a result listing; notes truncation inline when more matched than are shown. */
 export function resultListHeading(total, shown, labels) {
     const noun = `${labels.noun} ${pluralize(total, 'entry', 'entries')}`;
@@ -15,15 +36,6 @@ export function resultListHeading(total, shown, labels) {
         ? `Found ${total} ${noun} (showing ${labels.order} ${shown}; raise --limit to see more):`
         : `Found ${total} ${noun}:`;
 }
-/**
- * One-line truncation notice for stderr, or null when nothing was cut. Used under --json, where the
- * stdout heading is suppressed and an agent would otherwise get no signal that results were capped.
- */
-export function truncationNotice(total, shown, labels) {
-    if (total <= shown)
-        return null;
-    return `${total} entries matched; returning the ${labels.order} ${shown}. Raise --limit (max ${labels.maxLimit}) to see more.`;
-}
 /** Max edit distance for a plausible typo; scales with input length. */
 export function maxFuzzyDistance(input) {
     if (input.length <= 3)
@@ -71,3 +83,14 @@ export function closestMatch(input, candidates, maxDistance) {
     }
     return bestDistance <= maxDistance ? best : null;
 }
+/**
+ * Plausible option-value corrections: edit-distance first, then prefix matches for truncated enums
+ * (`stale` → `stale_grace` / `stale_expired`) where Levenshtein alone is too far.
+ */
+export function closestOptionValues(input, options) {
+    const edit = closestMatch(input, options, maxFuzzyDistance(input));
+    if (edit)
+        return [edit];
+    // Exact equals already won via closestMatch; prefix covers truncated enums (stale → stale_*).
+    return options.filter((option) => option.startsWith(`${input}_`));
+}

package/dist/lib/value-flags.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from '@oclif/core';
+type FlagDef = {
+    type?: string;
+    char?: string;
+    aliases?: string[] | string;
+    charAliases?: string[];
+};
+/**
+ * Derive every CLI token that consumes a following argv value from command class metadata
+ * (long names, short chars, aliases). Used by argv normalization so VALUE_TAKING_FLAG_TOKENS
+ * cannot drift from the real command surface.
+ */
+export declare function valueTakingFlagTokensFromCommands(commands: Record<string, typeof Command>, extraBaseFlags?: Record<string, FlagDef>): Set<string>;
+export {};

package/dist/lib/value-flags.js

@@ -0,0 +1,28 @@
+/** Every argv token that selects this flag: long name, short char, and all aliases. */
+function flagTokens(name, flag) {
+    const tokens = [`--${name}`];
+    if (flag.char)
+        tokens.push(`-${flag.char}`);
+    const aliases = typeof flag.aliases === 'string' ? [flag.aliases] : (flag.aliases ?? []);
+    tokens.push(...aliases.map((alias) => `--${alias}`));
+    tokens.push(...(flag.charAliases ?? []).map((charAlias) => `-${charAlias}`));
+    return tokens;
+}
+/**
+ * Derive every CLI token that consumes a following argv value from command class metadata
+ * (long names, short chars, aliases). Used by argv normalization so VALUE_TAKING_FLAG_TOKENS
+ * cannot drift from the real command surface.
+ */
+export function valueTakingFlagTokensFromCommands(commands, extraBaseFlags = {}) {
+    const tokens = new Set();
+    for (const command of Object.values(commands)) {
+        const flags = { ...extraBaseFlags, ...command.baseFlags, ...command.flags };
+        for (const [name, flag] of Object.entries(flags)) {
+            if (!flag || flag.type === 'boolean')
+                continue;
+            for (const token of flagTokens(name, flag))
+                tokens.add(token);
+        }
+    }
+    return tokens;
+}

package/dist/sites/coveo.d.ts

@@ -1,7 +1,17 @@
+/** Hostnames served by Salesforce-operated Lightning Web Runtime (LWR) doc sites with shared browser-capture logic. */
 export declare const ALLOWED_DOC_HOSTS: Set<string>;
+/**
+ * Returns true when `hostname` is one of the allowed Salesforce doc hosts.
+ *
+ * @param hostname - Hostname to check (case-insensitive).
+ * @returns True when the hostname is in `ALLOWED_DOC_HOSTS`.
+ */
 export declare function isAllowedDocHost(hostname: string): boolean;
 /**
  * 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.
+ *
+ * @param rawUrl - Any URL string; non-matching URLs are returned unchanged.
+ * @returns The canonical articleView URL, or `rawUrl` unchanged if no rewrite applies.
  */
 export declare function normalizeHelpDocContentUrl(rawUrl: string): string;

package/dist/sites/coveo.js

@@ -1,10 +1,20 @@
+/** Hostnames served by Salesforce-operated Lightning Web Runtime (LWR) doc sites with shared browser-capture logic. */
 export const ALLOWED_DOC_HOSTS = new Set(['help.salesforce.com', 'developer.salesforce.com']);
+/**
+ * Returns true when `hostname` is one of the allowed Salesforce doc hosts.
+ *
+ * @param hostname - Hostname to check (case-insensitive).
+ * @returns True when the hostname is in `ALLOWED_DOC_HOSTS`.
+ */
 export function isAllowedDocHost(hostname) {
     return ALLOWED_DOC_HOSTS.has(hostname.toLowerCase());
 }
 /**
  * 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.
+ *
+ * @param rawUrl - Any URL string; non-matching URLs are returned unchanged.
+ * @returns The canonical articleView URL, or `rawUrl` unchanged if no rewrite applies.
  */
 export function normalizeHelpDocContentUrl(rawUrl) {
     let url;

package/dist/sites/index.d.ts

@@ -1,4 +1,20 @@
 import type { SiteModule } from './types.js';
+/**
+ * Built-in documentation site modules shipped with the CLI (not a runtime registry).
+ * Salesforce Help and Salesforce Developer are separate entries — different domains and extractors.
+ */
 export declare const SITES: SiteModule[];
+/**
+ * Matches a URL to its registered site module by hostname. Returns undefined for unrecognized hosts.
+ *
+ * @param url - Any URL string; invalid URLs return undefined rather than throwing.
+ * @returns The matching SiteModule, or undefined when no registered site owns the URL's hostname.
+ */
 export declare function detectSite(url: string): SiteModule | undefined;
+/**
+ * Looks up a registered site module by its stable identifier (e.g. `'salesforce'`).
+ *
+ * @param id - The site module's `id` field.
+ * @returns The matching SiteModule, or undefined when no module with that id is registered.
+ */
 export declare function getSiteModuleById(id: string): SiteModule | undefined;

package/dist/sites/index.js

@@ -1,9 +1,9 @@
 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 behavior live in their own module (e.g. ./salesforce). Salesforce Help and
-// Salesforce Developer are separate modules — different domains, different extraction.
+/**
+ * Built-in documentation site modules shipped with the CLI (not a runtime registry).
+ * Salesforce Help and Salesforce Developer are separate entries — different domains and extractors.
+ */
 export const SITES = [
     salesforce,
     salesforceDeveloper,
@@ -12,6 +12,12 @@ export const SITES = [
     // Forcing rendered here bypassed that and dropped fenced code samples (e.g. useQueries).
     { id: 'tanstack', name: 'TanStack', domains: ['tanstack.com'] },
 ];
+/**
+ * Matches a URL to its registered site module by hostname. Returns undefined for unrecognized hosts.
+ *
+ * @param url - Any URL string; invalid URLs return undefined rather than throwing.
+ * @returns The matching SiteModule, or undefined when no registered site owns the URL's hostname.
+ */
 export function detectSite(url) {
     let hostname;
     try {
@@ -22,6 +28,12 @@ export function detectSite(url) {
     }
     return SITES.find((site) => site.domains.includes(hostname));
 }
+/**
+ * Looks up a registered site module by its stable identifier (e.g. `'salesforce'`).
+ *
+ * @param id - The site module's `id` field.
+ * @returns The matching SiteModule, or undefined when no module with that id is registered.
+ */
 export function getSiteModuleById(id) {
     return SITES.find((site) => site.id === id);
 }

package/dist/sites/markdown-twin.d.ts

@@ -0,0 +1,31 @@
+import { fetchText } from '../lib/research/fetcher.js';
+import type { SiteFetchResult } from './types.js';
+/** Result of a per-site body transform applied before extraction. */
+export interface TwinBodyTransform {
+    body: string;
+    /** Appended to the extraction's qualityNotes when set (e.g. "N directive(s) removed"). */
+    qualityNote?: string;
+}
+/** Options for {@link probeMarkdownTwin}. */
+export interface MarkdownTwinOptions {
+    /** Hostname the redirect chain must land on (see `isValidatedMarkdownTwin`). */
+    allowedHost: string;
+    /** Injectable fetcher (tests supply a fixture; production defaults to `fetchText`). */
+    fetcher?: typeof fetchText;
+    timeoutMs?: number;
+    /** Extra request headers (e.g. a WAF-appeasing User-Agent). */
+    headers?: Record<string, string>;
+    /** Applied to the raw body before extraction. Omit when the twin needs no preprocessing. */
+    transformBody?: (body: string) => TwinBodyTransform;
+}
+/**
+ * Probes candidate `.md`-twin URLs in order and returns the first that validates as a usable
+ * article, packaged as a SiteFetchResult with `route_markdown` provenance. Returns null when
+ * every candidate 404s, fails validation, or extracts thinner than the minimum viable article —
+ * callers fall back to their browser capture in that case. Never throws.
+ *
+ * @param candidates - Candidate `.md` URLs to try, in order.
+ * @param options - Allowed host, injectable fetcher/timeout, and an optional body transform.
+ * @returns SiteFetchResult with `route_markdown` provenance, or null when no candidate validates.
+ */
+export declare function probeMarkdownTwin(candidates: string[], { allowedHost, fetcher, timeoutMs, headers, transformBody, }: MarkdownTwinOptions): Promise<SiteFetchResult | null>;

package/dist/sites/markdown-twin.js

@@ -0,0 +1,56 @@
+import { fetchText } from '../lib/research/fetcher.js';
+import { isValidatedMarkdownTwin } from '../lib/research/docs/validate.js';
+import { extractFromSource } from '../lib/research/docs/markdown-source.js';
+// Shared shape behind every site module's ".md twin" probe: try candidate URLs, validate the
+// response against the expected host, and — once the body clears the minimum-viable-article
+// length — package it into the SiteFetchResult shape createArtifactFromFetch expects. Two site
+// modules use this: developer.salesforce.com (one derived URL) and help.salesforce.com (two
+// category candidates on the b2c-developer-tooling mirror). `transformBody` covers the one place
+// they differ — Developer strips unresolvable `::include{…}` directives before extraction.
+const DEFAULT_PROBE_TIMEOUT_MS = 4_000;
+// A twin this thin reads as a rollout stub/placeholder rather than a real article.
+const MIN_TWIN_CHARS = 100;
+/**
+ * Probes candidate `.md`-twin URLs in order and returns the first that validates as a usable
+ * article, packaged as a SiteFetchResult with `route_markdown` provenance. Returns null when
+ * every candidate 404s, fails validation, or extracts thinner than the minimum viable article —
+ * callers fall back to their browser capture in that case. Never throws.
+ *
+ * @param candidates - Candidate `.md` URLs to try, in order.
+ * @param options - Allowed host, injectable fetcher/timeout, and an optional body transform.
+ * @returns SiteFetchResult with `route_markdown` provenance, or null when no candidate validates.
+ */
+export async function probeMarkdownTwin(candidates, { allowedHost, fetcher = fetchText, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS, headers, transformBody, }) {
+    for (const candidate of candidates) {
+        let res;
+        try {
+            res = await fetcher(candidate, { timeoutMs, headers });
+        }
+        catch {
+            continue;
+        }
+        if (!isValidatedMarkdownTwin(res, allowedHost))
+            continue;
+        const transformed = transformBody?.(res.content);
+        const extraction = extractFromSource(transformed?.body ?? res.content, res.finalUrl);
+        if (extraction.detailedMarkdown.length < MIN_TWIN_CHARS)
+            continue;
+        if (transformed?.qualityNote) {
+            extraction.qualityNotes = [...(extraction.qualityNotes ?? []), transformed.qualityNote];
+        }
+        return {
+            fetchResult: {
+                contentType: res.contentType,
+                etag: res.etag,
+                lastModified: res.lastModified,
+                finalUrl: res.finalUrl,
+                responseSize: res.responseSize,
+                content: res.content,
+            },
+            extraction,
+            captureMethod: 'route_markdown',
+            sourceDocUrl: res.finalUrl,
+        };
+    }
+    return null;
+}

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

@@ -1,6 +1,12 @@
 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.
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten to
+ * the canonical /s/articleView page first. The Salesforce B2C Developer Tooling project mirrors a
+ * curated set of B2C Commerce Help articles as static Markdown; that twin is probed next, and used
+ * when it validates. Otherwise the shared Lightning Web Runtime (LWR) fetcher renders the page.
+ *
+ * @param url - The help.salesforce.com article URL (or a Coveo /help_doccontent URL).
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export declare function fetchSalesforcePage(url: string): Promise<SiteFetchResult>;

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

@@ -1,5 +1,6 @@
 import { fetchSalesforceDoc } from '../salesforce-doc-fetch.js';
 import { normalizeHelpDocContentUrl } from '../coveo.js';
+import { fetchHelpToolingMarkdown } from './help-tooling-markdown.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 = [
@@ -13,11 +14,21 @@ const CONTENT_SELECTORS = [
     '.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.
+ * Fetches a help.salesforce.com article. Coveo's internal /help_doccontent URLs are rewritten to
+ * the canonical /s/articleView page first. The Salesforce B2C Developer Tooling project mirrors a
+ * curated set of B2C Commerce Help articles as static Markdown; that twin is probed next, and used
+ * when it validates. Otherwise the shared Lightning Web Runtime (LWR) fetcher renders the page.
+ *
+ * @param url - The help.salesforce.com article URL (or a Coveo /help_doccontent URL).
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export async function fetchSalesforcePage(url) {
-    return fetchSalesforceDoc(normalizeHelpDocContentUrl(url), {
+    const normalizedUrl = normalizeHelpDocContentUrl(url);
+    const fromToolingMirror = await fetchHelpToolingMarkdown(normalizedUrl);
+    if (fromToolingMirror)
+        return fromToolingMirror;
+    return fetchSalesforceDoc(normalizedUrl, {
         allowedHost: 'help.salesforce.com',
         contentSelectors: CONTENT_SELECTORS,
         removeSelectors: [

package/dist/sites/salesforce/help-tooling-markdown.d.ts

@@ -0,0 +1,30 @@
+import { fetchText } from '../../lib/research/fetcher.js';
+import type { SiteFetchResult } from '../types.js';
+/**
+ * Extracts the b2c-developer-tooling slug from a help.salesforce.com article URL, or null when the
+ * URL isn't a `cc.<slug>.htm` B2C Commerce Help article (wrong host, missing `id`, or an `id` that
+ * doesn't follow that pattern — e.g. numeric knowledge-article ids, or other clouds' Help content).
+ *
+ * @param url - A help.salesforce.com article URL (or any URL; non-matching returns null).
+ * @returns The derived slug (e.g. `b2c_inventory_list_object_import_export`), or null.
+ */
+export declare function deriveHelpToolingSlug(url: string): string | null;
+/**
+ * Builds the candidate mirror URLs for a slug, one per known category. Category membership isn't
+ * derivable from the URL, so callers must probe each until one validates.
+ *
+ * @param slug - Slug derived by {@link deriveHelpToolingSlug}.
+ * @returns Candidate `.md` URLs on the b2c-developer-tooling mirror, one per category.
+ */
+export declare function candidateHelpToolingUrls(slug: string): string[];
+/**
+ * Probes the b2c-developer-tooling Markdown mirror for a help.salesforce.com article. Returns a
+ * complete SiteFetchResult (with route_markdown provenance) for the first category whose twin
+ * validates, or null so the caller falls back to the browser capture. Never throws: any
+ * network/validation failure just means "no twin in this category," or "no twin at all."
+ *
+ * @param url - The help.salesforce.com article URL to probe.
+ * @param fetcher - HTTP fetcher (injectable for tests; defaults to `fetchText`).
+ * @returns SiteFetchResult with route_markdown provenance, or null when no valid twin is found.
+ */
+export declare function fetchHelpToolingMarkdown(url: string, fetcher?: typeof fetchText): Promise<SiteFetchResult | null>;

package/dist/sites/salesforce/help-tooling-markdown.js

@@ -0,0 +1,74 @@
+import { fetchText } from '../../lib/research/fetcher.js';
+import { probeMarkdownTwin } from '../markdown-twin.js';
+// Salesforce's official "B2C Developer Tooling" project (GA, SalesforceCommerceCloud org) mirrors
+// a curated subset of help.salesforce.com's B2C Commerce articles as static Markdown for its own
+// CLI/MCP `docs` tool: /help/<category>/<slug>.md on its GitHub Pages site. Two categories cover
+// admin- and merchant-facing content. Fetching that twin replaces Help's ~45s shadow-DOM render
+// with one static request — the same win developer.salesforce.com's route.md twin gives us.
+//
+// Unlike the developer.salesforce.com twin, the mirror lives on a DIFFERENT host than the article
+// (help.salesforce.com -> salesforcecommercecloud.github.io), and there is no public index mapping
+// a help.salesforce.com article to its slug/category: the mapping ships inside the b2c-developer-
+// tooling CLI's bundled package, not as a fetchable file. But B2C Commerce Help articles' `id` query
+// param follows a stable `cc.<slug>.htm` pattern that matches the mirror's slug exactly (verified
+// against several live articles spanning both categories), so the slug is derivable from the URL;
+// which of the two categories holds it is not, so both are probed (see probeMarkdownTwin).
+const HELP_HOST = 'help.salesforce.com';
+const TOOLING_HOST = 'salesforcecommercecloud.github.io';
+const TOOLING_HELP_BASE = `https://${TOOLING_HOST}/b2c-developer-tooling/help`;
+// Order doesn't reflect prevalence, just the two categories b2c-developer-tooling publishes.
+const HELP_TOOLING_CATEGORIES = ['help-admin', 'help-merchant'];
+// Every real B2C Commerce Help slug is lowercase word characters/underscores (e.g.
+// b2c_inventory_list_object_import_export); restricting the capture group to that charset (rather
+// than `.+`) keeps a crafted `id` query param from steering the mirror probe at an arbitrary path
+// on the trusted host.
+const HELP_ARTICLE_ID_PATTERN = /^cc\.([\w-]+)\.htm$/i;
+/**
+ * Extracts the b2c-developer-tooling slug from a help.salesforce.com article URL, or null when the
+ * URL isn't a `cc.<slug>.htm` B2C Commerce Help article (wrong host, missing `id`, or an `id` that
+ * doesn't follow that pattern — e.g. numeric knowledge-article ids, or other clouds' Help content).
+ *
+ * @param url - A help.salesforce.com article URL (or any URL; non-matching returns null).
+ * @returns The derived slug (e.g. `b2c_inventory_list_object_import_export`), or null.
+ */
+export function deriveHelpToolingSlug(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.hostname.toLowerCase() !== HELP_HOST)
+        return null;
+    const id = parsed.searchParams.get('id');
+    if (!id)
+        return null;
+    return HELP_ARTICLE_ID_PATTERN.exec(id)?.[1] ?? null;
+}
+/**
+ * Builds the candidate mirror URLs for a slug, one per known category. Category membership isn't
+ * derivable from the URL, so callers must probe each until one validates.
+ *
+ * @param slug - Slug derived by {@link deriveHelpToolingSlug}.
+ * @returns Candidate `.md` URLs on the b2c-developer-tooling mirror, one per category.
+ */
+export function candidateHelpToolingUrls(slug) {
+    return HELP_TOOLING_CATEGORIES.map((category) => `${TOOLING_HELP_BASE}/${category}/${slug}.md`);
+}
+/**
+ * Probes the b2c-developer-tooling Markdown mirror for a help.salesforce.com article. Returns a
+ * complete SiteFetchResult (with route_markdown provenance) for the first category whose twin
+ * validates, or null so the caller falls back to the browser capture. Never throws: any
+ * network/validation failure just means "no twin in this category," or "no twin at all."
+ *
+ * @param url - The help.salesforce.com article URL to probe.
+ * @param fetcher - HTTP fetcher (injectable for tests; defaults to `fetchText`).
+ * @returns SiteFetchResult with route_markdown provenance, or null when no valid twin is found.
+ */
+export async function fetchHelpToolingMarkdown(url, fetcher = fetchText) {
+    const slug = deriveHelpToolingSlug(url);
+    if (!slug)
+        return null;
+    return probeMarkdownTwin(candidateHelpToolingUrls(slug), { allowedHost: TOOLING_HOST, fetcher });
+}

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

@@ -1,2 +1,3 @@
 import type { SiteModule } from '../types.js';
+/** Site module for help.salesforce.com: forces rendered capture and applies the Help-specific Lightning Web Runtime (LWR) fetcher. */
 export declare const salesforce: SiteModule;

package/dist/sites/salesforce/index.js

@@ -2,6 +2,7 @@ import { fetchSalesforcePage } from './fetch-page.js';
 // Scoped to help.salesforce.com — an LWR Experience site with light-DOM article content.
 // 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.
+/** Site module for help.salesforce.com: forces rendered capture and applies the Help-specific Lightning Web Runtime (LWR) fetcher. */
 export const salesforce = {
     id: 'salesforce',
     name: 'Salesforce Help',

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

@@ -3,6 +3,11 @@ import type { SiteFetchResult } from '../types.js';
  * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
  * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
  * browser render, and it returns the article's source. Pages without a validated twin (API
- * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ * reference, atlas.* books, landing pages) fall back to the shared Lightning Web Runtime (LWR)
+ * shadow-DOM fetcher.
+ *
+ * @param url - The developer.salesforce.com doc page URL.
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export declare function fetchDeveloperPage(url: string): Promise<SiteFetchResult>;

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

@@ -16,7 +16,12 @@ const CONTENT_SELECTORS = [
  * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
  * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
  * browser render, and it returns the article's source. Pages without a validated twin (API
- * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ * reference, atlas.* books, landing pages) fall back to the shared Lightning Web Runtime (LWR)
+ * shadow-DOM fetcher.
+ *
+ * @param url - The developer.salesforce.com doc page URL.
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export async function fetchDeveloperPage(url) {
     const fromMarkdownRoute = await fetchDeveloperRouteMarkdown(url);

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

@@ -1,2 +1,3 @@
 import type { SiteModule } from '../types.js';
+/** Site module for developer.salesforce.com: forces rendered capture and applies the shadow-DOM Lightning Web Runtime (LWR) fetcher. */
 export declare const salesforceDeveloper: SiteModule;

package/dist/sites/salesforce-developer/index.js

@@ -2,6 +2,7 @@ import { fetchDeveloperPage } from './fetch-page.js';
 // developer.salesforce.com docs (guides + API reference) render client-side inside web
 // components, so content lives in shadow DOM — a fundamentally different extraction strategy
 // than help.salesforce.com (see ../salesforce).
+/** Site module for developer.salesforce.com: forces rendered capture and applies the shadow-DOM Lightning Web Runtime (LWR) fetcher. */
 export const salesforceDeveloper = {
     id: 'salesforce-developer',
     name: 'Salesforce Developer',

package/dist/sites/salesforce-developer/route-markdown.d.ts

@@ -1,23 +1,35 @@
-import { type FetchResult } from '../../lib/research/fetcher.js';
+import { fetchText } from '../../lib/research/fetcher.js';
 import type { SiteFetchResult } from '../types.js';
 /**
  * Derives the candidate `.md` route for a developer.salesforce.com doc URL, or null when the URL
  * can't serve one (wrong host, not under /docs/, or an atlas.* book — verified to answer `.md`
  * with an HTML shell, never Markdown). Query/hash are view state and are dropped.
+ *
+ * @param url - A developer.salesforce.com doc URL (or any URL; non-matching returns null).
+ * @returns The derived `.md` URL, or null when no `.md` route exists for this URL.
  */
 export declare function deriveMarkdownUrl(url: string): string | null;
-/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped. */
+/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped.
+ *
+ * @param md - Markdown body from the `.md` route response.
+ * @returns Cleaned body string and a count of removed directive lines.
+ */
 export declare function stripIncludeDirectives(md: string): {
     body: string;
     dropped: number;
 };
-export type RouteMarkdownFetcher = (url: string, options?: {
-    headers?: Record<string, string>;
-    timeoutMs?: number;
-}) => Promise<FetchResult>;
+/**
+ * Injectable HTTP fetcher used by `fetchDeveloperRouteMarkdown`. The default is `fetchText`;
+ * tests inject a fixture fetcher to avoid real network calls.
+ */
+export type RouteMarkdownFetcher = typeof fetchText;
 /**
  * Probes the derived `.md` route for a developer doc URL. Returns a complete SiteFetchResult
  * (with route_markdown provenance) when the twin validates, or null so the caller falls back to
  * the browser capture. Never throws: any network/validation failure is just "no twin".
+ *
+ * @param url - The developer.salesforce.com doc page URL to probe.
+ * @param fetcher - HTTP fetcher (injectable for tests; defaults to `fetchText`).
+ * @returns SiteFetchResult with route_markdown provenance, or null when no valid twin is found.
  */
 export declare function fetchDeveloperRouteMarkdown(url: string, fetcher?: RouteMarkdownFetcher): Promise<SiteFetchResult | null>;