explorbot 0.3.5 → 0.4.1

package/dist/src/commands/options/ws-option.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { BaseOption } from './base-option.js';
+export declare class WsOption extends BaseOption {
+    flags: string;
+    description: string;
+    apply(options: Record<string, any>, command: Command): void;
+}

package/dist/src/commands/options/ws-option.js

@@ -0,0 +1,21 @@
+import { remote } from '../../remote.js';
+import { BaseOption } from './base-option.js';
+export class WsOption extends BaseOption {
+    flags = '--ws <url>';
+    description = 'Stream this run to a remote UI over WebSocket';
+    apply(options, command) {
+        const url = options.ws || process.env.EXPLORBOT_WS_URL;
+        if (!url)
+            return;
+        remote.attach(String(url), commandPath(command));
+    }
+}
+function commandPath(command) {
+    const parts = [];
+    let node = command;
+    while (node) {
+        parts.unshift(node.name());
+        node = node.parent;
+    }
+    return parts.slice(1).join(' ') || parts.join(' ');
+}

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

@@ -70,14 +70,14 @@ export class PlansCommand extends BaseCommand {
                 throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
             return file;
         }
-        const resolved = this.explorBot.resolvePlanPath(target);
-        if (!existsSync(resolved)) {
-            throw new Error(`Plan file not found: ${resolved}`);
+        const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
+        if (!plan?.filePath) {
+            throw new Error(`Plan file not found: ${target}`);
         }
         return {
-            name: path.basename(resolved),
-            path: resolved,
-            modifiedAt: statSync(resolved).mtimeMs,
+            name: path.basename(plan.filePath),
+            path: plan.filePath,
+            modifiedAt: statSync(plan.filePath).mtimeMs,
         };
     }
 }

package/dist/src/config.d.ts

