explorbot 0.5.6 → 0.5.8

package/dist/src/commands/freesail-command.js

@@ -4,6 +4,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
+import { UrlFilter } from "../utils/url-filter.js";
 import { BaseCommand } from './base-command.js';
 import { DEADLINE_RESERVE_MS, DEADLINE_TEST_ALLOWANCE_MS, ExploreCommand } from './explore-command.js';
 export class FreesailCommand extends BaseCommand {
@@ -17,6 +18,7 @@ export class FreesailCommand extends BaseCommand {
         { flags: '--scope <url>', description: 'Limit navigation to URLs starting with this prefix' },
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
         { flags: '--max-duration <number>', description: 'Wall-clock budget in minutes for the whole run' },
+        { flags: '--url-filter <spec>', description: 'Pick pages to explore: keys filter|exclude|limit, e.g. "filter:/admin/*;exclude:/admin/logs/*;limit:20"' },
     ];
     async execute(args) {
         Stats.mode = 'freesail';
@@ -27,6 +29,7 @@ export class FreesailCommand extends BaseCommand {
         if (opts.shallow)
             strategy = 'shallow';
         const scope = opts.scope;
+        const urlFilter = new UrlFilter(opts.urlFilter);
         const maxTests = opts.maxTests ? Number.parseInt(opts.maxTests, 10) : undefined;
         const maxDuration = opts.maxDuration ? Number.parseInt(opts.maxDuration, 10) : undefined;
         let hardDeadlineAt;
@@ -54,6 +57,7 @@ export class FreesailCommand extends BaseCommand {
                     exploreCmd.maxTests = maxTests - testsRun;
                 if (hardDeadlineAt != null)
                     exploreCmd.hardDeadlineAt = hardDeadlineAt;
+                exploreCmd.urlFilter = urlFilter;
                 await exploreCmd.execute('');
                 const plan = this.explorBot.getCurrentPlan();
                 if (plan)
@@ -63,7 +67,7 @@ export class FreesailCommand extends BaseCommand {
                 ctx.stop();
             const navigator = this.explorBot.agentNavigator();
             const visitedUrls = stateManager.getAllVisitedUrls();
-            const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls });
+            const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls, urlFilter });
             if (!suggestion) {
                 tag('info').log('No navigation suggestion available');
                 ctx.stop();
@@ -72,6 +76,10 @@ export class FreesailCommand extends BaseCommand {
                 tag('warning').log(`Suggestion ${suggestion.target} is outside scope ${scope}, skipping`);
                 ctx.stop();
             }
+            if (!urlFilter.admit(suggestion.target)) {
+                tag('info').log(`URL filter allows no more pages (${suggestion.target} not admitted); stopping exploration`);
+                ctx.stop();
+            }
             const currentUrl = stateManager.getCurrentState()?.url;
             if (currentUrl && normalizeUrl(suggestion.target) === normalizeUrl(currentUrl)) {
                 tag('info').log(`No new navigation target available after ${currentUrl}; stopping exploration`);

package/dist/src/commands/init-command.d.ts

@@ -11,5 +11,6 @@ type InitCommandOptions = {
     global?: boolean;
     provider?: string;
     apiKey?: string;
+    url?: string;
 };
 export {};

package/dist/src/commands/init-command.js

@@ -1,24 +1,29 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
+import figureSet from 'figures';
 import { ConfigParser, PROVIDERS, missingModelRoles } from "../config.js";
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "../global-config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
-import { relativeToCwd } from "../utils/next-steps.js";
-function defaultConfigTemplate(provider) {
+import { printNextSteps, relativeToCwd } from "../utils/next-steps.js";
+function defaultConfigTemplate(provider, url) {
+    const appUrl = url || 'http://<your-app-host-here>';
     return `// 'provider/model-id' uses a bundled provider.
 // It is also possible to import provider as a module from Vercel AI SDK.
-// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+// https://testomat.ai/docs/explorbot
 
 const config = {
   web: {
     // use application host without path prefix (e.g., http://localhost:3000)
-    url: 'http://<your-app-host-here>',
+    url: '${appUrl}',
   },
 
   ai: {
-${modelLines(provider)}
+    // every role (model, visionModel, agenticModel) takes the recommended ${provider} models bundled with this version
+    // override a single role as 'provider/model-id':
+    // model: '${provider}/<model-id>',
+    recommendedModels: '${provider}',
   },
 
   reporter: {
@@ -35,9 +40,10 @@ export default config;
 `;
 }
 export function envTemplate(provider) {
+    const { keyUrl } = PROVIDERS[provider];
     const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
         if (name === provider)
-            return `${envKey}=`;
+            return `# Create a key at ${keyUrl} and paste it after '='\n${envKey}=`;
         return `# ${envKey}=`;
     });
     return `# AI provider API keys
@@ -64,10 +70,10 @@ export async function runInit(options) {
     const choice = await renderInitWizard('choose');
     if (choice !== 'local')
         return;
-    const provider = await renderLocalProviderWizard();
-    if (!provider)
+    const setup = await renderLocalSetupWizard();
+    if (!setup)
         return;
-    runInitCommand({ ...options, provider });
+    runInitCommand({ ...options, ...setup });
 }
 export function writeGlobalConfig(provider, apiKey) {
     if (!PROVIDERS[provider]) {
@@ -75,21 +81,25 @@ export function writeGlobalConfig(provider, apiKey) {
     }
     mkdirSync(globalDir(), { recursive: true });
     writeFileSync(globalConfigPath(), globalConfigTemplate(provider), 'utf8');
-    log(`Created global config: ${globalConfigPath()}`);
+    tag('success').log(`${figureSet.tick} Created global config: ${globalConfigPath()}`);
     const envKey = PROVIDERS[provider].envKey;
     writeEnvKey(envKey, apiKey || '');
-    log(`Stored ${envKey} in ${globalEnvPath()}`);
+    tag('success').log(`${figureSet.tick} Stored ${envKey} in ${globalEnvPath()}`);
     const missing = missingModelRoles(provider);
     if (missing.length) {
         tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
     }
     if (!apiKey && !process.env[envKey]) {
-        tag('warning').log(`Add your API key to ${globalEnvPath()}`);
+        printApiKeySteps(provider, globalEnvPath());
     }
     log('');
-    log('Explorbot now runs from any directory:');
-    tag('substep').log(chalk.yellow(`${getCliName()} explore https://your-app.example.com`));
-    tag('substep').log(chalk.yellow(`${getCliName()} sites`));
+    log(`${figureSet.star} What's next:`);
+    printInitNextSteps({
+        siteCommands: [
+            { label: 'Any site', command: `${getCliName()} explore https://your-app.example.com` },
+            { label: 'Saved sites', command: `${getCliName()} sites` },
+        ],
+    });
 }
 export function runInitCommand(options) {
     const provider = options.provider || 'openrouter';
@@ -125,34 +135,38 @@ export function runInitCommand(options) {
             log('Use --force to overwrite existing file');
             process.exit(1);
         }
-        writeFileSync(outPath, defaultConfigTemplate(provider), 'utf8');
-        log(`Created config file: ${relativeToCwd(outPath)}`);
+        writeFileSync(outPath, defaultConfigTemplate(provider, options.url), 'utf8');
+        tag('success').log(`${figureSet.tick} Created config file: ${relativeToCwd(outPath)}`);
         const envPath = resolve(process.cwd(), '.env');
         if (!existsSync(envPath)) {
             writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
-            log(`Created env file: ${relativeToCwd(envPath)}`);
+            tag('success').log(`${figureSet.tick} Created env file: ${relativeToCwd(envPath)}`);
         }
         else {
             log(`Env file already exists: ${relativeToCwd(envPath)}`);
         }
+        const envKey = PROVIDERS[provider].envKey;
+        if (options.apiKey) {
+            writeEnvKey(envKey, options.apiKey, envPath);
+            tag('success').log(`${figureSet.tick} Stored ${envKey} in ${relativeToCwd(envPath)}`);
+        }
+        if (!options.apiKey && !process.env[envKey]) {
+            printApiKeySteps(provider, relativeToCwd(envPath));
+        }
+        if (!options.url) {
+            tag('warning').log(`Set your application URL in web.url: ${relativeToCwd(outPath)}`);
+        }
         const missing = missingModelRoles(provider);
         if (missing.length) {
             tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
         }
-        log('');
-        log('Next steps:');
-        log('1. Configure AI provider in .env');
-        log('2. Set AI models config file');
-        log('3. Set web application URL in the config file');
-        log('4. Add initial knowledge (how to authorize to the application, etc.)');
-        tag('substep').log(chalk.yellow(`${getCliName()} learn '*' 'to authorize use these credentials: admin@example.com / secret123'`));
-        tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
-        log('5. Launch application on a relative URL');
-        tag('substep').log(chalk.yellow(`${getCliName()} start /dashboard`));
         if (!existsSync('./output')) {
             mkdirSync('./output', { recursive: true });
-            log('Created directory: output');
+            tag('success').log(`${figureSet.tick} Created directory: output`);
         }
+        log('');
+        log(`${figureSet.star} What's next:`);
+        printInitNextSteps({ url: options.url });
     }
     catch (error) {
         log('Failed to create config file:', error);
@@ -198,12 +212,12 @@ async function renderInitWizard(mode) {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-async function renderLocalProviderWizard() {
+async function renderLocalSetupWizard() {
     const [{ render }, React, InitWizard] = await Promise.all([import('ink'), import('react'), import('../components/InitWizard.js').then((m) => m.default)]);
     return new Promise((resolve) => {
-        const finish = (provider) => {
+        const finish = (setup) => {
             unmount();
-            resolve(provider);
+            resolve(setup);
         };
         const { unmount } = render(React.createElement(InitWizard, {
             mode: 'local',
@@ -211,7 +225,7 @@ async function renderLocalProviderWizard() {
             onLocal: () => finish(null),
             onComplete: () => finish(null),
             onCancel: () => finish(null),
-            onLocalProvider: (provider) => finish(provider),
+            onLocalSetup: (setup) => finish(setup),
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
@@ -238,7 +252,7 @@ function globalConfigTemplate(provider) {
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
 // The key is read from ${envKey} in ~/.explorbot/.env
 // Model ids are snapshotted from the recommendations of this Explorbot version.
-// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+// https://testomat.ai/docs/explorbot
 const config = {
   ai: {
 ${modelLines(provider)}
@@ -255,8 +269,39 @@ ${modelLines(provider)}
 export default config;
 `;
 }
-function writeEnvKey(key, value) {
-    const envPath = globalEnvPath();
+function printInitNextSteps(options) {
+    const cli = getCliName();
+    const sections = [
+        {
+            label: 'Try the demo on a sample app',
+            commands: [{ command: `${cli} explore https://todomvc.com/examples/react/dist/` }],
+        },
+    ];
+    if (options.url) {
+        sections.push({
+            label: 'Explore your app',
+            commands: [
+                { label: 'Whole site', command: `${cli} explore ${options.url}` },
+                { label: 'One page', command: `${cli} explore /dashboard` },
+            ],
+        });
+    }
+    if (options.siteCommands)
+        sections.push({ label: 'Explore any site', commands: options.siteCommands });
+    sections.push({
+        label: 'Run it from VS Code',
+        commands: [{ command: 'https://testomat.ai/explorbot' }],
+    }, {
+        label: 'Docs',
+        commands: [{ command: 'https://testomat.ai/docs/explorbot' }],
+    });
+    printNextSteps(sections);
+    log('');
+    log('Add knowledge (logins, credentials) — created on first use in ./knowledge:');
+    tag('substep').log(chalk.yellow(`${cli} learn '*' 'to authorize use these credentials: admin@example.com / secret123'`));
+    tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
+}
+function writeEnvKey(key, value, envPath = globalEnvPath()) {
     let content = '# AI provider API keys';
     if (existsSync(envPath))
         content = readFileSync(envPath, 'utf8').trimEnd();
@@ -268,3 +313,9 @@ function writeEnvKey(key, value) {
         lines[index] = `${key}=${value}`;
     writeFileSync(envPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
 }
+function printApiKeySteps(provider, envPath) {
+    const { envKey, keyUrl } = PROVIDERS[provider];
+    tag('warning').log(`No API key yet — explorbot needs one to connect to ${provider}`);
+    tag('substep').log(`1. Create a key at ${keyUrl}`);
+    tag('substep').log(`2. Paste it into ${envPath}: ${envKey}=<your-key>`);
+}

package/dist/src/components/InitWizard.d.ts

@@ -5,7 +5,11 @@ interface InitWizardProps {
     onLocal: () => void;
     onComplete: () => void;
     onCancel: () => void;
-    onLocalProvider?: (provider: string) => void;
+    onLocalSetup?: (setup: {
+        provider: string;
+        apiKey: string;
+        url: string;
+    }) => void;
 }
 declare const InitWizard: React.FC<InitWizardProps>;
 export default InitWizard;

package/dist/src/components/InitWizard.js

@@ -7,16 +7,23 @@ import { ConfigParser, PROVIDERS, createModel } from '../config.js';
 import { globalDir } from '../global-config.js';
 import InputReadline from './InputReadline.js';
 const PROVIDER_NAMES = Object.keys(PROVIDERS);
-const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalProvider }) => {
+const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalSetup }) => {
     const [step, setStep] = useState(mode === 'choose' ? 'target' : 'provider');
     const [targetIndex, setTargetIndex] = useState(0);
     const [providerIndex, setProviderIndex] = useState(0);
     const [apiKey, setApiKey] = useState('');
+    const [url, setUrl] = useState('');
+    const [urlError, setUrlError] = useState('');
     const [status, setStatus] = useState('');
     const [error, setError] = useState('');
     const provider = PROVIDER_NAMES[providerIndex];
     const envKey = PROVIDERS[provider].envKey;
     const save = () => {
+        if (mode === 'local') {
+            setStatus('');
+            setStep('url');
+            return;
+        }
         writeGlobalConfig(provider, apiKey.trim());
         onComplete();
     };
@@ -45,7 +52,7 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, o
             onCancel();
             return;
         }
-        if (step === 'key')
+        if (step === 'key' || step === 'url')
             return;
         if (key.escape) {
             onCancel();
@@ -67,12 +74,8 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, o
                 setProviderIndex((index) => Math.max(0, index - 1));
             if (key.downArrow)
                 setProviderIndex((index) => Math.min(PROVIDER_NAMES.length - 1, index + 1));
-            if (key.return) {
-                if (mode === 'local')
-                    onLocalProvider?.(provider);
-                else
-                    setStep('key');
-            }
+            if (key.return)
+                setStep('key');
             return;
         }
         if (status)
@@ -109,10 +112,12 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, o
             React.createElement(Text, null,
                 "Enter the API key for ",
                 provider,
-                " ",
+                ' ',
                 React.createElement(Text, { dimColor: true },
                     "(stored as ",
                     envKey,
+                    ", create one at ",
+                    PROVIDERS[provider].keyUrl,
                     ")")),
             React.createElement(Box, { borderStyle: "single", borderColor: "blue", paddingX: 1 },
                 React.createElement(InputReadline, { value: apiKey, onChange: setApiKey, onSubmit: () => setStep('validate'), placeholder: process.env[envKey] ? 'leave empty to keep the key from your environment' : 'paste the key', isActive: true, showPrompt: false, mask: true })))),
@@ -121,13 +126,26 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, o
             status && React.createElement(Text, { color: "yellow" }, status),
             error && (React.createElement(Box, { flexDirection: "column" },
                 React.createElement(Text, { color: "red" }, error),
-                React.createElement(Text, { dimColor: true }, "r: re-enter the key | n: save anyway"))))),
+                React.createElement(Text, { dimColor: true }, "r: re-enter the key | n: continue anyway"))))),
+        step === 'url' && (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Text, null,
+                "What is the URL of the web application to test? ",
+                React.createElement(Text, { dimColor: true }, "(written to web.url in the config)")),
+            React.createElement(Box, { borderStyle: "single", borderColor: "blue", paddingX: 1 },
+                React.createElement(InputReadline, { value: url, onChange: setUrl, onSubmit: () => {
+                        if (!URL.canParse(url.trim())) {
+                            setUrlError('Enter a full URL, e.g. http://localhost:3000');
+                            return;
+                        }
+                        onLocalSetup?.({ provider, apiKey: apiKey.trim(), url: url.trim() });
+                    }, placeholder: "http://localhost:3000", isActive: true, showPrompt: false })),
+            urlError && React.createElement(Text, { color: "red" }, urlError))),
         React.createElement(Box, { marginTop: 1 },
             React.createElement(Text, { dimColor: true },
                 "Config goes to ",
                 mode === 'local' ? 'the current directory' : globalDir(),
                 " | ",
-                step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm',
+                step === 'key' || step === 'url' ? 'Enter: continue' : '↑↓: select | Enter: confirm',
                 " | Ctrl+C: exit"))));
 };
 function defaultModelId(provider) {

package/dist/src/config.d.ts

@@ -141,6 +141,7 @@ interface AgentsConfig {
 }
 interface AIConfig {
     model: any;
+    recommendedModels?: string;
     apiKey?: string;
     config?: Record<string, any>;
     langfuse?: {
@@ -315,6 +316,7 @@ interface ConfiguredModel {
 }
 interface ProviderInfo {
     envKey: string;
+    keyUrl: string;
     load: () => Promise<(modelId: string) => any>;
 }
 interface EnvVar {

package/dist/src/config.js

@@ -18,13 +18,13 @@ import { getCliName } from './utils/cli-name.js';
 import { deepMerge } from './utils/merge.js';
 import { log, tag } from './utils/logger.js';
 export const PROVIDERS = {
-    openai: { envKey: 'OPENAI_API_KEY', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
-    anthropic: { envKey: 'ANTHROPIC_API_KEY', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
-    google: { envKey: 'GOOGLE_GENERATIVE_AI_API_KEY', load: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI() },
-    groq: { envKey: 'GROQ_API_KEY', load: async () => (await import('@ai-sdk/groq')).createGroq() },
-    mistral: { envKey: 'MISTRAL_API_KEY', load: async () => (await import('@ai-sdk/mistral')).createMistral() },
-    openrouter: { envKey: 'OPENROUTER_API_KEY', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
-    sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
+    openai: { envKey: 'OPENAI_API_KEY', keyUrl: 'https://platform.openai.com/api-keys', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
+    anthropic: { envKey: 'ANTHROPIC_API_KEY', keyUrl: 'https://console.anthropic.com/settings/keys', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
+    google: { envKey: 'GOOGLE_GENERATIVE_AI_API_KEY', keyUrl: 'https://aistudio.google.com/apikey', load: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI() },
+    groq: { envKey: 'GROQ_API_KEY', keyUrl: 'https://console.groq.com/keys', load: async () => (await import('@ai-sdk/groq')).createGroq() },
+    mistral: { envKey: 'MISTRAL_API_KEY', keyUrl: 'https://console.mistral.ai/api-keys', load: async () => (await import('@ai-sdk/mistral')).createMistral() },
+    openrouter: { envKey: 'OPENROUTER_API_KEY', keyUrl: 'https://openrouter.ai/keys', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
+    sambanova: { envKey: 'SAMBANOVA_API_KEY', keyUrl: 'https://cloud.sambanova.ai/apis', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
 export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
@@ -572,11 +572,33 @@ export async function resolveConfigModels(ai) {
         if (typeof ai[role] === 'string')
             ai[role] = await resolveModel(ai[role], role);
     }
+    await fillRecommendedModels(ai);
     for (const agent of Object.values(ai.agents || {})) {
         if (typeof agent?.model === 'string')
             agent.model = await resolveModel(agent.model);
     }
 }
+async function fillRecommendedModels(ai) {
+    const provider = ai.recommendedModels;
+    if (!provider)
+        return;
+    const recommended = ConfigParser.recommendedModels()[provider];
+    if (!recommended) {
+        throw new Error(`No recommended models for "${provider}". Use a provider with recommendations: ${Object.keys(ConfigParser.recommendedModels()).join(', ')}`);
+    }
+    for (const role of MODEL_ROLES) {
+        if (ai[role])
+            continue;
+        if (!recommended[role])
+            continue;
+        ai[role] = await resolveModel(provider, role);
+    }
+    if (!ai.decisionModel && recommended.decisionModel)
+        ai.decisionModel = { provider, model: recommended.decisionModel };
+    const missing = missingModelRoles(provider);
+    if (missing.length)
+        tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set them explicitly as "provider/model-id"`);
+}
 export function resolveLangfuse(ai) {
     if (!ai)
         return;

package/dist/src/test-plan.d.ts

@@ -121,6 +121,7 @@ export declare class Test extends Task {
     get isSkipped(): boolean;
     getCheckedNotes(): Note[];
     getCheckedExpectations(): string[];
+    hasAchieved(expectation: string): boolean;
     hasAchievedAny(): boolean;
     getRunResult(): 'success' | 'partial' | 'failed';
     hasAchievedAll(): boolean;

package/dist/src/test-plan.js

@@ -272,10 +272,11 @@ export class Test extends Task {
             return Object.values(this.notes).some((note) => note.message === expectation && !!note.status);
         });
     }
+    hasAchieved(expectation) {
+        return Object.values(this.notes).some((note) => note.message === expectation && note.status === TestResult.PASSED);
+    }
     hasAchievedAny() {
-        return this.expected.some((expectation) => {
-            return Object.values(this.notes).some((note) => note.message === expectation && note.status === TestResult.PASSED);
-        });
+        return this.expected.some((expectation) => this.hasAchieved(expectation));
     }
     getRunResult() {
         if (this.isSuccessful)
@@ -285,9 +286,7 @@ export class Test extends Task {
         return super.getRunResult();
     }
     hasAchievedAll() {
-        return this.expected.every((expectation) => {
-            return Object.values(this.notes).some((note) => note.message === expectation && note.status === TestResult.PASSED);
-        });
+        return this.expected.every((expectation) => this.hasAchieved(expectation));
     }
     isComplete() {
         return this.expected.every((expectation) => {

package/dist/src/utils/sitemap.d.ts

@@ -0,0 +1,11 @@
+import type { UrlFilter } from './url-filter.js';
+export declare function readSitemap(source: string, filter?: UrlFilter): Promise<string[]>;
+export declare function readCliSitemap(path: string | undefined, source: string | undefined, filter?: UrlFilter): Promise<string[] | undefined>;
+export declare function keepSiteUrls(urls: string[], siteUrl: string): string[];
+export declare function extractEntries(content: string): SitemapEntry[];
+interface SitemapEntry {
+    url: string;
+    priority: number;
+    lastmod?: number;
+}
+export {};

package/dist/src/utils/sitemap.js

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import { tag } from './logger.js';
+const ENTRY_PATTERN = /<(url|sitemap)\b[^>]*>(.*?)<\/\1>/gis;
+const XML_ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'" };
+const MAX_NESTED_SITEMAPS = 50;
+const DEFAULT_PRIORITY = 0.5;
+const STDIN_SOURCE = '-';
+export async function readSitemap(source, filter) {
+    const entries = [];
+    const seen = new Set();
+    const pending = [source];
+    let fetched = 0;
+    while (pending.length > 0) {
+        if (fetched >= MAX_NESTED_SITEMAPS) {
+            tag('warning').log(`Sitemap index lists more than ${MAX_NESTED_SITEMAPS} sitemaps, the rest are ignored`);
+            break;
+        }
+        const next = pending.shift();
+        fetched++;
+        const content = await readSource(next);
+        const isIndex = content.includes('<sitemapindex');
+        for (const entry of extractEntries(content)) {
+            if (seen.has(entry.url))
+                continue;
+            seen.add(entry.url);
+            if (isIndex) {
+                pending.push(entry.url);
+                continue;
+            }
+            entries.push(entry);
+        }
+    }
+    return applyFilter(entries, filter).map((entry) => entry.url);
+}
+export async function readCliSitemap(path, source, filter) {
+    const usage = 'Pass a page path, --sitemap <source>, or pipe a sitemap to stdin';
+    let resolved = source;
+    if (!resolved && !path && !process.stdin.isTTY)
+        resolved = STDIN_SOURCE;
+    if (!resolved && !path)
+        throw new Error(usage);
+    if (!resolved)
+        return undefined;
+    const urls = await readSitemap(resolved, filter);
+    if (urls.length === 0 && !source)
+        throw new Error(usage);
+    if (urls.length === 0)
+        throw new Error(`No URLs left in sitemap ${resolved}`);
+    return urls;
+}
+export function keepSiteUrls(urls, siteUrl) {
+    const siteOrigin = URL.parse(siteUrl)?.origin;
+    const kept = urls.filter((url) => url.startsWith('/') || URL.parse(url)?.origin === siteOrigin);
+    if (kept.length < urls.length)
+        tag('warning').log(`Skipped ${urls.length - kept.length} sitemap URL(s) outside ${siteOrigin}`);
+    return kept;
+}
+export function extractEntries(content) {
+    if (!content.trimStart().startsWith('<')) {
+        return content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith('http://') || line.startsWith('https://') || line.startsWith('/'))
+            .map((url) => ({ url, priority: DEFAULT_PRIORITY }));
+    }
+    const entries = [];
+    for (const match of content.matchAll(ENTRY_PATTERN)) {
+        const url = tagValue(match[2], 'loc');
+        if (!url)
+            continue;
+        const entry = { url, priority: DEFAULT_PRIORITY };
+        const priority = Number.parseFloat(tagValue(match[2], 'priority') || '');
+        if (!Number.isNaN(priority))
+            entry.priority = priority;
+        const lastmod = Date.parse(tagValue(match[2], 'lastmod') || '');
+        if (!Number.isNaN(lastmod))
+            entry.lastmod = lastmod;
+        entries.push(entry);
+    }
+    return entries;
+}
+function applyFilter(entries, filter) {
+    if (!filter)
+        return entries;
+    let result = entries.filter((entry) => filter.allows(entry.url));
+    if (filter.sort === 'priority')
+        result = result.toSorted((a, b) => b.priority - a.priority);
+    if (filter.sort === 'lastmod')
+        result = result.toSorted((a, b) => (b.lastmod ?? 0) - (a.lastmod ?? 0));
+    return result.slice(0, filter.limit);
+}
+function tagValue(block, name) {
+    const match = block.match(new RegExp(`<${name}>\\s*(?:<!\\[CDATA\\[)?\\s*(.*?)\\s*(?:\\]\\]>)?\\s*</${name}>`, 'is'));
+    return match?.[1].replace(/&(amp|lt|gt|quot|apos);/g, (entity) => XML_ENTITIES[entity]) || undefined;
+}
+async function readSource(source) {
+    if (source === STDIN_SOURCE)
+        return readFileSync(0, 'utf8');
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const response = await fetch(source);
+        if (!response.ok)
+            throw new Error(`Sitemap ${source} returned HTTP ${response.status}`);
+        return await response.text();
+    }
+    return readFileSync(source, 'utf8');
+}

package/dist/src/utils/spec.d.ts

@@ -0,0 +1,5 @@
+export declare function parseSpecPairs(raw: string | undefined): SpecPair[];
+export interface SpecPair {
+    key: string;
+    value: string;
+}

package/dist/src/utils/spec.js

@@ -0,0 +1,16 @@
+import { tag } from './logger.js';
+export function parseSpecPairs(raw) {
+    const pairs = [];
+    for (const pair of (raw || '').split(';')) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const sepMatch = trimmed.match(/^([^:=]+)\s*[:=]\s*(.*)$/);
+        if (!sepMatch) {
+            tag('warning').log(`Ignoring malformed spec pair: ${trimmed}`);
+            continue;
+        }
+        pairs.push({ key: sepMatch[1].trim().toLowerCase(), value: sepMatch[2].trim() });
+    }
+    return pairs;
+}

package/dist/src/utils/url-filter.d.ts

@@ -0,0 +1,10 @@
+export declare class UrlFilter {
+    readonly include: string[];
+    readonly exclude: string[];
+    sort?: 'priority' | 'lastmod';
+    limit: number;
+    admitted: Set<string>;
+    constructor(spec?: string);
+    allows(url: string): boolean;
+    admit(url: string): boolean;
+}