explorbot 0.4.1 → 0.4.3

package/dist/src/api/request-store.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { isDynamicSegment } from "../utils/url-matcher.js";
+import { generalizeUrl, isDynamicSegment } from "../utils/url-matcher.js";
 import { RequestResult } from "./request-result.js";
 const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
@@ -10,6 +10,7 @@ export class RequestStore {
     onFailedListeners = [];
     outputDir;
     sessionStartedAt = new Date();
+    readEndpointKeys = new Set();
     constructor(outputDir) {
         this.outputDir = outputDir;
     }
@@ -17,6 +18,14 @@ export class RequestStore {
         this.capturedRequests.push(result);
         result.save(this.outputDir);
     }
+    addReadRequest(result) {
+        const key = readEndpointKey(result);
+        if (this.readEndpointKeys.has(key))
+            return;
+        this.readEndpointKeys.add(key);
+        this.capturedRequests.push(result);
+        result.save(this.outputDir);
+    }
     addFailedRequest(result) {
         this.failedRequests.push(result);
         for (const cb of this.onFailedListeners) {
@@ -38,39 +47,23 @@ export class RequestStore {
         this.madeRequests.push(result);
         result.save(this.outputDir);
     }
-    addRequest(result) {
-        this.addMadeRequest(result);
-    }
     getCapturedRequests() {
         return this.capturedRequests;
     }
     getMadeRequests() {
         return this.madeRequests;
     }
-    getRequests() {
-        return this.madeRequests;
-    }
     getLastRequest() {
         return this.madeRequests[this.madeRequests.length - 1];
     }
-    getRequestsByEndpoint(pathPrefix) {
-        return this.madeRequests.filter((r) => r.path.startsWith(pathPrefix));
-    }
-    getRequestsByMethod(method) {
-        const upper = method.toUpperCase();
-        return this.madeRequests.filter((r) => r.method === upper);
-    }
-    getRequestsByStatus(status) {
-        return this.madeRequests.filter((r) => r.status === status);
-    }
-    toEndpointList(scopePath) {
-        let requests = this.capturedRequests;
+    toEndpointList(scopePath, methods = 'write') {
+        let requests = this.capturedRequests.filter((r) => matchesFamily(r, methods));
         if (scopePath)
-            requests = this.getWriteRequestsForScope(scopePath);
+            requests = this.getRequestsForScope(scopePath, methods);
         const seen = new Set();
         const lines = [];
         for (const req of requests) {
-            const key = `${req.method} ${normalizePathPattern(req.path)}`;
+            const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}${queryParamHint(req)}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -92,13 +85,17 @@ export class RequestStore {
     }
     findCapturedRequest(method, searchPath) {
         const upper = method.toUpperCase();
-        const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+        const search = generalizeUrl(searchPath, () => '{id}')
+            .split('/')
+            .filter(Boolean);
         let best;
         let bestScore = -1;
         for (const req of this.capturedRequests) {
             if (req.method !== upper)
                 continue;
-            const segments = normalizePathPattern(req.path).split('/').filter(Boolean);
+            const segments = generalizeUrl(req.path, () => '{id}')
+                .split('/')
+                .filter(Boolean);
             if (segments.length < search.length)
                 continue;
             if (!search.every((segment, i) => segment === segments[i]))
@@ -131,6 +128,12 @@ export class RequestStore {
                 const result = RequestResult.load(path.join(requestsDir, file));
                 if (existingIds.has(result.id))
                     continue;
+                if (!result.isWrite) {
+                    const key = readEndpointKey(result);
+                    if (this.readEndpointKeys.has(key))
+                        continue;
+                    this.readEndpointKeys.add(key);
+                }
                 this.capturedRequests.push(result);
             }
             catch {
@@ -139,18 +142,29 @@ export class RequestStore {
         }
     }
     getWriteRequestsForScope(scopePath) {
-        const writeMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-        const writes = this.capturedRequests.filter((r) => writeMethods.has(r.method));
+        return this.getRequestsForScope(scopePath, 'write');
+    }
+    getReadRequestsForScope(scopePath) {
+        return this.getRequestsForScope(scopePath, 'read');
+    }
+    clear() {
+        this.capturedRequests = [];
+        this.madeRequests = [];
+        this.failedRequests = [];
+        this.readEndpointKeys.clear();
+    }
+    getRequestsForScope(scopePath, methods) {
+        const candidates = this.capturedRequests.filter((r) => matchesFamily(r, methods));
         const scopeSegments = scopePath.split('/').filter(Boolean);
         if (scopeSegments.length === 0)
-            return writes;
+            return candidates;
         let scoped = [];
         let fewest = Number.POSITIVE_INFINITY;
         let ambiguous = false;
         for (const segment of scopeSegments) {
             if (isDynamicSegment(segment))
                 continue;
-            const matches = writes.filter((r) => r.path.split('/').includes(segment));
+            const matches = candidates.filter((r) => r.path.split('/').includes(segment));
             if (matches.length === 0 || matches.length > fewest)
                 continue;
             if (matches.length === fewest) {
@@ -166,15 +180,29 @@ export class RequestStore {
             return [];
         return scoped;
     }
-    clear() {
-        this.capturedRequests = [];
-        this.madeRequests = [];
-        this.failedRequests = [];
-    }
 }
-function normalizePathPattern(urlPath) {
-    return urlPath
-        .split('/')
-        .map((segment) => (segment && isDynamicSegment(segment) ? '{id}' : segment))
-        .join('/');
+export function isFailedRequest(request) {
+    return request.status >= 400 || Boolean(request.error);
+}
+function readEndpointKey(result) {
+    return `${result.method} ${generalizeUrl(result.path, () => '{id}')}?${queryParamNames(result).join(',')}`;
+}
+function matchesFamily(result, methods) {
+    if (methods === 'write')
+        return result.isWrite;
+    return result.method === 'GET';
+}
+function queryParamHint(result) {
+    if (result.isWrite)
+        return '';
+    const names = queryParamNames(result);
+    if (names.length === 0)
+        return '';
+    return ` ?${names.join(',')}`;
+}
+function queryParamNames(result) {
+    const query = result.fullUrl.split('?')[1];
+    if (!query)
+        return [];
+    return [...new Set(new URLSearchParams(query).keys())].sort();
 }

package/dist/src/api/xhr-capture.d.ts

@@ -7,4 +7,6 @@ export declare class XhrCapture {
     attach(page: any): void;
     detach(page: any): void;
     captureResponse(response: any): Promise<void>;
+    captureReadEndpoint(request: any, response: any): void;
+    toHeaderMap(headers: Record<string, unknown>): Record<string, string>;
 }

package/dist/src/api/xhr-capture.js

@@ -52,24 +52,24 @@ export class XhrCapture {
             });
             this.store.addFailedRequest(failure);
         }
-        if (!WRITE_METHODS.has(method))
-            return;
         const contentType = response.headers()['content-type'] || '';
         if (!JSON_CONTENT_TYPES.test(contentType))
             return;
+        if (method === 'GET') {
+            if (status !== 200)
+                return;
+            this.captureReadEndpoint(request, response);
+            return;
+        }
+        if (!WRITE_METHODS.has(method))
+            return;
         if (status === 304)
             return;
         const parsedUrl = new URL(url);
         const origin = parsedUrl.pathname + parsedUrl.search;
         const id = generateRequestId(method, parsedUrl.pathname, 'xhr_');
-        const requestHeaders = {};
-        for (const [k, v] of Object.entries(request.headers())) {
-            requestHeaders[k] = String(v);
-        }
-        const responseHeaders = {};
-        for (const [k, v] of Object.entries(response.headers())) {
-            responseHeaders[k] = String(v);
-        }
+        const requestHeaders = this.toHeaderMap(request.headers());
+        const responseHeaders = this.toHeaderMap(response.headers());
         let rawBody = '';
         try {
             rawBody = await response.text();
@@ -103,4 +103,29 @@ export class XhrCapture {
         result.rawResponseBodyValue = rawBody;
         this.store.addCapturedRequest(result);
     }
+    captureReadEndpoint(request, response) {
+        const parsedUrl = new URL(request.url());
+        const requestHeaders = this.toHeaderMap(request.headers());
+        const result = new RequestResult({
+            id: generateRequestId('GET', parsedUrl.pathname, 'xhr_'),
+            method: 'GET',
+            path: parsedUrl.pathname,
+            fullUrl: parsedUrl.pathname + parsedUrl.search,
+            requestHeaders,
+            status: response.status(),
+            statusText: response.statusText(),
+            responseHeaders: {},
+            timing: 0,
+            timestamp: new Date(),
+        });
+        result.rawResponseBodyValue = '';
+        this.store.addReadRequest(result);
+    }
+    toHeaderMap(headers) {
+        const map = {};
+        for (const [k, v] of Object.entries(headers)) {
+            map[k] = String(v);
+        }
+        return map;
+    }
 }

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

@@ -5,6 +5,7 @@ import { ConfigParser, EXPLORBOT_ENV_VARS, configuredModels } from '../config.js
 import { listSites } from '../global-config.js';
 import { Reporter } from '../reporter.js';
 import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
 export class ConfigCommand extends BaseCommand {
@@ -68,15 +69,7 @@ export class ConfigCommand extends BaseCommand {
         if (options.json)
             return JSON.stringify(data, null, 2);
         const lines = [];
-        const section = (title, entries) => {
-            if (!entries.length)
-                return;
-            const width = Math.max(...entries.map(([label]) => label.length));
-            lines.push(chalk.bold(title));
-            for (const [label, value] of entries)
-                lines.push(`  ${chalk.dim(label.padEnd(width))}  ${value}`);
-            lines.push('');
-        };
+        const section = (title, entries) => lines.push(...renderSection(title, entries));
         const general = [['config', data.config || 'EXPLORBOT_* environment variables']];
         if (data.url)
             general.push(['url', data.url]);

package/dist/src/commands/help-json-command.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+export declare class HelpJsonCommand {
+    static register(program: Command): void;
+    static data(cmd: Command, root?: boolean): CommandDefinition;
+    static find(cmd: Command, names: string[]): Command | undefined;
+}
+interface CommandDefinition {
+    name: string;
+    description: string;
+    aliases: string[];
+    version?: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+        variadic: boolean;
+    }[];
+    options: {
+        flags: string;
+        description: string;
+        default?: unknown;
+        choices?: string[];
+    }[];
+    commands: CommandDefinition[];
+    env?: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}
+export {};

package/dist/src/commands/help-json-command.js

@@ -0,0 +1,58 @@
+import { EXPLORBOT_ENV_VARS } from '../config.js';
+const DESCRIPTION = 'Print command definitions as JSON for agents and tools';
+export class HelpJsonCommand {
+    static register(program) {
+        program
+            .command('help-json [command...]')
+            .description(DESCRIPTION)
+            .action(async (names) => {
+            const target = HelpJsonCommand.find(program, names);
+            if (!target) {
+                console.error(`Unknown command: ${names.join(' ')}`);
+                process.exit(1);
+            }
+            const json = JSON.stringify(HelpJsonCommand.data(target, target === program), null, 2);
+            await new Promise((resolve) => process.stdout.write(`${json}\n`, () => resolve()));
+        });
+    }
+    static data(cmd, root = false) {
+        const helper = cmd.createHelp();
+        const definition = {
+            name: cmd.name(),
+            description: cmd.description(),
+            aliases: cmd.aliases(),
+            arguments: cmd.registeredArguments.map((argument) => ({
+                name: argument.name(),
+                description: argument.description,
+                required: argument.required,
+                variadic: argument.variadic,
+            })),
+            options: helper.visibleOptions(cmd).map((option) => ({
+                flags: option.flags,
+                description: option.description,
+                default: option.defaultValue,
+                choices: option.argChoices,
+            })),
+            commands: helper.visibleCommands(cmd).map((sub) => HelpJsonCommand.data(sub)),
+        };
+        if (!root)
+            return definition;
+        definition.version = cmd.version();
+        definition.env = EXPLORBOT_ENV_VARS.map((variable) => ({
+            name: variable.name,
+            description: variable.description,
+            required: !!variable.required,
+        }));
+        return definition;
+    }
+    static find(cmd, names) {
+        let target = cmd;
+        for (const name of names) {
+            const sub = target.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
+            if (!sub)
+                return undefined;
+            target = sub;
+        }
+        return target;
+    }
+}

package/dist/src/commands/index.js

@@ -26,6 +26,7 @@ import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
 import { PlansCommand } from './plans-command.js';
+import { RecommendedModelsCommand } from './recommended-models-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -66,6 +67,7 @@ const commandClasses = [
     RerunCommand,
     StatusCommand,
     ConfigCommand,
+    RecommendedModelsCommand,
     DebugCommand,
     ExitCommand,
 ];

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import { ConfigParser, PROVIDERS } from "../config.js";
+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';
@@ -82,7 +82,7 @@ export function writeGlobalConfig(provider, apiKey) {
     const envKey = PROVIDERS[provider].envKey;
     writeEnvKey(envKey, apiKey || '');
     log(`Stored ${envKey} in ${globalEnvPath()}`);
-    const missing = missingRoles(provider);
+    const missing = missingModelRoles(provider);
     if (missing.length) {
         tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
     }
@@ -139,7 +139,7 @@ export function runInitCommand(options) {
         else {
             log(`Env file already exists: ${relativeToCwd(envPath)}`);
         }
-        const missing = missingRoles(provider);
+        const missing = missingModelRoles(provider);
         if (missing.length) {
             tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
         }
@@ -269,10 +269,6 @@ function isModuleProject(configDir) {
         currentDir = parentDir;
     }
 }
-function missingRoles(provider) {
-    const recommended = ConfigParser.recommendedModels()[provider] || {};
-    return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
-}
 function writeEnvKey(key, value) {
     const envPath = globalEnvPath();
     let content = '# AI provider API keys';

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

@@ -11,7 +11,10 @@ export declare class PlansCommand extends BaseCommand {
     getPlanFiles(): PlanFile[];
     printPlans(files: PlanFile[]): void;
     printPlanDetails(plan: Plan, file: PlanFile): void;
-    resolvePlanFile(target: string, files: PlanFile[]): PlanFile;
+    resolvePlanFile(target: string, files: PlanFile[]): {
+        plan: Plan;
+        file: PlanFile;
+    };
 }
 interface PlanFile {
     name: string;

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

@@ -17,8 +17,7 @@ export class PlansCommand extends BaseCommand {
             this.printPlans(files);
             return;
         }
-        const file = this.resolvePlanFile(target, files);
-        const plan = Plan.fromMarkdown(file.path);
+        const { plan, file } = this.resolvePlanFile(target, files);
         this.printPlanDetails(plan, file);
     }
     getPlanFiles() {
@@ -68,16 +67,17 @@ export class PlansCommand extends BaseCommand {
             const file = files[index - 1];
             if (!file)
                 throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
-            return file;
+            return { plan: Plan.fromMarkdown(file.path), file };
         }
         const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
         if (!plan?.filePath) {
             throw new Error(`Plan file not found: ${target}`);
         }
-        return {
+        const file = {
             name: path.basename(plan.filePath),
             path: plan.filePath,
             modifiedAt: statSync(plan.filePath).mtimeMs,
         };
+        return { plan, file };
     }
 }

package/dist/src/commands/recommended-models-command.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import { BaseCommand } from './base-command.js';
+export declare class RecommendedModelsCommand extends BaseCommand {
+    name: string;
+    description: string;
+    execute(): Promise<void>;
+    static register(program: Command): void;
+    static render(json?: boolean): string;
+}

package/dist/src/commands/recommended-models-command.js

@@ -0,0 +1,85 @@
+import chalk from 'chalk';
+import { ConfigParser, EXPLORBOT_ENV_VARS, MODEL_ROLES, PROVIDERS } from '../config.js';
+import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+const DESCRIPTION = 'Show the models recommended for every AI provider';
+const ROLES = {
+    model: { hint: 'fast', env: 'EXPLORBOT_AI_MODEL' },
+    visionModel: { hint: 'screenshots', env: 'EXPLORBOT_VISION_MODEL' },
+    agenticModel: { hint: 'smart', env: 'EXPLORBOT_AGENTIC_MODEL' },
+};
+const MODEL_ENV_VARS = MODEL_ROLES.map((role) => ROLES[role].env);
+export class RecommendedModelsCommand extends BaseCommand {
+    name = 'recommended-models';
+    description = DESCRIPTION;
+    async execute() {
+        tag('info').log(RecommendedModelsCommand.render());
+    }
+    static register(program) {
+        program
+            .command('recommended-models')
+            .description(DESCRIPTION)
+            .option('--json', 'Print the recommendations as JSON')
+            .action((options) => console.log(RecommendedModelsCommand.render(options.json)));
+    }
+    static render(json = false) {
+        const recommended = ConfigParser.recommendedModels();
+        if (json)
+            return JSON.stringify(recommended, null, 2);
+        const lines = [
+            chalk.bold('Export the provider key, then pick one of two ways to select models:'),
+            `  ${chalk.bold('EXPLORBOT_AI_PROVIDER')} — every role takes that provider's recommendation below`,
+            `  ${chalk.bold(MODEL_ENV_VARS.join(' + '))} — no provider variable, pin every role yourself as ${chalk.dim('provider/model-id')}`,
+            '',
+        ];
+        for (const [provider, roles] of Object.entries(recommended)) {
+            lines.push(chalk.bold.yellow(`${provider}:`));
+            const models = [];
+            for (const role of MODEL_ROLES) {
+                const label = `${role} (${ROLES[role].hint})`;
+                if (roles[role])
+                    models.push([label, roles[role]]);
+                if (!roles[role])
+                    models.push([label, chalk.dim('not served, pair with another provider')]);
+            }
+            lines.push(...renderSection('models', models, 2));
+            const envKey = PROVIDERS[provider]?.envKey;
+            if (!envKey) {
+                lines.push(`  ${chalk.dim('not bundled — import the provider in your config')}`, '');
+                continue;
+            }
+            const env = [
+                ['key', envKey],
+                ['provider', `EXPLORBOT_AI_PROVIDER=${provider}`],
+            ];
+            let label = 'or models';
+            for (const role of MODEL_ROLES) {
+                if (!roles[role])
+                    continue;
+                env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
+                label = '';
+            }
+            lines.push(...renderSection('env variables', env, 2));
+        }
+        const modelVars = ['EXPLORBOT_AI_PROVIDER', ...MODEL_ENV_VARS];
+        const current = [];
+        for (const variable of EXPLORBOT_ENV_VARS) {
+            if (!modelVars.includes(variable.name))
+                continue;
+            if (process.env[variable.name])
+                current.push([variable.name, process.env[variable.name]]);
+        }
+        for (const [provider, { envKey }] of Object.entries(PROVIDERS)) {
+            if (process.env[envKey])
+                current.push([envKey, chalk.dim(`set, ${provider} usable`)]);
+        }
+        if (!current.length)
+            lines.push(chalk.dim('Nothing set — export one of the variables above, or write models into your config'), '');
+        if (current.length)
+            lines.push(...renderSection('Currently set', current));
+        lines.push(chalk.bold('Example using OpenRouter:'), `  OPENROUTER_API_KEY=sk-... EXPLORBOT_AI_PROVIDER=openrouter ${getCliName()} <command>`);
+        return lines.join('\n');
+    }
+}

package/dist/src/config.d.ts

@@ -1,5 +1,6 @@
 import { type SiteRecord } from './global-config.js';
 export declare const PROVIDERS: Record<string, ProviderInfo>;
+export declare const MODEL_ROLES: ModelRole[];
 interface PlaywrightConfig {
     browser: 'chromium' | 'firefox' | 'webkit';
     url: string;
@@ -270,6 +271,7 @@ export declare class ConfigParser {
 }
 export declare function outputPath(...segments: string[]): string;
 export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
+export declare function missingModelRoles(provider: string): ModelRole[];
 export declare class ConfigMissingError extends Error {
 }
 export declare function envConfigRequested(): boolean;

package/dist/src/config.js

@@ -25,6 +25,7 @@ export const PROVIDERS = {
     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() },
 };
+export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
 const config = {
     playwright: {
@@ -458,6 +459,10 @@ export async function resolveModel(spec, role = 'model') {
     }
     return createModel(spec, modelId);
 }
+export function missingModelRoles(provider) {
+    const recommended = ConfigParser.recommendedModels()[provider] || {};
+    return MODEL_ROLES.filter((role) => !recommended[role]);
+}
 export class ConfigMissingError extends Error {
 }
 export function envConfigRequested() {
@@ -478,6 +483,7 @@ export function missingConfigMessage(configFile = 'explorbot.config.js') {
         EXPLORBOT_AI_PROVIDER=openrouter EXPLORBOT_URL=https://your-app.example.com ${cli} ...
 
     Providers: ${Object.keys(PROVIDERS).join(', ')}
+    See the models each one recommends: ${cli} recommended-models
   `;
 }
 export function modelName(model) {
@@ -511,8 +517,7 @@ export function configuredModels(ai) {
 export async function resolveConfigModels(ai) {
     if (!ai)
         return;
-    const roles = ['model', 'visionModel', 'agenticModel'];
-    for (const role of roles) {
+    for (const role of MODEL_ROLES) {
         if (typeof ai[role] === 'string')
             ai[role] = await resolveModel(ai[role], role);
     }

package/dist/src/experience-tracker.js

@@ -105,7 +105,7 @@ export class ExperienceTracker {
                 url: state.url ? extractStatePath(state.url) : '',
                 title: state.title,
             };
-            if (state.overlay.present && state.overlay.name) {
+            if (state.overlay.isOpen && state.overlay.name) {
                 frontmatter.region = state.overlay.name;
                 if (state.overlay.root)
                     frontmatter.root = state.overlay.root;

package/dist/src/explorbot.js

@@ -399,10 +399,10 @@ export class ExplorBot {
         return plan;
     }
     loadPlans(filename) {
-        const plan = Plan.loadFromFile(filename, this.getPlansDir());
-        if (!plan?.filePath)
+        const filePath = Plan.resolveFile(filename, this.getPlansDir());
+        if (!filePath)
             throw new Error(`Plan file not found: ${filename}`);
-        return parsePlansFromMarkdown(plan.filePath);
+        return parsePlansFromMarkdown(filePath);
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;

package/dist/src/global-config.d.ts

@@ -6,6 +6,8 @@ export declare function isGlobalConfigPath(configPath: string): boolean;
 export declare function sitesDir(): string;
 export declare function siteFolderName(url: string): string;
 export declare function listSites(): SiteRecord[];
+export declare function findSiteWith(subpath: string): SiteRecord | undefined;
+export declare function listSitePlanDirs(): string[];
 export declare function registerSite(baseUrl: string): SiteRecord;
 export declare function resolveSiteTarget(target?: string, defaultBaseUrl?: string): SiteTarget;
 interface SiteRecord {

package/dist/src/global-config.js

@@ -38,6 +38,12 @@ export function listSites() {
         .filter((site) => !!site)
         .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
+export function findSiteWith(subpath) {
+    return listSites().find((site) => existsSync(join(site.dir, subpath)));
+}
+export function listSitePlanDirs() {
+    return listSites().map((site) => join(site.dir, 'output', 'plans'));
+}
 export function registerSite(baseUrl) {
     const folder = siteFolderName(baseUrl);
     const dir = join(sitesDir(), folder);