@taurgis/bonsai 4.0.0 → 4.1.1

package/dist/lib/research/search-match.js

@@ -0,0 +1,134 @@
+/**
+ * Keyword scoring and snippet extraction for `search --query`. Matches only against fields already
+ * cheap to read from the search-index sidecar (topic, tags, summary, compressed) — see
+ * `artifact-index.ts` — so `search` never pays the cost of parsing the (often much larger)
+ * `detailed` body just to rank results.
+ */
+/** Per-term score contribution when it matches the artifact's topic. */
+const SCORE_WEIGHT_TOPIC = 100;
+/** Per matching tag, per term. */
+const SCORE_WEIGHT_TAG = 50;
+/** Per occurrence in `summary`, per term (capped by {@link SUMMARY_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_SUMMARY = 10;
+/** Per occurrence in `compressed`, per term (capped by {@link COMPRESSED_OCCURRENCE_CAP}). */
+const SCORE_WEIGHT_COMPRESSED = 2;
+// Repeated boilerplate (e.g. a term that happens to be a common word in a large compressed body)
+// must not let one field dominate the score just by occurring many times; capping occurrences
+// counted keeps the topic/tag weights meaningfully dominant regardless of body length.
+const SUMMARY_OCCURRENCE_CAP = 5;
+const COMPRESSED_OCCURRENCE_CAP = 10;
+/** Characters of original-case text kept on each side of a matched term in an excerpt. */
+const SNIPPET_CONTEXT_CHARS = 90;
+/** Field priority order for a deterministic `matchedFields` list, independent of term iteration order. */
+const FIELD_PRIORITY = ['topic', 'tags', 'summary', 'compressed'];
+/** Split a `--query` value into lowercase, deduplicated terms on whitespace. */
+export function tokenizeSearchQuery(query) {
+    const terms = query
+        .trim()
+        .split(/\s+/)
+        .map((term) => term.toLowerCase());
+    return [...new Set(terms)];
+}
+/**
+ * Reject a whitespace-only `--query` instead of silently matching nothing (an empty term list would
+ * either match every artifact or none, both surprising) — same reasoning as `--topic`/`--tags`/`--url`.
+ */
+export function emptySearchQueryError(query) {
+    if (query === undefined)
+        return undefined;
+    if (query.trim() === '') {
+        return '--query must be a non-empty value (e.g. "suspense boundary").';
+    }
+    return undefined;
+}
+/** Count non-overlapping occurrences of `needle` in `haystack` (both already lowercased). */
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let fromIndex = 0;
+    let index;
+    while ((index = haystack.indexOf(needle, fromIndex)) !== -1) {
+        count++;
+        fromIndex = index + needle.length;
+    }
+    return count;
+}
+/**
+ * Scores one artifact against tokenized query terms. Returns `null` when the artifact does not
+ * satisfy the match mode (every term must match somewhere, unless `matchAny` allows just one).
+ */
+export function scoreSearchMatch(fields, terms, matchAny) {
+    const topicLower = (fields.topic ?? '').toLowerCase();
+    const tagsLower = fields.tags.map((tag) => tag.toLowerCase());
+    const summaryLower = fields.summary.toLowerCase();
+    const compressedLower = fields.compressed.toLowerCase();
+    let score = 0;
+    let matchedTermCount = 0;
+    const matchedFieldSet = new Set();
+    for (const term of terms) {
+        let termMatched = false;
+        if (topicLower.includes(term)) {
+            score += SCORE_WEIGHT_TOPIC;
+            matchedFieldSet.add('topic');
+            termMatched = true;
+        }
+        const tagHits = tagsLower.filter((tag) => tag.includes(term)).length;
+        if (tagHits > 0) {
+            score += SCORE_WEIGHT_TAG * tagHits;
+            matchedFieldSet.add('tags');
+            termMatched = true;
+        }
+        const summaryHits = Math.min(countOccurrences(summaryLower, term), SUMMARY_OCCURRENCE_CAP);
+        if (summaryHits > 0) {
+            score += SCORE_WEIGHT_SUMMARY * summaryHits;
+            matchedFieldSet.add('summary');
+            termMatched = true;
+        }
+        const compressedHits = Math.min(countOccurrences(compressedLower, term), COMPRESSED_OCCURRENCE_CAP);
+        if (compressedHits > 0) {
+            score += SCORE_WEIGHT_COMPRESSED * compressedHits;
+            matchedFieldSet.add('compressed');
+            termMatched = true;
+        }
+        if (termMatched)
+            matchedTermCount++;
+    }
+    const satisfied = matchAny ? matchedTermCount > 0 : matchedTermCount === terms.length;
+    if (!satisfied)
+        return null;
+    return { score, matchedFields: FIELD_PRIORITY.filter((field) => matchedFieldSet.has(field)) };
+}
+/** Earliest (leftmost) occurrence of any term in already-lowercased `textLower`, or `null`. */
+function findEarliestMatch(textLower, terms) {
+    let best = null;
+    for (const term of terms) {
+        const index = textLower.indexOf(term);
+        if (index !== -1 && (best === null || index < best.index)) {
+            best = { index, length: term.length };
+        }
+    }
+    return best;
+}
+/** Windowed excerpt of `text` around `match`, collapsed to one line with ellipsis on truncation. */
+function buildSnippetWindow(text, match) {
+    const start = Math.max(0, match.index - SNIPPET_CONTEXT_CHARS);
+    const end = Math.min(text.length, match.index + match.length + SNIPPET_CONTEXT_CHARS);
+    const windowed = text.slice(start, end).replace(/\s+/g, ' ').trim();
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return `${prefix}${windowed}${suffix}`;
+}
+/**
+ * A short excerpt around the first query-term match in `compressed` (falling back to `summary`),
+ * so an agent can judge relevance from the token-cheap index alone before deciding to `inspect` or
+ * re-fetch the full page. Returns `null` when no term appears in either — e.g. the match was only
+ * against `topic`/`tags` — rather than an unrelated excerpt with no bearing on the query.
+ */
+export function extractSearchSnippet(fields, terms) {
+    const compressedMatch = findEarliestMatch(fields.compressed.toLowerCase(), terms);
+    if (compressedMatch)
+        return buildSnippetWindow(fields.compressed, compressedMatch);
+    const summaryMatch = findEarliestMatch(fields.summary.toLowerCase(), terms);
+    if (summaryMatch)
+        return buildSnippetWindow(fields.summary, summaryMatch);
+    return null;
+}

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

