explorbot 0.3.5 → 0.4.1

package/src/knowledge-tracker.ts

@@ -11,36 +11,54 @@ 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');
 
-export interface Knowledge {
-  filePath: string;
-  url: string;
-  content: string;
-  [key: string]: any;
-}
+const sessionEntries: string[] = [];
 
 export class KnowledgeTracker {
   private knowledgeDir: string;
   private knowledgeFiles: Knowledge[] = [];
+  private sessionKnowledge: Knowledge[] = [];
   private isLoaded = false;
   private applicationSpec?: ApplicationSpec;
 
-  constructor(applicationSpecPath?: string) {
-    const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
+  static appendSessionKnowledge(text: string): void {
+    sessionEntries.push(text);
+  }
+
+  static resetSessionKnowledge(): void {
+    sessionEntries.length = 0;
+  }
+
+  constructor(options: KnowledgeTrackerOptions = {}) {
+    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());
+    });
   }
 
   private loadKnowledgeFiles(): void {
@@ -49,12 +67,7 @@ export class KnowledgeTracker {
     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;
@@ -63,28 +76,22 @@ export class KnowledgeTracker {
   getRelevantKnowledge(state: ActionResult): Knowledge[] {
     this.loadKnowledgeFiles();
 
-    return this.knowledgeFiles.filter((knowledge) => {
-      return state.isMatchedBy(knowledge);
-    });
+    return this.allKnowledge().filter((knowledge) => knowledge.url && state.isMatchedBy(knowledge));
   }
 
-  renderRelevantKnowledge(state: ActionResult): string {
-    const knowledgeFiles = this.getRelevantKnowledge(state);
-    if (knowledgeFiles.length === 0) return '';
+  getEndpointKnowledge(endpoint: string): Knowledge[] {
+    this.loadKnowledgeFiles();
+    const path = extractStatePath(endpoint);
 
-    const knowledgeContent = knowledgeFiles
-      .map((k) => k.content)
-      .filter((k) => !!k)
-      .join('\n\n');
+    return this.allKnowledge().filter((knowledge) => knowledge.endpoint && matchesUrl(knowledge.endpoint, path));
+  }
 
-    tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
-    return dedent`
-      <knowledge>
-      Here is relevant knowledge for this page:
+  renderRelevantKnowledge(state: ActionResult): string {
+    return this.renderKnowledge(this.getRelevantKnowledge(state), 'page');
+  }
 
-      ${knowledgeContent}
-      </knowledge>
-    `;
+  renderEndpointKnowledge(endpoint: string): string {
+    return this.renderKnowledge(this.getEndpointKnowledge(endpoint), 'endpoint');
   }
 
   renderRelevantContext(state: ActionResult): string {
@@ -188,7 +195,7 @@ export class KnowledgeTracker {
   getExistingUrls(): string[] {
     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: string): string[] {
@@ -205,7 +212,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,
       };
@@ -242,4 +249,55 @@ export class KnowledgeTracker {
 
     return result;
   }
+
+  private allKnowledge(): Knowledge[] {
+    return [...this.knowledgeFiles, ...this.sessionKnowledge];
+  }
+
+  private toKnowledge(filePath: string, data: Record<string, any>, content: string): Knowledge {
+    const knowledge: 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;
+  }
+
+  private renderKnowledge(knowledgeFiles: Knowledge[], scope: string): string {
+    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>
+    `;
+  }
+}
+
+export interface Knowledge {
+  filePath: string;
+  url?: string;
+  endpoint?: string;
+  content: string;
+  [key: string]: any;
+}
+
+export interface KnowledgeTrackerOptions {
+  applicationSpec?: string;
+  knowledgeDir?: string;
 }

package/src/remote.ts

@@ -1,4 +1,3 @@
-import type { Command } from 'commander';
 import stripAnsi from 'strip-ansi';
 import { type ActivityEntry, addActivityListener } from './activity.ts';
 import { executionController } from './execution-controller.ts';
@@ -30,15 +29,6 @@ export class Remote implements LogDestination {
   private askCounter = 0;
   private lastActivity: string | null = null;
 
-  registerOption(program: Command): void {
-    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: string, command: string): void {
     if (this.url) return;
     this.url = url;
@@ -225,16 +215,6 @@ export class Remote implements LogDestination {
     if (typeof failure.message === 'string') return failure.message;
     return undefined;
   }
-
-  private commandPath(command: Command): string {
-    const parts: string[] = [];
-    let node: Command | null = command;
-    while (node) {
-      parts.unshift(node.name());
-      node = node.parent;
-    }
-    return parts.slice(1).join(' ') || parts.join(' ');
-  }
 }
 
 export const remote = new Remote();

package/src/state-manager.ts

@@ -50,6 +50,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 {
@@ -119,7 +123,9 @@ export class StateManager {
    */
   private emitStateChange(event: StateTransition): void {
     const state = event.toState;
-    tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+    const payload: Record<string, unknown> = { 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 {
@@ -143,9 +149,9 @@ export class StateManager {
     if (newState.url) this.allVisitedUrls.add(normalizeUrl(newState.url));
 
     const hashChanged = actionResult.hash !== previousHash;
-    const dialogOpened = !hashChanged && this.hasDialogAppeared(previousState, newState);
+    const regionAppeared = !hashChanged && this.hasRegionAppeared(previousState, newState);
 
-    if (hashChanged || dialogOpened) {
+    if (hashChanged || regionAppeared) {
       const transition: StateTransition = {
         fromState: previousState,
         toState: newState,
@@ -156,8 +162,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');
       }
     }
 
@@ -206,10 +212,10 @@ export class StateManager {
     return newState;
   }
 
-  private hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
+  private hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
     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;
   }
 
   /**

package/src/test-plan.ts

@@ -1,6 +1,9 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import figures from 'figures';
 import type { ActionResult } from './action-result.ts';
+import { listSites } from './global-config.ts';
 import { WebPageState } from './state-manager.ts';
 import { tag } from './utils/logger.ts';
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from './utils/test-plan-markdown.ts';
@@ -388,12 +391,15 @@ export class Test extends Task {
   }
 }
 
+const SITE_PLANS_DIR = ['output', 'plans'];
+
 type PlanChangeListener = (tests: Test[]) => void;
 
 export class Plan {
   title: string;
   tests: Test[] = [];
   url?: string;
+  filePath?: string;
   iteration = 0;
   parentPlan?: Plan;
   private changeListeners: PlanChangeListener[] = [];
@@ -455,6 +461,10 @@ export class Plan {
     return this.tests.filter((test) => test.status === 'pending' && test.enabled);
   }
 
+  get startUrl(): string | undefined {
+    return this.url || this.tests[0]?.startUrl;
+  }
+
   get isComplete(): boolean {
     return this.tests.length > 0 && this.tests.every((test) => test.hasFinished);
   }
@@ -469,6 +479,25 @@ export class Plan {
 
   updateStatus(): void {}
 
+  static loadFromFile(file: string, plansDir?: string): Plan | null {
+    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: string): Plan {
     return parsePlanFromMarkdown(filePath);
   }

package/src/utils/aria.ts

@@ -470,51 +470,20 @@ const formatDiff = (added: string[], removed: string[], toggled: string[], typed
 
 export interface FocusAreaResult {
   detected: boolean;
-  type: 'dialog' | 'modal' | null;
+  type: 'modal' | null;
   name: string | null;
 }
 
-const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
-
-const findOverlayByCloseButton = (nodeList: AriaNode[]): FocusAreaResult | null => {
-  const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
-  if (closeIdx !== -1) {
-    let heading: AriaNode | undefined;
-    for (let i = closeIdx - 1; i >= 0; i--) {
-      if (nodeList[i].role === 'heading' && nodeList[i].name) {
-        heading = nodeList[i];
-        break;
-      }
-    }
-    if (!heading) {
-      for (let i = closeIdx + 1; i < nodeList.length; i++) {
-        if (nodeList[i].role === 'heading' && nodeList[i].name) {
-          heading = nodeList[i];
-          break;
-        }
-      }
-    }
-    return { detected: true, type: 'dialog', name: heading?.name || null };
-  }
-  for (const node of nodeList) {
-    const inner = findOverlayByCloseButton(node.children);
-    if (inner) return inner;
-  }
-  return null;
-};
-
 const findDialogOrModal = (nodes: AriaNode[]): FocusAreaResult | null => {
+  let topmost: FocusAreaResult | null = null;
   for (const node of nodes) {
-    if (node.role === 'dialog' || node.role === 'alertdialog') {
-      return { detected: true, type: 'dialog', name: node.name || null };
-    }
-    if (node.attributes.modal === true || node.attributes.modal === 'true') {
-      return { detected: true, type: 'modal', name: node.name || null };
+    if (node.role === 'dialog' || node.role === 'alertdialog' || node.attributes.modal === true || node.attributes.modal === 'true') {
+      topmost = { detected: true, type: 'modal', name: node.name || null };
     }
     const child = findDialogOrModal(node.children);
-    if (child) return child;
+    if (child) topmost = child;
   }
-  return null;
+  return topmost;
 };
 
 // ─────────────────────────────────────────────────────────────────
@@ -561,13 +530,7 @@ export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
   tree = unwrapIgnored(tree);
   tree = dropEmpty(tree, { keepNamed: true });
 
-  const direct = findDialogOrModal(tree);
-  if (direct) return direct;
-
-  const fallback = findOverlayByCloseButton(tree);
-  if (fallback?.name) return fallback;
-
-  return { detected: false, type: null, name: null };
+  return findDialogOrModal(tree) ?? { detected: false, type: null, name: null };
 };
 
 export const collectInteractiveNodes = (snapshot: string | null): Array<Record<string, unknown>> => {

package/src/utils/html-diff.ts

@@ -7,8 +7,10 @@ import { isDynamicId, isGenericClass } from './xpath.ts';
 export interface HtmlDiffPart {
   container: string;
   subtree: string;
+  rawSize: number;
   added: string[];
   removed: string[];
+  appearedSelector?: string;
 }
 
 export interface HtmlDiffResult {
@@ -16,6 +18,7 @@ export interface HtmlDiffResult {
   added: string[];
   removed: string[];
   similarity: number;
+  pageSize: number;
   summary: string;
   messages: string[];
 }
@@ -30,6 +33,9 @@ interface HtmlNode {
 
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 
+const SHELL_RATIO = 0.8;
+const ROOT_CONTENT_RATIO = 0.8;
+
 const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
@@ -211,7 +217,12 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
 
   const originalMap = collectElementMap(originalDocument);
   const modifiedMap = collectElementMap(modifiedDocument);
-  const parts = await buildDiffParts(originalMap, modifiedMap);
+
+  const modifiedBody = findBodyElement(modifiedDocument);
+  let pageSize = modifiedHtml.length;
+  if (modifiedBody) pageSize = serializeNode(modifiedBody).length;
+
+  const parts = await buildDiffParts(originalMap, modifiedMap, pageSize);
 
   const structuralAdditions = parts.flatMap((p) => p.added.filter((a) => a.startsWith('ELEMENT:')));
   const allAdded = [...added, ...structuralAdditions];
@@ -223,11 +234,16 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
     added: allAdded,
     removed,
     similarity,
+    pageSize,
     summary,
     messages: collectMessages(originalMap, modifiedMap, allAdded),
   };
 }
 
+function serializeNode(node: parse5TreeAdapter.Node): string {
+  return serialize({ childNodes: [node], nodeName: '#document-fragment' } as any);
+}
+
 /**
  * Text the app announced while the page stayed the same: live region content first, then any other text that appeared.
  */
@@ -492,14 +508,14 @@ function buildContainerSelector(element: ElementNode, allElements: NodeMap): str
   return matchCount === 1 ? selector : null;
 }
 
-function pathToXPath(treePath: string): string {
+export function pathToXPath(treePath: string): string {
   const parts = treePath.split('/');
   const bodyIdx = parts.findIndex((p) => p.startsWith('body'));
   if (bodyIdx === -1) return `//${parts.join('/')}`;
   return `//body/${parts.slice(bodyIdx + 1).join('/')}`;
 }
 
-function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifiedMap: NodeMap): { path: string; selector: string } {
+function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifiedMap: NodeMap, pageSize: number): { path: string; selector: string } {
   const segments = topLevelPath.split('/');
 
   for (let i = segments.length - 2; i >= 1; i--) {
@@ -508,6 +524,7 @@ function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifie
     if (!originalMap.has(candidatePath) || !modifiedMap.has(candidatePath)) continue;
 
     const element = modifiedMap.get(candidatePath)!;
+    if (pageSize > 0 && serializeNode(element).length >= SHELL_RATIO * pageSize) break;
     const css = buildContainerSelector(element, modifiedMap);
     if (css) return { path: candidatePath, selector: css };
     return { path: candidatePath, selector: pathToXPath(candidatePath) };
@@ -516,7 +533,29 @@ function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifie
   return { path: 'html[1]/body[1]', selector: 'body' };
 }
 
-async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promise<HtmlDiffPart[]> {
+function dominantChild(element: ElementNode): ElementNode | null {
+  const children = (element.childNodes ?? []).filter((child): child is ElementNode => 'tagName' in child && !!child.tagName);
+  if (children.length === 0) return null;
+  if (children.length === 1) return children[0];
+  const parentSize = serializeNode(element).length;
+  if (!parentSize) return null;
+  for (const child of children) {
+    if (serializeNode(child).length >= ROOT_CONTENT_RATIO * parentSize) return child;
+  }
+  return null;
+}
+
+function semanticSelectorFor(element: ElementNode, allElements: NodeMap): string | undefined {
+  let current: ElementNode | null = element;
+  while (current) {
+    const selector = buildContainerSelector(current, allElements);
+    if (selector) return selector;
+    current = dominantChild(current);
+  }
+  return undefined;
+}
+
+async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap, pageSize: number): Promise<HtmlDiffPart[]> {
   const addedPaths: string[] = [];
   const changedPaths: string[] = [];
 
@@ -546,7 +585,7 @@ async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promi
   const grouped = new Map<string, { selector: string; paths: string[] }>();
 
   for (const path of allTopLevel) {
-    const { path: containerPath, selector } = findStableContainer(path, originalMap, modifiedMap);
+    const { path: containerPath, selector } = findStableContainer(path, originalMap, modifiedMap, pageSize);
     const existing = grouped.get(containerPath);
     if (existing) {
       existing.paths.push(path);
@@ -592,10 +631,26 @@ async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promi
     const subtree = serialized ? await minifyHtml(serialized) : '';
     if (!subtree) continue;
 
-    const addedLines = paths.filter((p) => addedTopLevel.includes(p)).map((p) => `ELEMENT:${p}`);
+    const appearedPaths = paths.filter((p) => addedTopLevel.includes(p));
+    const sizeOf = (p: string) => {
+      const node = modifiedMap.get(p);
+      if (!node) return 0;
+      return serializeNode(node).length;
+    };
+    appearedPaths.sort((a, b) => sizeOf(b) - sizeOf(a));
+    const addedLines = appearedPaths.map((p) => `ELEMENT:${p}`);
     const removedLines: string[] = [];
 
-    parts.push({ container: selector, subtree, added: addedLines, removed: removedLines });
+    const part: HtmlDiffPart = { container: selector, subtree, rawSize: serialized.length, added: addedLines, removed: removedLines };
+    const appearedPath = appearedPaths[0];
+    if (appearedPath) {
+      const appearedElement = modifiedMap.get(appearedPath);
+      if (appearedElement) {
+        const appearedSelector = semanticSelectorFor(appearedElement, modifiedMap);
+        if (appearedSelector) part.appearedSelector = appearedSelector;
+      }
+    }
+    parts.push(part);
   }
 
   return parts;