explorbot 0.5.10 → 0.6.0

package/src/commands/plan-command.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
 import figureSet from 'figures';
@@ -17,8 +18,12 @@ export class PlanCommand extends BaseCommand {
   options = [
     { flags: '--fresh', description: 'Regenerate plan from scratch' },
     { flags: '--clear', description: 'Clear plan before regenerating' },
+    { flags: '--append', description: 'Add tests to existing plan file' },
     { flags: '--style <name>', description: 'Planning style (normal, curious, psycho, performer)' },
     { flags: '--focus <feature>', description: 'Focus area for test planning' },
+    { flags: '--tests <count>', description: 'Exact number of tests to generate' },
+    { flags: '--min-tests <count>', description: 'Minimum number of tests to generate' },
+    { flags: '--max-tests <count>', description: 'Maximum number of tests to generate' },
   ];
 
   async execute(args: string): Promise<void> {
@@ -30,11 +35,20 @@ export class PlanCommand extends BaseCommand {
       tag('success').log('Plan cleared');
     }
 
+    if (opts.append) {
+      const existingPlanPath = path.join(this.explorBot.getPlansDir(), this.explorBot.generatePlanFilename());
+      if (existsSync(existingPlanPath)) this.explorBot.loadPlan(existingPlanPath);
+    }
+
     if (focus) {
       tag('info').log(`Planning focus: ${focus}`);
     }
 
-    await this.explorBot.plan(focus, { fresh: !!(opts.fresh || opts.clear), style: opts.style as string });
+    const testsCount = opts.tests ? Number.parseInt(opts.tests as string, 10) : undefined;
+    const minTests = testsCount ?? (opts.minTests ? Number.parseInt(opts.minTests as string, 10) : undefined);
+    const maxTests = testsCount ?? (opts.maxTests ? Number.parseInt(opts.maxTests as string, 10) : undefined);
+
+    await this.explorBot.plan(focus, { fresh: !!(opts.fresh || opts.clear), style: opts.style as string, minTests, maxTests });
 
     const plan = this.explorBot.getCurrentPlan();
     if (!plan?.tests.length) {
@@ -46,29 +60,34 @@ export class PlanCommand extends BaseCommand {
     this.printNextSteps();
   }
 
+  static planSection(planPath: string, cliSuffix = ''): NextStepSection {
+    const cli = getCliName();
+    const planName = path.basename(planPath, '.md');
+    return {
+      label: 'Plan',
+      path: planPath,
+      commands: [
+        { label: 'Run all tests', command: `${cli} test ${planName}${cliSuffix}` },
+        { label: 'Run one test', command: `${cli} test ${planName} 1${cliSuffix}` },
+        { label: 'Run a range', command: `${cli} test ${planName} 1-3${cliSuffix}` },
+      ],
+    };
+  }
+
   private printNextSteps(): void {
     const savedPath = this.explorBot.lastSavedPlanPath;
     if (!savedPath) return;
 
     const cli = getCliName();
-    const relPlan = relativeToCwd(savedPath);
-    const sections: NextStepSection[] = [
-      {
-        label: 'Plan',
-        path: savedPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-          { label: 'Reload', command: `/plan:load ${relPlan}` },
-        ],
-      },
-    ];
+    const cliSuffix = this.cliSuffix();
+    const section = PlanCommand.planSection(savedPath, cliSuffix);
+    section.commands?.push({ label: 'Reload', command: `/plan:load ${path.basename(savedPath, '.md')}` });
+    const sections: NextStepSection[] = [section];
 
     const suite = this.explorBot.getSuite();
     const files = suite && suite.automatedTestCount > 0 ? suite.getAutomatedTestFiles() : [];
     if (files.length > 0) {
-      const commands = files.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
+      const commands = files.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}${cliSuffix}` }));
       sections.push({
         label: `Automated tests (${files.length})`,
         commands,
@@ -78,6 +97,14 @@ export class PlanCommand extends BaseCommand {
     printNextSteps(sections);
   }
 
+  private cliSuffix(): string {
+    const options = this.explorBot.getOptions();
+    let suffix = '';
+    if (options.path) suffix += ` --path ${options.path}`;
+    if (options.session) suffix += ' --session';
+    return suffix;
+  }
+
   private printPlanSummary(): void {
     const suite = this.explorBot.getSuite();
     const plan = this.explorBot.getCurrentPlan();
@@ -91,10 +118,10 @@ export class PlanCommand extends BaseCommand {
     }
 
     if (plan?.tests.length) {
-      console.log(`\n${chalk.bold.cyan(`New test scenarios (${plan.tests.length})`)}`);
+      console.log(`\n${chalk.bold.cyan(`New test scenarios (${plan.tests.length})`)}\n`);
       for (let i = 0; i < plan.tests.length; i++) {
         const t = plan.tests[i];
-        console.log(`  ${chalk.dim(`${i + 1}.`)} ${chalk.green(figureSet.pointer)} ${t.scenario} ${chalk.dim(`[${t.priority}]`)}`);
+        console.log(`  ${chalk.cyan(`${i + 1}.`)} ${t.scenario}`);
       }
     }
   }

package/src/commands/plan-save-command.ts

@@ -1,5 +1,6 @@
-import { getCliName } from '../utils/cli-name.ts';
-import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
+import path from 'node:path';
+import { printNextSteps } from '../utils/next-steps.ts';
+import { PlanCommand } from './plan-command.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanSaveCommand extends BaseCommand {
@@ -17,20 +18,8 @@ export class PlanSaveCommand extends BaseCommand {
     const savedPath = this.explorBot.savePlan(filename);
     if (!savedPath) return;
 
-    const cli = getCliName();
-    const relPlan = relativeToCwd(savedPath);
-    const sections: NextStepSection[] = [
-      {
-        label: 'Plan',
-        path: savedPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-          { label: 'Reload', command: `/plan:load ${relPlan}` },
-        ],
-      },
-    ];
-    printNextSteps(sections);
+    const section = PlanCommand.planSection(savedPath);
+    section.commands?.push({ label: 'Reload', command: `/plan:load ${path.basename(savedPath, '.md')}` });
+    printNextSteps([section]);
   }
 }

package/src/commands/plans-command.ts

@@ -52,7 +52,7 @@ export class PlansCommand extends BaseCommand {
     }
     tag('info').log('');
     tag('info').log('Run test from this plan as:');
-    tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
+    tag('info').log(`${getCliName()} test ${file.name} 1`);
   }
 
   private resolvePlanFile(target: string, files: PlanFile[]): { plan: Plan; file: PlanFile } {

package/src/commands/test-command.ts

@@ -1,5 +1,6 @@
 import { Stats } from '../stats.js';
 import { Plan, Test } from '../test-plan.js';
+import { BlockedError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
@@ -18,6 +19,11 @@ export class TestCommand extends BaseCommand {
       this.explorBot.loadPlan(String(opts.fromPlan));
     }
 
+    if (!opts.fromPlan && remaining[0] && Plan.resolveFile(remaining[0], this.explorBot.getPlansDir())) {
+      this.explorBot.loadPlan(remaining.shift()!);
+      if (remaining.length === 0) remaining.push('*');
+    }
+
     const plan = this.explorBot.getCurrentPlan();
     const selector = remaining.join(' ');
     Stats.mode = 'test';
@@ -71,13 +77,16 @@ export class TestCommand extends BaseCommand {
     const tester = this.explorBot.agentTester();
     for (const [index, test] of toExecute.entries()) {
       tag('info').log(`Starting test ${index + 1}/${toExecute.length}: ${test.scenario}`);
-      await tester.test(test);
+      await tester.test(test).catch((err) => {
+        if (!(err instanceof BlockedError)) throw err;
+        tag('warning').log(`Skipping test: ${err.message}`);
+      });
     }
     tag('success').log('Test execution finished');
   }
 
   completeArguments(): ArgumentCompletion[] {
-    return Plan.listFiles(this.explorBot.getPlansDir()).map((file) => ({ value: `--from-plan ${file.name}`, display: file.label }));
+    return Plan.listFiles(this.explorBot.getPlansDir()).map((file) => ({ value: file.name, display: file.label }));
   }
 }
 

package/src/components/App.tsx

@@ -3,14 +3,13 @@ import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { CommandHandler } from '../command-handler.js';
 import type { ExplorbotConfig } from '../config.js';
 import { executionController } from '../execution-controller.ts';
-import type { ExplorBot, ExplorBotOptions } from '../explorbot.ts';
+import type { ExplorBot } from '../explorbot.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import type { StateTransition, WebPageState } from '../state-manager.js';
 import { Test } from '../test-plan.ts';
 import { tag } from '../utils/logger.js';
 import ActivityPane from './ActivityPane.js';
 import Autocomplete from './Autocomplete.js';
-import InputPane from './InputPane.js';
 import InputReadline from './InputReadline.js';
 import LogPane from './LogPane.js';
 import PlanEditor from './PlanEditor.js';
@@ -23,17 +22,15 @@ import WelcomeCommands from './WelcomeCommands.js';
 interface AppProps {
   explorBot: ExplorBot;
   initialShowInput?: boolean;
-  exitOnEmptyInput?: boolean;
 }
 
-export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = false }: AppProps) {
+export function App({ explorBot, initialShowInput = false }: AppProps) {
   const sessionStartedAtRef = useRef<number>(Date.now());
   const InputComponent = InputReadline;
   const [showSessionTimer, setShowSessionTimer] = useState(false);
   const [showInput, setShowInput] = useState(initialShowInput);
   const [interruptPrompt, setInterruptPrompt] = useState<string | null>(null);
   const [currentState, setCurrentState] = useState<WebPageState | null>(null);
-  const [lastTransition, setLastTransition] = useState<StateTransition | null>(null);
   const [tasks, setTasks] = useState<Test[]>([]);
   const tasksRef = useRef<Test[]>([]);
   const [showPlanEditor, setShowPlanEditor] = useState(false);
@@ -72,7 +69,6 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
 
     unsubscribe = manager.onStateChange((transition: StateTransition) => {
       if (mounted) {
-        setLastTransition(transition);
         setCurrentState(transition.toState);
       }
     });

package/src/components/InputPane.tsx

@@ -19,7 +19,6 @@ const InputPane: React.FC<InputPaneProps> = ({ commandHandler, exitOnEmptyInput
   const [cursorPosition, setCursorPosition] = useState(0);
   const [showAutocomplete, setShowAutocomplete] = useState(false);
   const [selectedIndex, setSelectedIndex] = useState(0);
-  const [autoCompleteTriggered, setAutoCompleteTriggered] = useState(false);
   const inputRef = useRef(inputValue);
   const cursorRef = useRef(cursorPosition);
 
@@ -166,7 +165,6 @@ const InputPane: React.FC<InputPaneProps> = ({ commandHandler, exitOnEmptyInput
           setShowAutocomplete(false);
           setSelectedIndex(0);
           setCursorPosition(selectedCommand.length);
-          setAutoCompleteTriggered(true);
         }
         return;
       }
@@ -182,7 +180,6 @@ const InputPane: React.FC<InputPaneProps> = ({ commandHandler, exitOnEmptyInput
           setInputValue(newValue);
           setCursorPosition(nextCursor);
           setSelectedIndex(0);
-          setAutoCompleteTriggered(false);
           setShowAutocomplete(shouldShowAutocomplete(newValue));
         }
         return;
@@ -198,7 +195,6 @@ const InputPane: React.FC<InputPaneProps> = ({ commandHandler, exitOnEmptyInput
         setInputValue(newValue);
         setCursorPosition(nextCursor);
         setSelectedIndex(0);
-        setAutoCompleteTriggered(false);
         setShowAutocomplete(shouldShowAutocomplete(newValue));
       }
     },
@@ -247,7 +243,6 @@ const InputPane: React.FC<InputPaneProps> = ({ commandHandler, exitOnEmptyInput
             setShowAutocomplete(false);
             setSelectedIndex(0);
             setCursorPosition(selectedCommand.length);
-            setAutoCompleteTriggered(true);
           }
         }}
         visible={showAutocomplete}

package/src/config.ts

@@ -132,6 +132,8 @@ interface PlannerAgentConfig extends AgentConfig {
   styles?: string[];
   stylesDir?: string;
   docsWeight?: number;
+  minTests?: number;
+  maxTests?: number;
 }
 
 interface ScoutAgentConfig extends AgentConfig {
@@ -245,7 +247,7 @@ interface ExplorbotConfig {
     knowledge: string;
     experience: string;
     output: string;
-    spec?: string;
+    spec?: string | string[];
   };
   experience?: {
     maxReadLines?: number;
@@ -258,17 +260,6 @@ interface ExplorbotConfig {
   dynamicPageRegex?: string;
 }
 
-const config: ExplorbotConfig = {
-  playwright: {
-    browser: 'chromium',
-    url: 'http://localhost:3000',
-  },
-
-  ai: {
-    model: null as any,
-  },
-};
-
 type RuleEntry = string | Record<string, string>;
 
 export { EXPLORBOT_CONFIG_PATHS };
@@ -763,10 +754,6 @@ export class ConfigParser {
     }
   }
 
-  private getNestedValue(obj: any, path: string): any {
-    return path.split('.').reduce((current, key) => current?.[key], obj);
-  }
-
   public mergeWithDefaults(config: Partial<ExplorbotConfig>): ExplorbotConfig {
     const defaults = {
       playwright: {
@@ -879,6 +866,7 @@ export function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>
   const models: Record<string, ConfiguredModel> = { model: describe(ai.model) };
   if (ai.agenticModel) models.agenticModel = describe(ai.agenticModel);
   if (ai.visionModel) models.visionModel = describe(ai.visionModel);
+  if (ai.decisionModel) models.decisionModel = { name: ai.decisionModel.model, provider: ai.decisionModel.provider };
   for (const [agent, agentConfig] of Object.entries(ai.agents || {})) {
     if (agentConfig?.model) models[agent] = describe(agentConfig.model);
   }

package/src/experience-tracker.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import matter from 'gray-matter';
 import type { ActionResult } from './action-result.js';

package/src/explorbot.ts

@@ -55,7 +55,7 @@ export interface ExplorBotOptions {
   optionalAi?: boolean;
   reporter?: ReporterConfig;
   attachedBrowser?: Browser;
-  applicationSpec?: string;
+  applicationSpec?: string | string[];
 }
 
 export type UserResolveFunction = (error?: Error, showWelcome?: boolean) => Promise<string | null>;
@@ -156,7 +156,13 @@ export class ExplorBot {
   }
 
   async visit(url: string): Promise<void> {
-    await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+    const target = this.configParser.resolveTargetPath(url);
+    await this.agentNavigator()
+      .visit(target)
+      .catch(async (err) => {
+        if (await this.agentCaptain().resolveBlocker(err, () => this.agentNavigator().isOn(target))) return;
+        throw err;
+      });
   }
 
   async openTab(): Promise<void> {
@@ -274,7 +280,7 @@ export class ExplorBot {
       }
       if (this.isHistorianEnabled()) this.agents.tester.setHistorian(this.agentHistorian());
       this.agents.tester.setPilot(this.agentPilot());
-      this.agents.tester.setCaptain(this.agentCaptain());
+      this.agents.tester.setSupervisor((input: string, test: Test) => this.agentCaptain().processSupervisorInterrupt(input, test));
 
       const fisherman = this.agentFisherman();
       if (fisherman) this.agentPilot().setFisherman(fisherman);
@@ -377,9 +383,14 @@ export class ExplorBot {
 
   agentScout(): Scout | null {
     const scoutConfig = this.config.ai?.agents?.scout;
-    if (scoutConfig?.enabled !== true) return null;
-
     const dirs = this.scoutCorpusDirs();
+    const hasSpec = dirs.length > 0;
+    const explicitlyDisabled = scoutConfig?.enabled === false;
+    const explicitlyEnabled = scoutConfig?.enabled === true;
+
+    if (explicitlyDisabled) return null;
+    if (!explicitlyEnabled && !hasSpec) return null;
+
     if (dirs.length === 0) {
       tag('warning').log('Scout enabled but no documentation found — set --spec or ai.agents.scout.dirs');
       return null;
@@ -391,11 +402,10 @@ export class ExplorBot {
   private scoutCorpusDirs(): string[] {
     const dirs: string[] = [];
 
-    const specPath = this.options.applicationSpec || this.config.dirs?.spec;
-    if (specPath) {
+    const specPaths = normalizeSpecPaths(this.options.applicationSpec || this.config.dirs?.spec);
+    for (const specPath of specPaths) {
       const bundle = resolveSpecBundlePath(specPath);
-      const pagesDir = bundle && path.join(bundle, 'pages');
-      if (pagesDir && existsSync(pagesDir)) dirs.push(pagesDir);
+      if (bundle && existsSync(bundle)) dirs.push(bundle);
     }
 
     for (const dir of this.config.ai?.agents?.scout?.dirs || []) {
@@ -423,7 +433,7 @@ export class ExplorBot {
     this.agents.planner = undefined;
   }
 
-  async plan(feature?: string, opts: { fresh?: boolean; style?: string; extend?: Plan; completedPlans?: Plan[]; noSave?: boolean } = {}) {
+  async plan(feature?: string, opts: { fresh?: boolean; style?: string; extend?: Plan; noSave?: boolean; minTests?: number; maxTests?: number } = {}) {
     this.planFeature = feature;
 
     if (opts.fresh) {
@@ -440,13 +450,18 @@ export class ExplorBot {
 
     const planner = this.agentPlanner();
     planner.freshStart = !!opts.fresh;
+    if (opts.minTests !== undefined || opts.maxTests !== undefined) {
+      planner.setTestCount({ minTests: opts.minTests, maxTests: opts.maxTests });
+    }
     if (this.currentPlan) {
       planner.setPlan(this.currentPlan);
     }
     this.lastPlanError = null;
+    const before = new Set(this.currentPlan?.tests ?? []);
     try {
-      this.setCurrentPlan(await planner.plan(feature, opts.style, opts.extend, opts.completedPlans));
+      this.setCurrentPlan(await planner.plan(feature, opts.style, opts.extend));
     } catch (err) {
+      if (await this.agentCaptain().resolveBlocker(err, () => !!this.currentPlan?.tests.some((t) => !before.has(t)))) return this.currentPlan;
       this.lastPlanError = err instanceof Error ? err : new Error(String(err));
       tag('warning').log(`Planning failed: ${this.lastPlanError.message}`);
       if (!this.currentPlan) return undefined;
@@ -575,3 +590,8 @@ export class ExplorBot {
     }
   }
 }
+
+function normalizeSpecPaths(spec: string | string[] | undefined): string[] {
+  if (!spec) return [];
+  return Array.isArray(spec) ? spec : [spec];
+}

package/src/explorer.ts

@@ -17,7 +17,7 @@ import type { KnowledgeTracker } from './knowledge-tracker.js';
 import type { PlaywrightRecorder } from './playwright-recorder.ts';
 import type { Reporter } from './reporter.ts';
 import type { StateManager } from './state-manager.js';
-import { Test, TestResult } from './test-plan.ts';
+import { Test } from './test-plan.ts';
 import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
 import { createDebug, log, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
@@ -190,7 +190,6 @@ class Explorer {
     if (!(await this.recoverOrRestart())) {
       return { ok: false, action: 'stop', message: 'Browser page could not be recovered' };
     }
-    this.watchActiveTestPage();
     return { ok: true, action: 'continue', recovered: true, message: 'Browser page was recovered' };
   }
 
@@ -201,7 +200,7 @@ class Explorer {
 
     this._activeTest = test;
     test.start();
-    await this.reporter.reportTestStart(test);
+    await this.reporter.reportTestStart();
     await this.closeOtherTabs();
     this.stateManager.otherTabs = [];
 
@@ -414,7 +413,7 @@ class Explorer {
 
   private async runWithRecovery<T>(label: string, operation: () => Promise<T>): Promise<T> {
     if (!this.page && !(await this.recoverOrRestart())) {
-      throw new Error(`Browser page is unavailable before ${label}`);
+      throw new BrowserRecoveryError(label, new Error('Browser page is unavailable'), false);
     }
 
     try {
@@ -516,7 +515,6 @@ class Explorer {
       return { ok: false, action: 'stop', recovered: false, message: `Browser could not be recovered after fatal error: ${message}` };
     }
 
-    this.watchActiveTestPage();
     return {
       ok: true,
       action: 'continue',
@@ -531,8 +529,9 @@ class Explorer {
   }
 
   private async recoverOrRestart(): Promise<boolean> {
-    if (await this.recoverPage()) return true;
-    return this.restartBrowser();
+    if (!(await this.recoverPage()) && !(await this.restartBrowser())) return false;
+    this.watchActiveTestPage();
+    return true;
   }
 
   private async recoverPage(): Promise<boolean> {

package/src/knowledge-tracker.ts

@@ -22,7 +22,7 @@ export class KnowledgeTracker {
   private knowledgeFiles: Knowledge[] = [];
   private sessionKnowledge: Knowledge[] = [];
   private isLoaded = false;
-  private applicationSpec?: ApplicationSpec;
+  private applicationSpecs: ApplicationSpec[] = [];
 
   static appendSessionKnowledge(text: string): void {
     sessionEntries.push(text);
@@ -49,9 +49,14 @@ export class KnowledgeTracker {
       mkdirSync(this.knowledgeDir, { recursive: true });
     }
 
-    if (specPath) {
-      this.applicationSpec = new ApplicationSpec(specPath);
-      tag('info').log(`Loaded application spec with ${this.applicationSpec.pageCount} documented pages`);
+    for (const p of normalizeSpecPaths(specPath)) {
+      const spec = new ApplicationSpec(p);
+      this.applicationSpecs.push(spec);
+      if (spec.pageCount > 0) {
+        tag('info').log(`Loaded application spec with ${spec.pageCount} documented pages`);
+      } else if (spec.markdownFileCount > 0) {
+        tag('info').log(`Loaded spec corpus with ${spec.markdownFileCount} markdown files`);
+      }
     }
 
     this.sessionKnowledge = sessionEntries.map((entry, index) => {
@@ -99,11 +104,12 @@ export class KnowledgeTracker {
   }
 
   renderApplicationSpec(state: ActionResult): string {
-    return this.applicationSpec?.renderFor(state) || '';
+    const parts = this.applicationSpecs.map((spec) => spec.renderFor(state)).filter(Boolean);
+    return parts.join('\n\n');
   }
 
   applicationSpecUrls(state: ActionResult): string[] {
-    return this.applicationSpec?.matchedUrls(state) || [];
+    return this.applicationSpecs.flatMap((spec) => spec.matchedUrls(state));
   }
 
   addKnowledge(urlPattern: string, description: string, opts?: { replace?: boolean }): { filename: string; filePath: string; isNewFile: boolean } {
@@ -293,6 +299,11 @@ export class KnowledgeTracker {
   }
 }
 
+function normalizeSpecPaths(spec: string | string[] | undefined): string[] {
+  if (!spec) return [];
+  return Array.isArray(spec) ? spec : [spec];
+}
+
 export interface Knowledge {
   filePath: string;
   url?: string;
@@ -302,6 +313,6 @@ export interface Knowledge {
 }
 
 export interface KnowledgeTrackerOptions {
-  applicationSpec?: string;
+  applicationSpec?: string | string[];
   knowledgeDir?: string;
 }

package/src/playwright-recorder.ts

@@ -39,7 +39,6 @@ export interface VerificationStep {
 }
 
 export class PlaywrightRecorder {
-  private context: any = null;
   private tracing: any = null;
   private active = false;
   private nextGroupId = 0;
@@ -68,7 +67,6 @@ export class PlaywrightRecorder {
       debugLog('start: no tracing on browserContext, recorder inactive');
       return;
     }
-    this.context = browserContext;
     this.tracing = browserContext.tracing;
     try {
       await this.tracing.start({});

package/src/reporter.ts

@@ -1,4 +1,3 @@
-import { join } from 'node:path';
 import { Client } from '@testomatio/reporter';
 import type { Step } from '@testomatio/reporter/types/types.js';
 import { outputPath } from './config.js';
@@ -132,14 +131,14 @@ export class Reporter {
     process.env.TESTOMATIO_STEPS_PASSED = 'true';
   }
 
-  async reportTestStart(test: Test): Promise<void> {
+  async reportTestStart(): Promise<void> {
     await this.startRun();
   }
 
   protected combineStepsAndNotes(test: Test, lastScreenshotFile?: string): Step[] {
     const noteEntries = Object.entries(test.notes)
       .filter(([, note]) => !note.observation)
-      .map(([timestampKey, note]) => ({
+      .map(([, note]) => ({
         startTime: note.startTime,
         endTime: note.endTime,
         message: note.message,
@@ -150,7 +149,7 @@ export class Reporter {
       .sort((a, b) => a.startTime - b.startTime);
 
     const stepEntries = Object.entries(test.steps)
-      .map(([timestampKey, stepData]) => ({
+      .map(([, stepData]) => ({
         noteStartTime: stepData.noteStartTime,
         text: stepData.text,
         duration: stepData.duration,

package/src/test-plan.ts

@@ -1,7 +1,6 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import figures from 'figures';
 import type { ActionResult } from './action-result.ts';
 import { listSitePlanDirs } from './global-config.ts';
 import { WebPageState } from './state-manager.ts';
@@ -545,7 +544,7 @@ export class Plan {
     if (!plansDir) dirs.push(...listSitePlanDirs());
 
     for (const dir of dirs) {
-      const filePath = names.map((name) => path.resolve(dir, name)).find(existsSync);
+      const filePath = names.map((name) => path.resolve(dir, name)).find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
       if (filePath) return filePath;
     }
     return null;