@@ -255,6 +255,7 @@ export declare class ConfigParser {
     static getTestDirectories(): string[];
     static cleanupAllTestDirectories(): void;
     enterGlobalMode(config: ExplorbotConfig, target: string | null): void;
+    applyEnvSpec(config: ExplorbotConfig): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;

package/dist/src/config.js

@@ -46,8 +46,10 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
     { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
     { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
+    { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
     { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
     { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
+    { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
 export class ConfigParser {
     static instance;
@@ -128,6 +130,7 @@ export class ConfigParser {
             if (resolvedPath && isGlobalConfigPath(resolvedPath)) {
                 this.enterGlobalMode(this.config, target);
             }
+            this.applyEnvSpec(this.config);
             // Restore original directory after successful config load
             if (options?.path && originalCwd !== process.cwd()) {
                 process.chdir(originalCwd);
@@ -268,8 +271,17 @@ export class ConfigParser {
         this.siteStartPath = site.path;
         config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
         config.playwright = { ...config.playwright, browser: config.playwright?.browser || 'chromium', url: site.baseUrl };
+        materializeKnowledge(this.site.dir);
         log(`Global mode: ${site.baseUrl} stored in ${this.site.dir}`);
     }
+    applyEnvSpec(config) {
+        const spec = process.env.EXPLORBOT_SPEC;
+        if (!spec)
+            return;
+        if (!config.dirs)
+            config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+        config.dirs.spec = spec;
+    }
     async buildEnvConfig(baseUrl, outputRoot) {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;

package/dist/src/experience-tracker.js

@@ -105,6 +105,11 @@ export class ExperienceTracker {
                 url: state.url ? extractStatePath(state.url) : '',
                 title: state.title,
             };
+            if (state.overlay.present && state.overlay.name) {
+                frontmatter.region = state.overlay.name;
+                if (state.overlay.root)
+                    frontmatter.root = state.overlay.root;
+            }
             this.writeExperienceFile(stateHash, '', frontmatter);
         }
         return filePath;

package/dist/src/explorbot.d.ts

@@ -114,7 +114,6 @@ export declare class ExplorBot {
     savePlan(filename?: string): string | null;
     savePlans(plans: Plan[], filename?: string): string | null;
     generatePlanFilename(feature?: string): string;
-    resolvePlanPath(filename: string): string;
     loadPlan(filename: string): Plan;
     loadPlans(filename: string): Plan[];
     setCurrentPlan(plan?: Plan): void;

package/dist/src/explorbot.js

@@ -132,7 +132,7 @@ export class ExplorBot {
         return this.explorer;
     }
     knowledgeTracker() {
-        return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
+        return (this._knowledgeTracker ||= new KnowledgeTracker({ applicationSpec: this.options.applicationSpec }));
     }
     experienceTracker() {
         return (this._experienceTracker ||= new ExperienceTracker(this.knowledgeTracker()));
@@ -290,14 +290,22 @@ export class ExplorBot {
                     return null;
                 }
             };
-            const cookieProvider = async () => {
-                const cookies = await this.explorer.withPage((page) => page.context().cookies()).catch(() => []);
-                if (!cookies.length)
-                    return {};
-                return { Cookie: cookies.map((c) => `${c.name}=${c.value}`).join('; ') };
+            const browserHeaderProvider = async () => {
+                const session = await this.explorer
+                    .withPage(async (page) => ({
+                    cookies: await page.context().cookies(baseEndpoint),
+                    csrf: await page.evaluate(() => document.querySelector('meta[name="csrf-token"]')?.getAttribute('content') || '').catch(() => ''),
+                }))
+                    .catch(() => ({ cookies: [], csrf: '' }));
+                const headers = {};
+                if (session.cookies.length)
+                    headers.Cookie = session.cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+                if (session.csrf)
+                    headers['x-csrf-token'] = session.csrf;
+                return headers;
             };
             this.agents.fisherman = this.createAgent(({ ai }) => {
-                return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, cookieProvider, configHeaders, hasApiConfig);
+                return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, browserHeaderProvider, configHeaders, hasApiConfig);
             });
         }
         return this.agents.fisherman;
@@ -383,39 +391,18 @@ export class ExplorBot {
             return urlPart.slice(0, 256 - suffix.length) + suffix;
         return urlPart + featurePart.slice(0, maxFeatureLen) + suffix;
     }
-    resolvePlanPath(filename) {
-        let planPath = filename;
-        if (path.isAbsolute(filename)) {
-            if (!existsSync(planPath) && !filename.endsWith('.md')) {
-                planPath = `${filename}.md`;
-            }
-        }
-        else if (existsSync(filename) || existsSync(`${filename}.md`)) {
-            planPath = existsSync(filename) ? filename : `${filename}.md`;
-        }
-        else {
-            const plansDir = this.getPlansDir();
-            planPath = path.join(plansDir, filename);
-            if (!existsSync(planPath) && !filename.endsWith('.md')) {
-                planPath = path.join(plansDir, `${filename}.md`);
-            }
-        }
-        return planPath;
-    }
     loadPlan(filename) {
-        const planPath = this.resolvePlanPath(filename);
-        if (!existsSync(planPath)) {
-            throw new Error(`Plan file not found: ${planPath}`);
-        }
-        this.setCurrentPlan(Plan.fromMarkdown(planPath));
-        return this.currentPlan;
+        const plan = Plan.loadFromFile(filename, this.getPlansDir());
+        if (!plan)
+            throw new Error(`Plan file not found: ${filename}`);
+        this.setCurrentPlan(plan);
+        return plan;
     }
     loadPlans(filename) {
-        const planPath = this.resolvePlanPath(filename);
-        if (!existsSync(planPath)) {
-            throw new Error(`Plan file not found: ${planPath}`);
-        }
-        return parsePlansFromMarkdown(planPath);
+        const plan = Plan.loadFromFile(filename, this.getPlansDir());
+        if (!plan?.filePath)
+            throw new Error(`Plan file not found: ${filename}`);
+        return parsePlansFromMarkdown(plan.filePath);
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;

package/dist/src/knowledge-tracker.d.ts

@@ -1,20 +1,19 @@
 import { ActionResult } from './action-result.js';
 import { ApplicationSpec } from './application-spec.js';
-export interface Knowledge {
-    filePath: string;
-    url: string;
-    content: string;
-    [key: string]: any;
-}
 export declare class KnowledgeTracker {
     knowledgeDir: string;
     knowledgeFiles: Knowledge[];
+    sessionKnowledge: Knowledge[];
     isLoaded: boolean;
     applicationSpec?: ApplicationSpec;
-    constructor(applicationSpecPath?: string);
+    static appendSessionKnowledge(text: string): void;
+    static resetSessionKnowledge(): void;
+    constructor(options?: KnowledgeTrackerOptions);
     loadKnowledgeFiles(): void;
     getRelevantKnowledge(state: ActionResult): Knowledge[];
+    getEndpointKnowledge(endpoint: string): Knowledge[];
     renderRelevantKnowledge(state: ActionResult): string;
+    renderEndpointKnowledge(endpoint: string): string;
     renderRelevantContext(state: ActionResult): string;
     renderApplicationSpec(state: ActionResult): string;
     addKnowledge(urlPattern: string, description: string, opts?: {
@@ -36,4 +35,18 @@ export declare class KnowledgeTracker {
     getMatchingKnowledge(url: string): Knowledge[];
     normalizeUrl(url: string): string;
     getStateParameters(state: ActionResult, keys: string[]): Record<string, any>;
+    allKnowledge(): Knowledge[];
+    toKnowledge(filePath: string, data: Record<string, any>, content: string): Knowledge;
+    renderKnowledge(knowledgeFiles: Knowledge[], scope: string): string;
+}
+export interface Knowledge {
+    filePath: string;
+    url?: string;
+    endpoint?: string;
+    content: string;
+    [key: string]: any;
+}
+export interface KnowledgeTrackerOptions {
+    applicationSpec?: string;
+    knowledgeDir?: string;
 }

package/dist/src/knowledge-tracker.js

@@ -11,61 +11,67 @@ import { loadMarkdownFiles } from './utils/markdown-files.js';
 import { mdq } from './utils/markdown-query.js';
 import { isSecretName, registerSecret } from './utils/secrets.js';
 import { slugify } from './utils/strings.js';
+import { extractStatePath, matchesUrl } from './utils/url-matcher.js';
 const debugLog = createDebug('explorbot:knowledge-tracker');
+const sessionEntries = [];
 export class KnowledgeTracker {
     knowledgeDir;
     knowledgeFiles = [];
+    sessionKnowledge = [];
     isLoaded = false;
     applicationSpec;
-    constructor(applicationSpecPath) {
-        const configParser = ConfigParser.getInstance();
-        const config = configParser.getConfig();
-        this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+    static appendSessionKnowledge(text) {
+        sessionEntries.push(text);
+    }
+    static resetSessionKnowledge() {
+        sessionEntries.length = 0;
+    }
+    constructor(options = {}) {
+        let knowledgeDir = options.knowledgeDir;
+        let specPath = options.applicationSpec;
+        if (!knowledgeDir) {
+            const configParser = ConfigParser.getInstance();
+            const config = configParser.getConfig();
+            knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+            specPath ||= config.dirs?.spec;
+        }
+        this.knowledgeDir = knowledgeDir;
         if (!existsSync(this.knowledgeDir)) {
             mkdirSync(this.knowledgeDir, { recursive: true });
         }
-        const specPath = applicationSpecPath || config.dirs?.spec;
         if (specPath) {
             this.applicationSpec = new ApplicationSpec(specPath);
             tag('info').log(`Loaded application spec with ${this.applicationSpec.pageCount} documented pages`);
         }
+        this.sessionKnowledge = sessionEntries.map((entry, index) => {
+            const parsed = matter(entry);
+            debugLog(`Session knowledge #${index + 1}`);
+            return this.toKnowledge(`--knowledge #${index + 1}`, parsed.data, parsed.content.trim());
+        });
     }
     loadKnowledgeFiles() {
         if (this.isLoaded)
             return;
         this.knowledgeFiles = [];
         for (const entry of loadMarkdownFiles(this.knowledgeDir, { recursive: true })) {
-            this.knowledgeFiles.push({
-                filePath: entry.filePath,
-                url: entry.data.url || entry.data.path || '*',
-                content: this.interpolateVars(entry.content),
-                ...entry.data,
-            });
+            this.knowledgeFiles.push(this.toKnowledge(entry.filePath, entry.data, entry.content));
         }
         this.isLoaded = true;
     }
     getRelevantKnowledge(state) {
         this.loadKnowledgeFiles();
-        return this.knowledgeFiles.filter((knowledge) => {
-            return state.isMatchedBy(knowledge);
-        });
+        return this.allKnowledge().filter((knowledge) => knowledge.url && state.isMatchedBy(knowledge));
+    }
+    getEndpointKnowledge(endpoint) {
+        this.loadKnowledgeFiles();
+        const path = extractStatePath(endpoint);
+        return this.allKnowledge().filter((knowledge) => knowledge.endpoint && matchesUrl(knowledge.endpoint, path));
     }
     renderRelevantKnowledge(state) {
-        const knowledgeFiles = this.getRelevantKnowledge(state);
-        if (knowledgeFiles.length === 0)
-            return '';
-        const knowledgeContent = knowledgeFiles
-            .map((k) => k.content)
-            .filter((k) => !!k)
-            .join('\n\n');
-        tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
-        return dedent `
-      <knowledge>
-      Here is relevant knowledge for this page:
-
-      ${knowledgeContent}
-      </knowledge>
-    `;
+        return this.renderKnowledge(this.getRelevantKnowledge(state), 'page');
+    }
+    renderEndpointKnowledge(endpoint) {
+        return this.renderKnowledge(this.getEndpointKnowledge(endpoint), 'endpoint');
     }
     renderRelevantContext(state) {
         return [this.renderRelevantKnowledge(state), this.renderApplicationSpec(state)].filter(Boolean).join('\n\n');
@@ -151,7 +157,7 @@ export class KnowledgeTracker {
     }
     getExistingUrls() {
         this.loadKnowledgeFiles();
-        return this.knowledgeFiles.map((knowledge) => knowledge.url).filter((url) => url && url !== '*');
+        return this.knowledgeFiles.map((knowledge) => knowledge.url || '').filter((url) => url && url !== '*');
     }
     getKnowledgeForUrl(urlPattern) {
         this.loadKnowledgeFiles();
@@ -164,7 +170,7 @@ export class KnowledgeTracker {
             const content = knowledge.content.trim();
             const firstLine = mdq(content).meta()[0]?.text.split('\n')[0]?.trim() || '';
             return {
-                url: knowledge.url,
+                url: knowledge.url || knowledge.endpoint || '',
                 firstLine,
                 filePath: knowledge.filePath,
             };
@@ -194,4 +200,36 @@ export class KnowledgeTracker {
         }
         return result;
     }
+    allKnowledge() {
+        return [...this.knowledgeFiles, ...this.sessionKnowledge];
+    }
+    toKnowledge(filePath, data, content) {
+        const knowledge = {
+            ...data,
+            filePath,
+            url: data.url || data.path,
+            content: this.interpolateVars(content),
+        };
+        if (!data.url && !data.path && !data.endpoint) {
+            knowledge.url = '*';
+            knowledge.endpoint = '*';
+        }
+        return knowledge;
+    }
+    renderKnowledge(knowledgeFiles, scope) {
+        if (knowledgeFiles.length === 0)
+            return '';
+        const knowledgeContent = knowledgeFiles
+            .map((k) => k.content)
+            .filter((k) => !!k)
+            .join('\n\n');
+        tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
+        return dedent `
+      <knowledge>
+      Here is relevant knowledge for this ${scope}:
+
+      ${knowledgeContent}
+      </knowledge>
+    `;
+    }
 }

package/dist/src/remote.d.ts

@@ -1,4 +1,3 @@
-import type { Command } from 'commander';
 import { type ActivityEntry } from './activity.js';
 import { type LogDestination, type TaggedLogEntry } from './utils/logger.js';
 /**
@@ -19,7 +18,6 @@ export declare class Remote implements LogDestination {
     asks: Map<string, (value: string | null) => void>;
     askCounter: number;
     lastActivity: string | null;
-    registerOption(program: Command): void;
     attach(url: string, command: string): void;
     isAttached(): boolean;
     send(type: string, data?: Record<string, unknown>): void;
@@ -42,7 +40,6 @@ export declare class Remote implements LogDestination {
      *  nothing — so skip repeats, the priming null included. */
     reportActivity(activity: ActivityEntry | null): void;
     errorOf(args: any[] | undefined): string | undefined;
-    commandPath(command: Command): string;
 }
 export declare const remote: Remote;
 /** Whatever the run wants to say. Not a schema — the UI renders what it knows

package/dist/src/remote.js

@@ -26,15 +26,6 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
-    registerOption(program) {
-        program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
-        program.hook('preAction', (_thisCommand, actionCommand) => {
-            const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
-            if (!url)
-                return;
-            this.attach(String(url), this.commandPath(actionCommand));
-        });
-    }
     attach(url, command) {
         if (this.url)
             return;
@@ -222,14 +213,5 @@ export class Remote {
             return failure.message;
         return undefined;
     }
-    commandPath(command) {
-        const parts = [];
-        let node = command;
-        while (node) {
-            parts.unshift(node.name());
-            node = node.parent;
-        }
-        return parts.slice(1).join(' ') || parts.join(' ');
-    }
 }
 export const remote = new Remote();

package/dist/src/state-manager.d.ts

@@ -42,6 +42,10 @@ export interface WebPageState {
     links?: Link[];
     verifications?: Record<string, boolean>;
     overlay?: Overlay;
+    /** Region name, the persisted scalar form of overlay.name used in experience frontmatter */
+    region?: string;
+    /** Region root selector, the persisted scalar form of overlay.root used in experience frontmatter */
+    root?: string;
 }
 export interface StateTransition {
     /** Previous state (null if this is the first state) */
@@ -91,7 +95,7 @@ export declare class StateManager {
      * Update state from basic data (for navigation events)
      */
     updateStateFromBasic(url: string, title?: string, trigger?: 'manual' | 'navigation' | 'automatic'): WebPageState;
-    hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
+    hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean;
     /**
      * Generate a basic hash for state comparison
      */

package/dist/src/state-manager.js

@@ -41,7 +41,10 @@ export class StateManager {
      */
     emitStateChange(event) {
         const state = event.toState;
-        tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+        const payload = { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 };
+        if (state.overlay?.present)
+            payload.region = state.overlay.name || state.overlay.type;
+        tag('data').log('state', payload);
         this.stateChangeListeners.forEach((listener) => {
             try {
                 listener(event);
@@ -63,8 +66,8 @@ export class StateManager {
         if (newState.url)
             this.allVisitedUrls.add(normalizeUrl(newState.url));
         const hashChanged = actionResult.hash !== previousHash;
-        const dialogOpened = !hashChanged && this.hasDialogAppeared(previousState, newState);
-        if (hashChanged || dialogOpened) {
+        const regionAppeared = !hashChanged && this.hasRegionAppeared(previousState, newState);
+        if (hashChanged || regionAppeared) {
             const transition = {
                 fromState: previousState,
                 toState: newState,
@@ -74,8 +77,8 @@ export class StateManager {
             };
             this.stateHistory.push(transition);
             this.emitStateChange(transition);
-            if (dialogOpened) {
-                debugLog('State change detected: modal dialog appeared');
+            if (regionAppeared) {
+                debugLog('State change detected: region of interest appeared');
             }
         }
         debugLog(`State updated: ${this.currentState.url} (${this.currentState.hash})`);
@@ -113,10 +116,10 @@ export class StateManager {
         debugLog(`State updated from navigation: ${this.currentState.url} (${this.currentState.hash})`);
         return newState;
     }
-    hasDialogAppeared(previousState, newState) {
+    hasRegionAppeared(previousState, newState) {
         const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
         const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
-        return !prevFocus.detected && newFocus.detected;
+        return !prevFocus.present && newFocus.present;
     }
     /**
      * Generate a basic hash for state comparison

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

@@ -129,6 +129,7 @@ export declare class Plan {
     title: string;
     tests: Test[];
     url?: string;
+    filePath?: string;
     iteration: number;
     parentPlan?: Plan;
     changeListeners: PlanChangeListener[];
@@ -141,10 +142,12 @@ export declare class Plan {
     getAllTests(): Test[];
     listTests(): Test[];
     getPendingTests(): Test[];
+    get startUrl(): string | undefined;
     get isComplete(): boolean;
     get allSuccessful(): boolean;
     get allFailed(): boolean;
     updateStatus(): void;
+    static loadFromFile(file: string, plansDir?: string): Plan | null;
     static fromMarkdown(filePath: string): Plan;
     saveToMarkdown(filePath: string): void;
     static saveMultipleToMarkdown(plans: Plan[], filePath: string): void;

package/dist/src/test-plan.js

@@ -1,4 +1,7 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { listSites } from "./global-config.js";
 import { tag } from "./utils/logger.js";
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from "./utils/test-plan-markdown.js";
 import { uniqSessionName } from "./utils/unique-names.js";
@@ -320,10 +323,12 @@ export class Test extends Task {
             .sort((a, b) => a.timestamp - b.timestamp);
     }
 }
+const SITE_PLANS_DIR = ['output', 'plans'];
 export class Plan {
     title;
     tests = [];
     url;
+    filePath;
     iteration = 0;
     parentPlan;
     changeListeners = [];
@@ -380,6 +385,9 @@ export class Plan {
     getPendingTests() {
         return this.tests.filter((test) => test.status === 'pending' && test.enabled);
     }
+    get startUrl() {
+        return this.url || this.tests[0]?.startUrl;
+    }
     get isComplete() {
         return this.tests.length > 0 && this.tests.every((test) => test.hasFinished);
     }
@@ -390,6 +398,25 @@ export class Plan {
         return this.tests.length > 0 && this.tests.every((test) => test.hasFailed);
     }
     updateStatus() { }
+    static loadFromFile(file, plansDir) {
+        const names = [file];
+        if (!file.endsWith('.md'))
+            names.push(`${file}.md`);
+        const dirs = [process.cwd()];
+        if (plansDir)
+            dirs.push(plansDir);
+        if (!plansDir)
+            dirs.push(...listSites().map((site) => path.join(site.dir, ...SITE_PLANS_DIR)));
+        for (const dir of dirs) {
+            const filePath = names.map((name) => path.resolve(dir, name)).find(existsSync);
+            if (!filePath)
+                continue;
+            const loaded = parsePlanFromMarkdown(filePath);
+            loaded.filePath = filePath;
+            return loaded;
+        }
+        return null;
+    }
     static fromMarkdown(filePath) {
         return parsePlanFromMarkdown(filePath);
     }

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

@@ -1,6 +1,6 @@
 export interface FocusAreaResult {
     detected: boolean;
-    type: 'dialog' | 'modal' | null;
+    type: 'modal' | null;
     name: string | null;
 }
 export type ValueOffload = (value: string) => string | undefined;