explorbot 0.4.4 → 0.4.6

package/dist/src/ai/scout/tools.js

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tool } from 'ai';
+import { createBashTool } from 'bash-tool';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { ConfigParser } from "../../config.js";
+import { tag } from "../../utils/logger.js";
+import { loadMarkdownFiles } from "../../utils/markdown-files.js";
+import { readCaptainFile } from "../captain/file-tools.js";
+const MAX_FILES = 500;
+const MAX_FINDINGS = 6000;
+let cachedScanner = null;
+export function loadScoutCorpus(dirs) {
+    const files = [];
+    for (const dir of dirs) {
+        if (files.length >= MAX_FILES) {
+            tag('warning').log(`Scout corpus capped at ${MAX_FILES} files — remaining directories skipped`);
+            break;
+        }
+        for (const file of loadMarkdownFiles(dir, { recursive: true })) {
+            if (files.length >= MAX_FILES)
+                break;
+            const entry = { path: file.filePath };
+            if (typeof file.data.url === 'string')
+                entry.url = file.data.url;
+            files.push(entry);
+        }
+    }
+    return { dirs, files, excludedPaths: [] };
+}
+export function excludeCorpusUrls(corpus, urls) {
+    if (urls.length === 0)
+        return corpus;
+    const excludedUrls = new Set(urls);
+    const files = [];
+    const excludedPaths = [...corpus.excludedPaths];
+    for (const file of corpus.files) {
+        if (file.url && excludedUrls.has(file.url)) {
+            excludedPaths.push(file.path);
+            continue;
+        }
+        files.push(file);
+    }
+    return { dirs: corpus.dirs, files, excludedPaths };
+}
+export async function createScoutTools(corpus) {
+    const scanner = await detectScanner();
+    const projectRoot = ConfigParser.getInstance().getProjectRoot();
+    let result = '';
+    let searchedOrRead = false;
+    const getResult = () => result;
+    const finishFromText = (text) => {
+        if (text && searchedOrRead)
+            result = text.slice(0, MAX_FINDINGS);
+    };
+    const files = {};
+    const readableFiles = new Set();
+    for (const file of corpus.files) {
+        files[toPosix(file.path)] = readFileSync(file.path, 'utf8');
+        readableFiles.add(resolve(file.path));
+    }
+    const toolkit = await createBashTool({
+        destination: '/',
+        files,
+        maxOutputLength: 20000,
+    });
+    const bashExecute = toolkit.bash.execute;
+    const bash = {
+        ...toolkit.bash,
+        execute: async (input) => {
+            tag('step').log(`Scout: bash ${input.command}`);
+            searchedOrRead = true;
+            return bashExecute?.(input);
+        },
+    };
+    const tools = {
+        bash,
+        readFile: tool({
+            description: dedent `
+        Read one documentation file from the corpus.
+        Pass the exact path returned by a search result.
+      `,
+            inputSchema: z.object({
+                path: z.string().describe('File path from a search result'),
+                startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+                endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+                maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+            }),
+            execute: async (input) => {
+                tag('step').log(`Scout: read ${input.path}`);
+                const output = readCaptainFile(projectRoot, input, corpus.dirs);
+                if (!output.success)
+                    return output;
+                const resolvedPath = resolve(projectRoot || process.cwd(), output.path);
+                if (!readableFiles.has(resolvedPath)) {
+                    return { success: false, message: 'File is outside the Scout corpus' };
+                }
+                searchedOrRead = true;
+                return output;
+            },
+        }),
+    };
+    return { tools, scanner, getResult, finishFromText };
+}
+async function detectScanner() {
+    if (cachedScanner)
+        return cachedScanner;
+    if (await binaryRuns('rg')) {
+        cachedScanner = 'rg';
+        return cachedScanner;
+    }
+    if (await binaryRuns('grep')) {
+        cachedScanner = 'grep';
+        return cachedScanner;
+    }
+    throw new Error('Scout requires ripgrep or grep on PATH — neither was found');
+}
+async function binaryRuns(binary) {
+    try {
+        const proc = Bun.spawn([binary, '--version'], { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+        return (await proc.exited) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}

package/dist/src/ai/scout.d.ts

@@ -0,0 +1,21 @@
+import type { Agent } from './agent.js';
+import type { Provider } from './provider.js';
+import { type ScoutCorpus } from './scout/tools.js';
+export declare class Scout implements Agent {
+    provider: Provider;
+    corpus: ScoutCorpus;
+    emoji: string;
+    cache: Map<string, string>;
+    constructor(provider: Provider, corpus: ScoutCorpus);
+    isAvailable(): boolean;
+    collectDocs(query: ScoutQuery): Promise<string>;
+    runSession(corpus: ScoutCorpus, query: ScoutQuery): Promise<string | null>;
+    buildSystemPrompt(toolNames: string[], corpus: ScoutCorpus, query: ScoutQuery, scanner: 'rg' | 'grep'): string;
+    buildTaskPrompt(query: ScoutQuery): string;
+}
+export interface ScoutQuery {
+    url?: string;
+    title?: string;
+    feature?: string;
+    excludeUrls: string[];
+}

package/dist/src/ai/scout.js

@@ -0,0 +1,150 @@
+import dedent from 'dedent';
+import { tag } from "../utils/logger.js";
+import { loop } from "../utils/loop.js";
+import { createScoutTools, excludeCorpusUrls } from "./scout/tools.js";
+const MAX_ITERATIONS = 3;
+const MAX_TOOL_ROUNDTRIPS = 5;
+const CACHE_LIMIT = 40;
+const URL_LISTING_LIMIT = 40;
+export class Scout {
+    provider;
+    corpus;
+    emoji = '🔎';
+    cache = new Map();
+    constructor(provider, corpus) {
+        this.provider = provider;
+        this.corpus = corpus;
+    }
+    isAvailable() {
+        return this.corpus.files.length > 0;
+    }
+    async collectDocs(query) {
+        if (!this.isAvailable())
+            return '';
+        const cacheKey = `${query.url || ''}|${query.feature || ''}|${query.excludeUrls.join(',')}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const corpus = excludeCorpusUrls(this.corpus, query.excludeUrls);
+        if (corpus.files.length === 0)
+            return '';
+        const result = await this.runSession(corpus, query);
+        if (result === null)
+            return '';
+        if (this.cache.size > CACHE_LIMIT)
+            this.cache.clear();
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+    async runSession(corpus, query) {
+        const { tools, scanner, getResult, finishFromText } = await createScoutTools(corpus);
+        const conversation = this.provider.startConversation(this.buildSystemPrompt(Object.keys(tools), corpus, query, scanner), 'scout', this.provider.getAgenticModel('scout'));
+        conversation.addUserText(this.buildTaskPrompt(query));
+        tag('info').log(`Scout: collecting documentation for ${query.feature || query.url || 'the current page'}`);
+        let failed = false;
+        await loop(async ({ stop, iteration }) => {
+            const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+                maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+                agentName: 'scout',
+            });
+            if (!invokeResult?.toolExecutions?.length) {
+                finishFromText(invokeResult?.response?.text);
+                stop();
+                return;
+            }
+            if (iteration >= MAX_ITERATIONS) {
+                const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
+                finishFromText(final?.response?.text);
+                stop();
+            }
+        }, {
+            maxAttempts: MAX_ITERATIONS,
+            observability: { name: `scout: ${query.feature || query.url || 'docs'}`, agent: 'scout' },
+            catch: async ({ error, stop }) => {
+                failed = true;
+                tag('warning').log(`Scout error: ${error.message}`);
+                stop();
+            },
+        });
+        if (failed)
+            return null;
+        const digest = getResult();
+        if (digest) {
+            const preview = digest.slice(0, 600);
+            const ellipsis = digest.length > 600 ? '…' : '';
+            tag('info').log(`Scout digest:\n${preview}${ellipsis}`);
+        }
+        return digest;
+    }
+    buildSystemPrompt(toolNames, corpus, query, scanner) {
+        const urls = corpus.files.map((file) => file.url).filter(Boolean);
+        const urlless = corpus.files.filter((file) => !file.url);
+        let pagesListing = '';
+        if (urls.length > 0) {
+            const listing = urls
+                .slice(0, URL_LISTING_LIMIT)
+                .map((url) => `- ${url}`)
+                .join('\n');
+            pagesListing = `Documented pages:\n${listing}`;
+            const remaining = urls.length - URL_LISTING_LIMIT;
+            if (remaining > 0)
+                pagesListing += `\n…and ${remaining} more — find them with ${scanner}`;
+        }
+        if (urlless.length > 0) {
+            const listing = urlless
+                .slice(0, URL_LISTING_LIMIT)
+                .map((file) => `- ${toPosix(file.path)}`)
+                .join('\n');
+            pagesListing += `\nFiles with no page URL (hand-written docs):\n${listing}`;
+        }
+        const prompt = dedent `
+      You are Scout — a documentation retrieval agent. You find collected documentation relevant to a testing focus and report it for test planning.
+
+      You never see the application itself. The documentation corpus is your only source of truth.
+
+      CORPUS:
+      ${corpus.files.length} markdown files under:
+      - ${corpus.dirs.map(toPosix).join('\n- ')}
+      ${pagesListing}
+
+      These pages are already provided to the planner in full — do not re-report them:
+      ${query.excludeUrls.map((url) => `- ${url}`).join('\n') || '- none'}
+
+      AVAILABLE TOOLS:
+      ${toolNames.join(', ')}.
+      Use tool names exactly as listed. Do not invent aliases or combined names.
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
+
+      SCANNER:
+      ${scanner} is the search command. Scan the working directory through bash() — explore freely, pipelines, globs and repeated searches are fine. Read files with readFile().
+
+      WORKFLOW:
+      1. Scan with ${scanner} using plain prose words from the focus — feature names, page purposes, capabilities
+      2. Read the files whose hits look most relevant
+      3. Report the digest as your final message — no tool call is needed to finish
+
+      RULES:
+      - Report only what the documentation states. Never fill gaps with assumptions about the application
+      - Keep verified capabilities and unverified possibilities distinguishable, the way the documentation marks them
+      - Name the page URL each item belongs to, so scenarios anchor to real routes
+      - Explore briefly: a few scans and reads are enough, then report
+      - A short accurate digest beats a long loose one; reporting that nothing relevant exists is a valid answer
+    `;
+        const customPrompt = this.provider.getSystemPromptForAgent('scout');
+        if (customPrompt)
+            return `${prompt}\n\n${customPrompt}`;
+        return prompt;
+    }
+    buildTaskPrompt(query) {
+        return dedent `
+      Page URL: ${query.url || 'Unknown'}
+      Page title: ${query.title || 'Unknown'}
+      Focus: ${query.feature || 'the page as a whole'}
+
+      Report the documented capabilities, states and transitions a test planner could turn into scenarios.
+    `;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}

package/dist/src/ai/tools.d.ts

@@ -1,5 +1,5 @@
-import type { ExecutedStep } from '../action.js';
 import { ActionResult, type PageDiff } from '../action-result.js';
+import type { ExecutedStep } from '../action.js';
 import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
 import type { ToolDeps } from './agent.js';

package/dist/src/ai/tools.js

@@ -5,12 +5,13 @@ import { ActionResult } from "../action-result.js";
 import { renderExperienceRecipes } from "../experience-tracker.js";
 import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
@@ -52,7 +53,6 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
-          5. I.clickXY(x, y) - coordinates fallback
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
@@ -63,10 +63,18 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('click', 'No commands provided');
                 }
-                const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
+                const trimmedCommands = rawCommands.map((cmd) => cmd.trim());
+                const coordinateCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.clickXY'));
+                if (coordinateCommands.length > 0) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('click', `Coordinate commands are not locators: ${coordinateCommands.join(', ')}. A coordinate click always runs, so it cannot tell you whether the element was there.`, {
+                        suggestion: 'Name the element instead. Use visualClick() when you can see the target but cannot address it, or form() for a deliberate coordinate click such as dismissing a layer.',
+                    });
+                }
+                const invalidCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
                 if (invalidCommands.length > 0) {
                     activeNote.commit(TestResult.FAILED);
-                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() or I.clickXY() commands.`, {
+                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() commands.`, {
                         suggestion: 'Use form() tool for typing text or multiple actions, or exitIframe() to leave iframe context.',
                     });
                 }
@@ -91,8 +99,23 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                         ambiguityError = action.lastError;
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
+                        if (!hasObservablePageChange(toolResult)) {
+                            activeNote.commit(TestResult.FAILED);
+                            return failedToolResult('click', 'Click executed, but no observable page change was captured.', {
+                                ...toolResult,
+                                attempts,
+                                code: command,
+                                suggestion: 'Treat the element as not clicked. It may be covered by another layer, disabled, or the locator may have matched a non-interactive ancestor. Re-locate via xpathCheck(), which reports whether the element is covered or offscreen, before retrying.',
+                            });
+                        }
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                        return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+                        const data = { ...toolResult, attempts, code: command };
+                        const notExecuted = commands.slice(i + 1);
+                        if (notExecuted.length) {
+                            data.notExecuted = notExecuted;
+                            data.suggestion = `SKIPPED: ${notExecuted.join('; ')}`;
+                        }
+                        return successToolResult('click', data, action);
                     }
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
@@ -385,10 +408,16 @@ export function createRefTools({ explorer, stateManager }, task) {
             }),
             execute: async ({ ref, element }) => {
                 const activeNote = task.startNote(`Click ${element}`);
+                if (await refIsGone(explorer, ref)) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} names no element on the page any more.`, {
+                        suggestion: 'The page has been rebuilt since you were given that ref. Call context() and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const named = await describeRef(explorer, ref);
-                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
                 if (!(await action.attempt(run, `Click ${element}`))) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
@@ -1015,17 +1044,6 @@ export async function commitNote(activeNote, result, toolResult, action) {
     }
     activeNote.commit(result);
 }
-async function describeRef(explorer, ref) {
-    return Promise.resolve(explorer?.withPage?.((page) => page.locator(`aria-ref=${ref}`).evaluate((el) => {
-        const tag = el.tagName.toLowerCase();
-        const roles = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
-        const role = el.getAttribute('role') || roles[tag] || tag;
-        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
-        if (!text)
-            return null;
-        return { role, text };
-    }))).catch(() => null);
-}
 async function hasFocusedElement(explorer) {
     return explorer.withPage((page) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
 }
@@ -1085,6 +1103,8 @@ function hasObservablePageChange(data) {
         return true;
     if (data.pageDiff.messages?.length)
         return true;
+    if (data.pageDiff.requests?.length)
+        return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 export async function failedToolResult(action, message, data, error) {
@@ -1093,12 +1113,11 @@ export async function failedToolResult(action, message, data, error) {
         result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
     }
     const errorTexts = [message, ...(data?.attempts?.map((a) => a.error || '') || [])];
-    const hasMultipleElements = errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN));
-    const multipleElementsSuggestion = hasMultipleElements ? getMultipleElementsSuggestion() : null;
-    if (multipleElementsSuggestion) {
-        result.suggestion = multipleElementsSuggestion;
+    if (errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
+        const matched = await extractWebElements(error);
+        result.suggestion = getMultipleElementsSuggestion();
         result.multipleElementsDetected = true;
-        result.elements = await formatMatchedElements(error);
+        result.elements = formatElementList(matched);
         return result;
     }
     const notFoundSuggestion = getNotFoundSuggestion(message);
@@ -1111,8 +1130,9 @@ export async function failedToolResult(action, message, data, error) {
 function getMultipleElementsSuggestion() {
     return dedent `
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
-    Read the numbered elements list and click the one you meant by its number:
+    Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1132,7 +1152,7 @@ export function clickFailureSuggestion(attempts) {
         return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
     }
     if (errors.some((e) => e.includes('is not visible'))) {
-        return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+        return 'Element is in the DOM but not visible. Reveal it — scroll to it, expand its section, open the panel holding it — or, when the page carries several copies of the same control, target the one that is on screen.';
     }
     if (errors.some((e) => e.includes('SyntaxError'))) {
         return 'The command string never parsed as JavaScript — quotes or brackets do not match. No element was looked up, so this tells you nothing about the page. Re-emit the same intent as valid CodeceptJS.';
@@ -1162,7 +1182,8 @@ async function extractWebElements(error) {
             const xpath = await elements[i].toAbsoluteXPath();
             const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
             const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
-            result.push({ xpath, html, text });
+            const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
+            result.push({ xpath, html, text, visible });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1170,14 +1191,24 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-function formatElementList(details) {
-    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+function formatElementList(matched) {
+    if (!matched)
+        return 'Could not fetch element details. Repeat the action to get better info.';
+    return matched
+        .map((el, i) => {
+        const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
+        if (el.visible !== undefined)
+            lines.push(`Visible: ${el.visible}`);
+        const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
+        if (wrapped.length)
+            lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
+        lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
+        return lines.join('\n');
+    })
+        .join('\n\n');
 }
 export async function formatMatchedElements(error) {
-    const details = await extractWebElements(error);
-    if (!details)
-        return 'Could not fetch element details. Repeat the action to get better info.';
-    return formatElementList(details);
+    return formatElementList(await extractWebElements(error));
 }
 function getNotFoundSuggestion(errorMessage) {
     if (!errorMessage.includes('not found')) {

package/dist/src/api/spec-reader.d.ts

@@ -1,5 +1,6 @@
 export declare function validateSpecs(specs?: string[]): void;
 export declare function loadSpec(specPaths: string[], outputDir: string): Promise<any>;
 export declare function extractEndpointDefinition(schema: any, endpoint: string, baseEndpoint?: string): string;
+export declare function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[];
 export declare function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string;
 export declare function listAllEndpoints(schema: any, baseEndpoint?: string): string;

package/dist/src/api/spec-reader.js

@@ -42,13 +42,35 @@ export function extractEndpointDefinition(schema, endpoint, baseEndpoint) {
         throw new Error('OpenAPI spec has no paths defined');
     }
     const basePath = toBasePath(baseEndpoint);
-    const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+    const matched = collectEndpointPaths(schema, basePath, endpoint);
     if (!Object.keys(matched).length) {
         const available = listNormalizedPaths(schema, basePath);
         throw new Error(`Endpoint "${endpoint}" not found in spec. Available: ${available}`);
     }
     return safeStringify(matched);
 }
+export function resolveEndpoints(schema, pattern, baseEndpoint) {
+    if (!schema?.paths) {
+        throw new Error('OpenAPI spec has no paths defined');
+    }
+    const basePath = toBasePath(baseEndpoint);
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+    if (!matched.length) {
+        throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+    }
+    const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+    const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+    const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+    if (!endpoints.length) {
+        throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+    }
+    const skipped = resolved.filter((specPath) => specPath.includes('{'));
+    if (skipped.length) {
+        tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+    }
+    return endpoints;
+}
 export function searchEndpoints(schema, query, baseEndpoint) {
     if (!schema?.paths)
         return 'No endpoints available';
@@ -136,6 +158,76 @@ function stripBasePath(specPath, basePath) {
     }
     return `/${specSegments.slice(i).join('/')}`;
 }
+function collectEndpointPaths(schema, basePath, endpoint) {
+    const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+    const roots = resolveEndpoint(normalized, endpoint);
+    if (!roots.length)
+        return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+    return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+function resolveEndpoint(specPaths, endpoint) {
+    const wanted = toSegments(endpoint);
+    if (!wanted.length)
+        return [];
+    const matched = specPaths.filter((specPath) => {
+        const segments = toSegments(specPath);
+        if (segments.length !== wanted.length)
+            return false;
+        return segmentsMatch(segments, wanted);
+    });
+    const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+    const best = Math.max(0, ...literals);
+    return matched.filter((_, i) => literals[i] === best);
+}
+function matchesPattern(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    if (segments.length < wanted.length)
+        return false;
+    return segmentsMatch(segments, wanted);
+}
+function segmentsMatch(segments, wanted) {
+    return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+function toCollection(specPath, specPaths, pattern) {
+    const segments = toSegments(specPath);
+    const filled = toSegments(fillParameters(specPath, pattern));
+    let deepest = segments.length;
+    const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+    if (unfilled >= 0)
+        deepest = unfilled;
+    for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+        const prefix = `/${segments.slice(0, i).join('/')}`;
+        if (specPaths.includes(prefix))
+            return prefix;
+    }
+    return specPath;
+}
+function fillParameters(specPath, pattern) {
+    const wanted = toSegments(pattern);
+    const segments = toSegments(specPath);
+    for (let i = 0; i < wanted.length && i < segments.length; i++) {
+        if (wanted[i] === '*')
+            continue;
+        if (!segments[i].startsWith('{'))
+            continue;
+        segments[i] = wanted[i];
+    }
+    return `/${segments.join('/')}`;
+}
+function listParameters(specPaths) {
+    const found = new Set();
+    for (const specPath of specPaths) {
+        for (const segment of toSegments(specPath)) {
+            if (segment.startsWith('{'))
+                found.add(segment);
+        }
+    }
+    return [...found].join(', ');
+}
+function toSegments(path) {
+    return path.split('/').filter(Boolean);
+}
 function matchesEndpoint(specPath, endpoint) {
     if (specPath === endpoint)
         return true;

package/dist/src/application-spec.d.ts

@@ -4,10 +4,13 @@ export declare class ApplicationSpec {
     readonly sourcePath: string;
     constructor(sourcePath: string);
     renderFor(state: ActionResult): string;
+    matchedUrls(state: ActionResult): string[];
     get pageCount(): number;
     load(): void;
     resolveSourcePath(sourcePath: string): string;
+    relevantPages(state: ActionResult): ApplicationSpecPage[];
 }
+export declare function resolveSpecBundlePath(sourcePath: string): string | null;
 interface ApplicationSpecPage {
     url: string;
     content: string;