@@ -0,0 +1,19 @@
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export declare function scopeFlags(descriptions: {
+    global: string;
+    local: string;
+}): {
+    global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export declare function assertScopeFlagsExclusive(error: (message: string, options: {
+    exit: 2;
+    code: string;
+    suggestions: string[];
+}) => never, global: boolean | undefined, local: boolean | undefined): void;

package/dist/lib/scope-flags.js

@@ -0,0 +1,27 @@
+import { Flags } from '@oclif/core';
+/** Build the `--global`/`--local` scope-flag pair with per-command descriptions. */
+export function scopeFlags(descriptions) {
+    return {
+        global: Flags.boolean({ char: 'g', description: descriptions.global }),
+        local: Flags.boolean({
+            description: descriptions.local,
+            aliases: ['project'],
+            charAliases: ['p'],
+        }),
+    };
+}
+/**
+ * Rejects `--global`/`--local` passed together. Shared by every command with this scope-flag pair
+ * (`config`, `setup`) so the guard, its message, and its error code can't drift between them.
+ *
+ * @param error - The command's own `this.error`, bound by the caller (it always throws, hence `never`).
+ */
+export function assertScopeFlagsExclusive(error, global, local) {
+    if (global && local) {
+        error('--global and --local are mutually exclusive.', {
+            exit: 2,
+            code: 'CONFLICTING_FLAGS',
+            suggestions: ['Pass --global or --local, not both.'],
+        });
+    }
+}

package/dist/lib/setup/agents.d.ts

@@ -0,0 +1,16 @@
+import type { SetupAgent } from '../cli-result-types.js';
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export declare const SETUP_AGENTS: readonly SetupAgent[];
+/** Where a SessionStart hook lives for one agent, and how Bonsai's entry is shaped. */
+export interface SetupAgentTarget {
+    /** Hook-config file path, relative to the project root or the user's home directory. */
+    relativePath: string;
+    eventName: string;
+    matcher: string;
+    timeout: number;
+}
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export declare const SETUP_HOOK_COMMAND_SUFFIX = "context";
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export declare const SETUP_HOOK_MANAGED_BY = "bonsai";
+export declare const SETUP_AGENT_TARGETS: Record<SetupAgent, SetupAgentTarget>;

package/dist/lib/setup/agents.js

@@ -0,0 +1,20 @@
+/** Every agent `setup` currently knows how to install a SessionStart hook for. */
+export const SETUP_AGENTS = ['claude-code', 'codex'];
+// Both agents accept plain stdout as SessionStart context and share the same `source` matcher
+// values (startup/resume/clear/compact) — see the cached docs at
+// developers.openai.com/codex/hooks#sessionstart (.bonsai/research/4f69debe...) and
+// code.claude.com/docs/en/hooks (.bonsai/research/20106b0f3bee09dd540039d6a1a5294fbfbe0ae0b182affd4138cf3caa31e0c6.md,
+// imported rather than fetched — Bonsai's own fetch times out on this host in this environment).
+const SESSION_START = {
+    eventName: 'SessionStart',
+    matcher: 'startup|resume|clear|compact',
+    timeout: 10,
+};
+/** Subcommand `setup` invokes at session start; appended to the resolved bin command. */
+export const SETUP_HOOK_COMMAND_SUFFIX = 'context';
+/** Tag value stamped on every handler `setup` installs — see {@link SessionStartHookSpec.managedBy}. */
+export const SETUP_HOOK_MANAGED_BY = 'bonsai';
+export const SETUP_AGENT_TARGETS = {
+    'claude-code': { ...SESSION_START, relativePath: '.claude/settings.json' },
+    codex: { ...SESSION_START, relativePath: '.codex/hooks.json' },
+};

package/dist/lib/setup/bin-command.d.ts

@@ -0,0 +1,14 @@
+/** `which`/`where` lookup for a command name; `null` when not found on `PATH`. */
+export declare function findOnPath(command: string): string | null;
+/**
+ * Resolves the command a hook config should invoke to run this CLI (AXI rule: "hook commands
+ * should use a PATH-verified binary name when it resolves to the current executable, and fall
+ * back to the full absolute path otherwise"). This keeps a global install portable across
+ * machines while guaranteeing a hook never silently runs a different `bonsai` than the one that
+ * installed it.
+ *
+ * @param scriptPath - The currently running script (`process.argv[1]`).
+ * @param lookup - `PATH` lookup, injectable for tests.
+ * @returns `"bonsai"` when `PATH` resolves to this same script, otherwise `node "<absolute path>"`.
+ */
+export declare function resolveBinCommand(scriptPath: string, lookup?: typeof findOnPath): string;

package/dist/lib/setup/bin-command.js

@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+/** `which`/`where` lookup for a command name; `null` when not found on `PATH`. */
+export function findOnPath(command) {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const output = execFileSync(finder, [command], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // `where` on Windows can print multiple matches, one per line; the first is the one PATH resolves to.
+        return output.split(/\r?\n/).find((line) => line.trim() !== '') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the command a hook config should invoke to run this CLI (AXI rule: "hook commands
+ * should use a PATH-verified binary name when it resolves to the current executable, and fall
+ * back to the full absolute path otherwise"). This keeps a global install portable across
+ * machines while guaranteeing a hook never silently runs a different `bonsai` than the one that
+ * installed it.
+ *
+ * @param scriptPath - The currently running script (`process.argv[1]`).
+ * @param lookup - `PATH` lookup, injectable for tests.
+ * @returns `"bonsai"` when `PATH` resolves to this same script, otherwise `node "<absolute path>"`.
+ */
+export function resolveBinCommand(scriptPath, lookup = findOnPath) {
+    const realScript = realpathSync(scriptPath);
+    const onPath = lookup('bonsai');
+    if (onPath) {
+        try {
+            if (realpathSync(onPath) === realScript)
+                return 'bonsai';
+        }
+        catch {
+            // onPath didn't resolve to a real file (stale PATH entry) — fall through to the absolute path.
+        }
+    }
+    return `node "${realScript}"`;
+}

package/dist/lib/setup/hook-file-io.d.ts

@@ -0,0 +1,37 @@
+/** The SessionStart hook Bonsai wants installed. */
+export interface SessionStartHookSpec {
+    /** Hook event name, e.g. `"SessionStart"`. */
+    eventName: string;
+    matcher: string;
+    /** Full command to run (already resolved to a PATH-verified name or absolute path). */
+    command: string;
+    timeout: number;
+    /**
+     * Tag stamped on the installed handler (e.g. `"bonsai"`) so a later run can find *this exact*
+     * entry to repair or leave alone, without guessing from `command` text — a user's own hook could
+     * otherwise end in the same word Bonsai's command does (e.g. a wrapped `... && bonsai context`)
+     * and get silently claimed and overwritten.
+     */
+    managedBy: string;
+}
+/** Outcome of planning a hook-file install: what changed, and the file content to persist. */
+export interface HookInstallPlan {
+    status: 'installed' | 'repaired' | 'unchanged';
+    content: string;
+}
+/** Thrown when an existing hook file can't be safely merged into (not JSON, or not an object). */
+export declare class InvalidHookFileError extends Error {
+}
+/**
+ * Plans installing or repairing a Bonsai-managed `SessionStart` hook entry inside an existing (or
+ * not-yet-created) hook-config file, without touching any other hooks already in that file (AXI
+ * rules: explicit opt-in install, path repair, idempotent). Pure — callers own reading the
+ * existing file and persisting `content` (see `setup.ts`).
+ *
+ * - No existing Bonsai entry for this event → append a new matcher group (`installed`).
+ * - An existing Bonsai entry with a stale `command` → update it in place (`repaired`).
+ * - An existing Bonsai entry with the same `command` → no-op, original bytes returned (`unchanged`).
+ *
+ * @throws {InvalidHookFileError} When `existingContent` isn't a mergeable JSON object.
+ */
+export declare function planSessionStartHookInstall(existingContent: string | null, spec: SessionStartHookSpec): HookInstallPlan;

package/dist/lib/setup/hook-file-io.js

@@ -0,0 +1,80 @@
+/** Thrown when an existing hook file can't be safely merged into (not JSON, or not an object). */
+export class InvalidHookFileError extends Error {
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isBonsaiHandler(handler, managedBy) {
+    return isPlainObject(handler) && handler.managedBy === managedBy;
+}
+function serialize(root) {
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/**
+ * Parses an existing hook-file's content into its root JSON object, or `{}` when the file doesn't
+ * exist yet. Deliberately refuses (rather than silently discarding) content that isn't a JSON
+ * object — the file may carry a user's own unrelated hooks, and Bonsai must never clobber content
+ * it can't understand.
+ *
+ * @throws {InvalidHookFileError} When `existingContent` is set but isn't a JSON object.
+ */
+function parseHookFileRoot(existingContent) {
+    if (existingContent === null || existingContent.trim() === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(existingContent);
+    }
+    catch (err) {
+        throw new InvalidHookFileError(`not valid JSON: ${err.message}`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new InvalidHookFileError('expected a JSON object at the top level');
+    }
+    return parsed;
+}
+/**
+ * Plans installing or repairing a Bonsai-managed `SessionStart` hook entry inside an existing (or
+ * not-yet-created) hook-config file, without touching any other hooks already in that file (AXI
+ * rules: explicit opt-in install, path repair, idempotent). Pure — callers own reading the
+ * existing file and persisting `content` (see `setup.ts`).
+ *
+ * - No existing Bonsai entry for this event → append a new matcher group (`installed`).
+ * - An existing Bonsai entry with a stale `command` → update it in place (`repaired`).
+ * - An existing Bonsai entry with the same `command` → no-op, original bytes returned (`unchanged`).
+ *
+ * @throws {InvalidHookFileError} When `existingContent` isn't a mergeable JSON object.
+ */
+export function planSessionStartHookInstall(existingContent, spec) {
+    const root = parseHookFileRoot(existingContent);
+    const hooks = isPlainObject(root.hooks) ? { ...root.hooks } : {};
+    const eventGroups = Array.isArray(hooks[spec.eventName])
+        ? [...hooks[spec.eventName]]
+        : [];
+    for (const group of eventGroups) {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            continue;
+        const index = group.hooks.findIndex((handler) => isBonsaiHandler(handler, spec.managedBy));
+        if (index === -1)
+            continue;
+        const existingHandler = group.hooks[index];
+        if (existingHandler.command === spec.command) {
+            // Byte-identical no-op: return the original content rather than a reserialized copy, so a
+            // repeated install never churns the file's formatting.
+            return { status: 'unchanged', content: existingContent ?? serialize(root) };
+        }
+        group.hooks[index] = { ...existingHandler, command: spec.command };
+        hooks[spec.eventName] = eventGroups;
+        root.hooks = hooks;
+        return { status: 'repaired', content: serialize(root) };
+    }
+    eventGroups.push({
+        matcher: spec.matcher,
+        hooks: [
+            { type: 'command', command: spec.command, timeout: spec.timeout, managedBy: spec.managedBy },
+        ],
+    });
+    hooks[spec.eventName] = eventGroups;
+    root.hooks = hooks;
+    return { status: 'installed', content: serialize(root) };
+}

package/dist/lib/text.d.ts

@@ -1,5 +1,11 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export declare const NO_TOPIC_LABEL = "(no topic)";
+/**
+ * Collapse a leading home-directory prefix to `~`, matching how shells and tools like `git`
+ * display paths. Used for the home-view "bin:" identity line (AXI principle 10) so the executable
+ * path stays readable instead of a long absolute path.
+ */
+export declare function collapseHomeDir(path: string, homeDir: string): string;
 export declare const CONTROL_CHAR_PATTERN: RegExp;
 /**
  * Strip ANSI escape codes and other control characters from a cached metadata string before it

package/dist/lib/text.js

@@ -1,5 +1,16 @@
 /** Display label when an artifact has no topic — not a filterable topic value. */
 export const NO_TOPIC_LABEL = '(no topic)';
+/**
+ * Collapse a leading home-directory prefix to `~`, matching how shells and tools like `git`
+ * display paths. Used for the home-view "bin:" identity line (AXI principle 10) so the executable
+ * path stays readable instead of a long absolute path.
+ */
+export function collapseHomeDir(path, homeDir) {
+    if (homeDir && (path === homeDir || path.startsWith(`${homeDir}/`))) {
+        return `~${path.slice(homeDir.length)}`;
+    }
+    return path;
+}
 // 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

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

@@ -11,4 +11,6 @@ type FlagDef = {
  * cannot drift from the real command surface.
  */
 export declare function valueTakingFlagTokensFromCommands(commands: Record<string, typeof Command>, extraBaseFlags?: Record<string, FlagDef>): Set<string>;
+/** Same token set, read from a generated oclif manifest instead of command classes. */
+export declare function valueTakingFlagTokensFromFlagMaps(flagMaps: Array<Record<string, FlagDef> | undefined>): Set<string>;
 export {};

package/dist/lib/value-flags.js

@@ -14,10 +14,18 @@ function flagTokens(name, flag) {
  * cannot drift from the real command surface.
  */
 export function valueTakingFlagTokensFromCommands(commands, extraBaseFlags = {}) {
+    const maps = Object.values(commands).map((command) => ({
+        ...extraBaseFlags,
+        ...command.baseFlags,
+        ...command.flags,
+    }));
+    return valueTakingFlagTokensFromFlagMaps(maps);
+}
+/** Same token set, read from a generated oclif manifest instead of command classes. */
+export function valueTakingFlagTokensFromFlagMaps(flagMaps) {
     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)) {
+    for (const flags of flagMaps) {
+        for (const [name, flag] of Object.entries(flags ?? {})) {
             if (!flag || flag.type === 'boolean')
                 continue;
             for (const token of flagTokens(name, flag))

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

@@ -3,7 +3,7 @@ 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 Lightning Web Runtime (LWR)
+ * reference, atlas books whose `.md` route is still an HTML shell, landing pages) fall back to the shared Lightning Web Runtime (LWR)
  * shadow-DOM fetcher.
  *
  * @param url - The developer.salesforce.com doc page URL.

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

@@ -5,7 +5,9 @@ import { fetchDeveloperRouteMarkdown } from './route-markdown.js';
 const CONTENT_SELECTORS = [
     // API-reference pages: doc-amf-reference holds the method/type tables. doc-content-layout only
     // carries the shared deprecation banner and must not win selector priority on those pages.
+    // doc-redoc-reference is the Connect REST (B2B Commerce and platform) three-panel host.
     'doc-amf-reference',
+    'doc-redoc-reference',
     'doc-content-layout',
     '.markdown-content',
     'main article',
@@ -16,7 +18,7 @@ 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 Lightning Web Runtime (LWR)
+ * reference, atlas books whose `.md` route is still an HTML shell, landing pages) fall back to the shared Lightning Web Runtime (LWR)
  * shadow-DOM fetcher.
  *
  * @param url - The developer.salesforce.com doc page URL.

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

@@ -2,8 +2,9 @@ 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.
+ * can't serve one (wrong host, or not under /docs/). Atlas books are included: a shell is
+ * rejected later by content-type, and a redirect to Markdown is kept. 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.

package/dist/sites/salesforce-developer/route-markdown.js

@@ -7,9 +7,10 @@ import { probeMarkdownTwin } from '../markdown-twin.js';
 // shadow-DOM render and returns the article's actual source (code fences, admonitions intact).
 //
 // Coverage is rolling out per doc set, so the probe result is only a candidate (T-19/T-24):
-// unsupported articles 404, and atlas.* books answer the .md route with an HTTP 200 HTML SPA
-// shell — which makes the strict content-type + body validation in probeMarkdownTwin
-// load-bearing, not defensive garnish.
+// unsupported articles 404, and some atlas.* books still answer the .md route with an HTTP 200
+// HTML SPA shell. Others (REST API, Bulk API's successor) now redirect that same .md route to a
+// real text/markdown article under /docs/platform. Content-type validation rejects the shells;
+// skipping atlas.* up front would miss the books that moved.
 const DEVELOPER_HOST = 'developer.salesforce.com';
 // Salesforce's WAF answers 403 unless the User-Agent LEADS with a recognized HTTP-tool token
 // (curl/wget/python-requests pass; bare product names and browser UAs on a non-browser TLS stack
@@ -20,8 +21,9 @@ const PROBE_HEADERS = {
 };
 /**
  * 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.
+ * can't serve one (wrong host, or not under /docs/). Atlas books are included: a shell is
+ * rejected later by content-type, and a redirect to Markdown is kept. 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.
@@ -37,7 +39,7 @@ export function deriveMarkdownUrl(url) {
     if (parsed.hostname.toLowerCase() !== DEVELOPER_HOST)
         return null;
     let path = parsed.pathname.replace(/\/+$/, '');
-    if (!path.startsWith('/docs/') || path.startsWith('/docs/atlas.'))
+    if (!path.startsWith('/docs/'))
         return null;
     if (path.endsWith('.md'))
         return `https://${DEVELOPER_HOST}${path}`;

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

@@ -1,16 +1,12 @@
 import type { SiteFetchResult } from './types.js';
-/** True when the extracted text is an error/not-found/loading shell rather than real content.
- *
- * @param text - Extracted Markdown text to check.
- * @returns True when the text matches a Salesforce error/not-found pattern.
- */
-export declare function looksLikeSalesforceError(text: string): boolean;
+import { looksLikeSalesforceError } from './salesforce-dom-probe.js';
+export { looksLikeSalesforceError };
 /**
- * Removes known boilerplate lines from converted Salesforce Markdown: the feedback widget text,
- * "View as Markdown" toolbar labels, and empty icon-anchor lines.
+ * Removes known boilerplate from converted Salesforce Markdown: the feedback widget, doc-chrome
+ * toolbar labels, the atlas release switcher, and empty icon-anchor lines.
  *
  * @param markdown - Markdown output from the DOM or content API conversion.
- * @returns Markdown with boilerplate lines stripped and excess blank lines collapsed.
+ * @returns Markdown with boilerplate stripped and excess blank lines collapsed.
  */
 export declare function stripBoilerplate(markdown: string): string;
 /** Parses the Salesforce private content API JSON payload.
@@ -45,6 +41,21 @@ export interface SalesforceDocOptions {
     contentSelectors: string[];
     removeSelectors?: string[];
 }
+/** Article identity for a Salesforce doc URL: Help `id`, otherwise the last path segment.
+ * Underscores and hyphens match so a REST rename (`intro_what_is_rest_api` →
+ * `intro-what-is-rest-api`) stays the same article.
+ *
+ * @param url - Requested or post-navigation URL.
+ * @returns Normalized article key, or null when the URL has no article identity.
+ */
+export declare function salesforceArticleKey(url: string): string | null;
+/** True when both URLs name the same Salesforce article, or either key can't be read.
+ *
+ * @param requested - URL the caller asked for.
+ * @param finalUrl - URL the browser landed on.
+ * @returns False only when both keys exist and differ.
+ */
+export declare function sameSalesforceArticle(requested: string, finalUrl: string): boolean;
 /**
  * Renders a Salesforce Lightning Web Runtime (LWR) doc page, serializes its shadow-DOM content
  * container, and converts it to Markdown. Validates the host before any network access.
@@ -53,7 +64,8 @@ export interface SalesforceDocOptions {
  * @param options - Allowed host, priority content selectors, and optional per-site remove selectors.
  * @returns Extracted Markdown, fetch metadata, and browser-capture provenance.
  * @throws {Error} When the URL is invalid, the host is not the allowed host, DNS is unsafe,
- *   Chrome/CDP navigation or evaluation fails, the response body exceeds the size limit,
- *   or the captured content is too short / looks like an error page.
+ *   the document itself is HTTP 404/410, Chrome/CDP navigation or evaluation fails, the page
+ *   redirects to a different article, the response body exceeds the size limit, or the captured
+ *   content is too short / looks like an error page.
  */
 export declare function fetchSalesforceDoc(url: string, { allowedHost, contentSelectors, removeSelectors }: SalesforceDocOptions): Promise<SiteFetchResult>;