explorbot 0.2.2 → 0.2.4

package/README.md

@@ -138,7 +138,7 @@ EXPLORBOT_KNOWLEDGE="Log in as admin@example.com / secret123" \
   npx explorbot explore /admin/users --max-tests 3
 ```
 
-Output lands in a temp directory and nothing is written to your project. See [Agentic Usage](docs/workflow/agentic-usage.md).
+Output lands in a per-host site directory, `~/.explorbot/sites/<host>/`, so runs against the same app collect in one place and nothing is written to your project. Set `EXPLORBOT_EPHEMERAL=1` to keep nothing between runs. See [Agentic Usage](docs/workflow/agentic-usage.md).
 
 ## Teaching Explorbot
 

package/bin/explorbot-cli.ts

@@ -11,6 +11,7 @@ import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
+import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
 import { getCliName } from '../src/utils/cli-name.ts';
@@ -26,8 +27,9 @@ const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../p
 const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as string;
 
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
+remote.registerOption(program);
 
-if (!process.env.EXPLORBOT_NO_BANNER) {
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 
@@ -40,6 +42,7 @@ interface CLIOptions {
   headless?: boolean;
   incognito?: boolean;
   session?: string | boolean;
+  spec?: string;
 }
 
 function buildExplorBotOptions(from: string | undefined, options: CLIOptions): ExplorBotOptions {
@@ -52,6 +55,7 @@ function buildExplorBotOptions(from: string | undefined, options: CLIOptions): E
     headless: options.headless,
     incognito: options.incognito,
     session: options.session,
+    applicationSpec: options.spec,
   } as ExplorBotOptions;
 }
 
@@ -64,6 +68,7 @@ function addCommonOptions(cmd: Command): Command {
     .option('-s, --show', 'Show browser window')
     .option('--headless', 'Run browser in headless mode')
     .option('--incognito', 'Run without recording experiences')
+    .option('--spec <path>', 'Use a Docbot application spec directory or index.md')
     .option('--session [file]', 'Save/restore browser session from file');
 }
 
@@ -96,6 +101,10 @@ async function startTUI(explorBot: ExplorBot): Promise<void> {
 }
 
 async function showStatsAndExit(code: number): Promise<never> {
+  if (remote.isAttached()) {
+    await remote.close(code);
+    process.exit(code);
+  }
   if (Stats.hasActivity()) {
     await new Promise<void>((resolve) => {
       const { unmount } = render(
@@ -386,6 +395,14 @@ program
     }
   });
 
+program
+  .command('sites')
+  .description('List sites registered in the global installation')
+  .action(async () => {
+    const { SitesCommand } = await import('../src/commands/sites-command.js');
+    await new SitesCommand(new ExplorBot()).execute('');
+  });
+
 addCommonOptions(program.command('rerun <filename> [index]').description('Re-run generated tests with AI auto-healing')).action(async (filename, index, options) => {
   try {
     const explorBot = new ExplorBot(buildExplorBotOptions(undefined, options));
@@ -421,17 +438,28 @@ addCommonOptions(
 
 program
   .command('init')
-  .description('Initialize a new project with configuration')
-  .option('-c, --config-path <path>', 'Path for the config file', './explorbot.config.js')
+  .description('Initialize configuration for a project or for this machine')
+  .option('-c, --config-path <path>', 'Path for the config file')
   .option('-f, --force', 'Overwrite existing config file')
   .option('-p, --path <path>', 'Working directory for initialization')
+  .option('-g, --global', 'Configure explorbot in ~/.explorbot to run from anywhere')
+  .option('--provider <name>', `AI provider for the global config: ${Object.keys(PROVIDERS).join(', ')}`)
+  .option('--api-key <key>', 'API key stored in ~/.explorbot/.env')
   .action(async (options) => {
-    const { runInitCommand } = await import('../src/commands/init-command.js');
-    runInitCommand({
-      configPath: options.configPath,
-      force: options.force,
-      path: options.path,
-    });
+    try {
+      const { runInit } = await import('../src/commands/init-command.js');
+      await runInit({
+        configPath: options.configPath,
+        force: options.force,
+        path: options.path,
+        global: options.global,
+        provider: options.provider,
+        apiKey: options.apiKey,
+      });
+    } catch (error) {
+      console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+      process.exit(1);
+    }
   });
 
 program
@@ -694,7 +722,7 @@ program
       const explorBot = new ExplorBot(mainOptions);
       await explorBot.start();
 
-      await explorBot.agentNavigator().visit(url);
+      await explorBot.visit(url);
 
       const { ContextCommand } = await import('../src/commands/context-command.js');
       const argParts: string[] = [];
@@ -716,7 +744,7 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
   try {
     const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
     await explorBot.start();
-    await explorBot.agentNavigator().visit(url);
+    await explorBot.visit(url);
 
     const action = explorBot.getExplorer().action();
     await action.execute(command);
@@ -740,10 +768,11 @@ browserCmd
   .description('Launch a persistent browser server')
   .option('-s, --show', 'Launch browser in headed mode (visible window)')
   .option('--headless', 'Launch browser in headless mode')
+  .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
   .option('-c, --config <path>', 'Path to configuration file')
   .option('-p, --path <path>', 'Working directory path')
   .action(async (options) => {
-    const { launchServer, removeEndpointFile } = await import('../src/browser-server.js');
+    const { launchServer, removeEndpointFile, keepServerRunning } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
       config: options.config,
       path: options.path,
@@ -754,55 +783,45 @@ browserCmd
     if (options.show !== undefined) show = true;
     if (options.headless !== undefined) show = false;
 
-    const server = await launchServer({
-      browser: config.playwright.browser,
-      show,
-    });
-
-    console.log('Browser server is running. Press Ctrl+C to stop.');
-
-    const cleanup = () => {
-      console.log('\nStopping browser server...');
-      server.close();
-      removeEndpointFile();
-      process.exit(0);
-    };
+    const server = await launchServer(
+      {
+        browser: config.playwright.browser,
+        show,
+      },
+      options.instance
+    );
 
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
+    await keepServerRunning(async () => {
+      await server.close();
+      removeEndpointFile(options.instance);
+    });
   });
 
 browserCmd
   .command('stop')
   .description('Stop a running browser server')
+  .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
   .option('-c, --config <path>', 'Path to configuration file')
   .option('-p, --path <path>', 'Working directory path')
   .action(async (options) => {
-    const { getAliveEndpoint, removeEndpointFile } = await import('../src/browser-server.js');
+    const { stopServer } = await import('../src/browser-server.js');
     await ConfigParser.getInstance().loadConfig({
       config: options.config,
       path: options.path,
     });
 
-    const endpoint = await getAliveEndpoint();
-    if (!endpoint) {
+    if (!(await stopServer(options.instance))) {
       console.log('No running browser server found.');
       process.exit(0);
     }
 
-    try {
-      const { chromium } = await import('playwright-core');
-      const browser = await chromium.connect(endpoint, { timeout: 3000 });
-      await browser.close();
-    } catch {}
-
-    removeEndpointFile();
     console.log('Browser server stopped.');
   });
 
 browserCmd
   .command('status')
   .description('Check if a browser server is running')
+  .option('--instance <name>', 'Named browser instance (lowercase letters, digits, dashes)')
   .option('-c, --config <path>', 'Path to configuration file')
   .option('-p, --path <path>', 'Working directory path')
   .action(async (options) => {
@@ -812,7 +831,7 @@ browserCmd
       path: options.path,
     });
 
-    const endpoint = await getAliveEndpoint();
+    const endpoint = await getAliveEndpoint(options.instance);
     if (endpoint) {
       console.log(`Browser server is running at: ${endpoint}`);
     } else {
@@ -871,8 +890,10 @@ program
 
 import { createApiCommands } from '../boat/api-tester/src/cli.ts';
 import { createDocsCommands } from '../boat/doc-collector/src/cli.ts';
+import { createPrimaCommands } from '../boat/prima/src/cli.ts';
 program.addCommand(createApiCommands('api'));
 program.addCommand(createDocsCommands('docs'));
+program.addCommand(createPrimaCommands('prima'));
 
 const envHelp = () => {
   const width = Math.max(...EXPLORBOT_ENV_VARS.map((v) => v.name.length));

package/boat/api-tester/src/apibot.ts

@@ -33,7 +33,7 @@ export class ApiBot {
   }
 
   async start(): Promise<void> {
-    this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path });
+    this.config = await this.configParser.loadConfig({ config: this.options.config, path: this.options.path, endpoint: this.options.endpoint });
     this.provider = new AIProvider(this.config.ai);
     await this.provider.validateConnection();
 
@@ -101,12 +101,13 @@ export class ApiBot {
     return (this.agents.curler ||= this.createAgent(({ ai, apiClient, requestState }) => new Curler(ai, apiClient, requestState, this.reporter)));
   }
 
-  async plan(endpoint: string, opts: { style?: string; fresh?: boolean } = {}): Promise<Plan> {
+  async plan(target: string, opts: { style?: string; fresh?: boolean } = {}): Promise<Plan> {
     if (opts.fresh) {
       this.currentPlan = undefined;
       this.agents.chief = undefined;
     }
 
+    const endpoint = this.configParser.resolveEndpointPath(target);
     const chief = this.agentChief();
     const specDefinition = this.getEndpointDefinition(endpoint);
     this.currentPlan = await chief.plan(endpoint, { style: opts.style, specDefinition });
@@ -198,6 +199,7 @@ interface ApibotOptions {
   verbose?: boolean;
   config?: string;
   path?: string;
+  endpoint?: string;
 }
 
 export type { ApibotOptions };

package/boat/api-tester/src/cli.ts

@@ -49,7 +49,7 @@ export function createApiCommands(name = 'api'): Command {
   addCommonOptions(cmd.command('plan <endpoint>').description('Generate test plan for an API endpoint').option('--style <style>', 'Planning style: basename of a file in rules/chief/styles/').option('--fresh', 'Start planning from scratch')).action(async (endpoint, options) => {
     setPreserveConsoleLogs(true);
     try {
-      const bot = new ApiBot(buildOptions(options));
+      const bot = new ApiBot({ ...buildOptions(options), endpoint });
       await bot.start();
 
       await bot.plan(endpoint, { style: options.style, fresh: options.fresh });
@@ -122,7 +122,7 @@ export function createApiCommands(name = 'api'): Command {
   addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan')).action(async (endpoint, options) => {
     setPreserveConsoleLogs(true);
     try {
-      const bot = new ApiBot(buildOptions(options));
+      const bot = new ApiBot({ ...buildOptions(options), endpoint });
       await bot.start();
 
       const styles = Object.keys(getStyles());

package/boat/api-tester/src/config.ts

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
-import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from '../../../src/config.ts';
+import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from '../../../src/config.ts';
+import { type SiteRecord, findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from '../../../src/global-config.ts';
 
 export type { AIConfig };
 
@@ -26,6 +28,7 @@ export class ApibotConfigParser {
   private static instance: ApibotConfigParser;
   private config: ApibotConfig | null = null;
   private configPath: string | null = null;
+  private site: SiteRecord | null = null;
 
   private constructor() {}
 
@@ -42,7 +45,7 @@ export class ApibotConfigParser {
     Object.assign(process.env, parseEnv(readFileSync(resolved, 'utf8')));
   }
 
-  async loadConfig(options?: { config?: string; path?: string }): Promise<ApibotConfig> {
+  async loadConfig(options?: { config?: string; path?: string; endpoint?: string }): Promise<ApibotConfig> {
     if (this.config && !options?.config && !options?.path) return this.config;
 
     const originalCwd = process.cwd();
@@ -50,6 +53,7 @@ export class ApibotConfigParser {
       process.chdir(resolve(options.path));
     }
 
+    ApibotConfigParser.loadEnv(globalEnvPath());
     ApibotConfigParser.loadEnv('.env');
 
     const resolvedPath = options?.config || this.findConfigFile();
@@ -78,7 +82,14 @@ export class ApibotConfigParser {
       }
 
       this.config = this.mergeWithDefaults(loadedConfig);
+      await resolveConfigModels(this.config.ai);
       this.configPath = resolvedPath;
+      this.site = null;
+
+      if (isGlobalConfigPath(resolvedPath)) {
+        this.enterGlobalMode(this.config, options?.endpoint);
+      }
+
       this.validateConfig(this.config);
 
       return this.config;
@@ -100,9 +111,22 @@ export class ApibotConfigParser {
 
   getOutputDir(): string {
     const config = this.getConfig();
+    return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
+  }
+
+  getProjectRoot(): string {
+    if (this.site) return this.site.dir;
     const configPath = this.getConfigPath();
     if (!configPath) throw new Error('Config path not found');
-    return path.join(path.dirname(configPath), config.dirs?.output || 'output');
+    return path.dirname(configPath);
+  }
+
+  resolveEndpointPath(endpoint: string): string {
+    if (!this.site) return endpoint;
+
+    const resolved = resolveSiteTarget(endpoint, this.site.url);
+    if (resolved.baseUrl !== this.site.url) return endpoint;
+    return resolved.path;
   }
 
   getPlansDir(): string {
@@ -115,9 +139,7 @@ export class ApibotConfigParser {
 
   getKnowledgeDir(): string {
     const config = this.getConfig();
-    const configPath = this.getConfigPath();
-    if (!configPath) throw new Error('Config path not found');
-    return path.join(path.dirname(configPath), config.dirs?.knowledge || 'knowledge');
+    return path.join(this.getProjectRoot(), config.dirs?.knowledge || 'knowledge');
   }
 
   ensureDirectory(dirPath: string): void {
@@ -126,11 +148,20 @@ export class ApibotConfigParser {
     }
   }
 
+  private enterGlobalMode(config: ApibotConfig, endpoint?: string): void {
+    const site = resolveSiteTarget(endpoint);
+    this.site = registerSite(site.baseUrl);
+
+    config.dirs = { output: 'output', knowledge: 'knowledge' };
+    config.api = { ...config.api, baseEndpoint: site.baseUrl };
+    if (process.env.EXPLORBOT_API_SPEC) config.api.spec = [process.env.EXPLORBOT_API_SPEC];
+  }
+
   private async loadEnvConfig(): Promise<ApibotConfig> {
     const provider = process.env.EXPLORBOT_AI_PROVIDER;
     const modelSpec = process.env.EXPLORBOT_AI_MODEL;
     if (!provider && !modelSpec) {
-      throw new Error('No configuration file found. Create apibot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+      throw new ConfigMissingError(missingConfigMessage('apibot.config.js'));
     }
     if (modelSpec && !provider && !modelSpec.includes('/')) {
       throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
@@ -177,15 +208,17 @@ export class ApibotConfigParser {
       if (existsSync(fullPath)) return fullPath;
     }
 
-    return null;
+    if (envConfigRequested()) return null;
+    return findGlobalConfig();
   }
 
   private async loadConfigModule(configPath: string): Promise<any> {
     const ext = configPath.split('.').pop();
+    const moduleUrl = pathToFileURL(resolve(configPath)).href;
 
     if (ext === 'ts') {
       try {
-        return await import(configPath);
+        return await import(moduleUrl);
       } catch {
         const require = (await import('node:module')).createRequire(import.meta.url);
         return require(configPath);
@@ -193,7 +226,7 @@ export class ApibotConfigParser {
     }
 
     if (ext === 'js' || ext === 'mjs') {
-      return await import(configPath);
+      return await import(moduleUrl);
     }
 
     const content = readFileSync(configPath, 'utf8');

package/boat/doc-collector/bin/doc-collector-cli.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env bun
+import { remote } from '../../../src/remote.ts';
 import { createDocsCommands } from '../src/cli.ts';
 
 const program = createDocsCommands('doc-collector');
+remote.registerOption(program);
 program.parse();

package/boat/doc-collector/src/ai/documentarian.ts

@@ -67,17 +67,32 @@ class Documentarian {
       const message = error instanceof Error ? error.message : String(error);
       tag('warning').log(`Interactive documentation failed: ${message}.`);
       if (meaningfulInteractions.length > 0) {
-        tag('info').log(`Preserving ${meaningfulInteractions.length} observed interaction(s) without AI summary.`);
-        return this.normalizeDocumentation(
-          {
-            summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
-            can: [],
-            might: [],
-            interactions: meaningfulInteractions,
-          },
-          state,
-          research
-        );
+        tag('info').log(`Retrying static documentation while preserving ${meaningfulInteractions.length} observed interaction(s).`);
+        return this.documentStatic(state, research)
+          .then((documentation) =>
+            this.normalizeDocumentation(
+              {
+                ...documentation,
+                interactions: meaningfulInteractions,
+              },
+              state,
+              research
+            )
+          )
+          .catch((fallbackError) => {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            tag('warning').log(`Static documentation fallback failed: ${fallbackMessage}. Preserving observed interactions without AI summary.`);
+            return this.normalizeDocumentation(
+              {
+                summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
+                can: [],
+                might: [],
+                interactions: meaningfulInteractions,
+              },
+              state,
+              research
+            );
+          });
       }
       return this.documentStatic(state, research);
     }
@@ -113,13 +128,13 @@ class Documentarian {
       },
     ];
 
-    const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+    const response = await this.provider.generateObject(messages, generatedPageDocumentationSchema, undefined, {
       agentName: 'documentarian',
     });
 
     return this.normalizeDocumentation(
       {
-        ...(response.object as PageDocumentation),
+        ...(response.object as GeneratedPageDocumentation),
         interactions,
       },
       state,
@@ -139,11 +154,11 @@ class Documentarian {
       },
     ];
 
-    const response = await this.provider.generateObject(messages, pageDocumentationSchema, undefined, {
+    const response = await this.provider.generateObject(messages, generatedPageDocumentationSchema, undefined, {
       agentName: 'documentarian',
     });
 
-    return this.normalizeDocumentation(response.object as PageDocumentation, state, research);
+    return this.normalizeDocumentation(response.object as GeneratedPageDocumentation, state, research);
   }
 
   private getSystemPrompt(): string {
@@ -259,7 +274,7 @@ class Documentarian {
     return message.includes('Failed to generate JSON') || message.includes('Failed to validate JSON') || message.includes('failed_generation') || message.includes('No object generated') || message.includes('response did not match schema');
   }
 
-  private normalizeDocumentation(documentation: PageDocumentation, _state: WebPageState, _research: string): PageDocumentation {
+  private normalizeDocumentation(documentation: GeneratedPageDocumentation & Partial<Pick<PageDocumentation, 'interactions'>>, _state: WebPageState, _research: string): PageDocumentation {
     const normalized = { ...documentation };
     if (!normalized.interactions) {
       normalized.interactions = undefined;
@@ -267,10 +282,10 @@ class Documentarian {
 
     const qualityNotes = this.evaluateDocumentationQuality(normalized);
 
-    return {
+    return pageDocumentationSchema.parse({
       ...normalized,
       qualityNotes,
-    };
+    });
   }
 
   private evaluateDocumentationQuality(documentation: PageDocumentation): string[] {
@@ -346,39 +361,54 @@ const stateTransitionSchema = z.object({
   action: z.string(),
   before: z.string(),
   after: z.string(),
-  targetUrl: z.string().nullable(),
-  discoveredUrls: z.array(z.string()).nullable(),
-  newCapabilities: z.array(z.string()).nullable(),
+  targetUrl: z.string().optional(),
+  discoveredUrls: z.array(z.string()).optional(),
+  newCapabilities: z.array(z.string()).optional(),
   element: z
     .object({
       role: z.string(),
       name: z.string(),
       section: z.string(),
-      container: z.string().nullable(),
-      locator: z.string().nullable(),
+      container: z.string().optional(),
+      locator: z.string().optional(),
     })
-    .nullable(),
+    .optional(),
   changes: z
     .object({
       urlChanged: z.boolean(),
       newElements: z.number(),
       removedElements: z.number(),
     })
-    .nullable(),
+    .optional(),
+  targetState: z
+    .object({
+      kind: z.enum(['page', 'dialog', 'modal', 'section']),
+      label: z.string(),
+      url: z.string(),
+    })
+    .optional(),
+  screenshot: z
+    .object({
+      title: z.string(),
+      relativePath: z.string(),
+    })
+    .optional(),
 });
 
-const pageDocumentationSchema = z.object({
+const generatedPageDocumentationSchema = z.object({
   summary: z.string(),
   can: z.array(capabilitySchema),
   might: z.array(capabilitySchema),
-  interactions: z.array(stateTransitionSchema).nullable(),
+});
+
+const pageDocumentationSchema = generatedPageDocumentationSchema.extend({
+  interactions: z.array(stateTransitionSchema).optional(),
+  qualityNotes: z.array(z.string()).optional(),
 });
 
 type StateTransition = DocStateTransition;
-type PageDocumentation = Omit<z.infer<typeof pageDocumentationSchema>, 'interactions'> & {
-  interactions?: StateTransition[];
-  qualityNotes?: string[];
-};
+type GeneratedPageDocumentation = z.infer<typeof generatedPageDocumentationSchema>;
+type PageDocumentation = z.infer<typeof pageDocumentationSchema>;
 
 export { Documentarian };
 export type { PageDocumentation, StateTransition };

package/boat/doc-collector/src/cli.ts

@@ -55,6 +55,7 @@ export function createDocsCommands(name = 'docs'): Command {
       console.log(`Skipped ${result.skipped.length} page(s)`);
       console.log(`Spec index: ${result.indexPath}`);
       console.log(`Pages dir: ${path.join(result.outputDir, 'pages')}`);
+      console.log(`Use in Explorbot: npx explorbot start ${startPath} --spec "${result.outputDir}"`);
 
       await bot.stop();
       process.exit(0);

package/boat/doc-collector/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import { ConfigParser } from '../../../src/config.ts';
 
@@ -90,10 +91,11 @@ class DocbotConfigParser {
 
   private async loadConfigModule(configPath: string): Promise<any> {
     const ext = configPath.split('.').pop();
+    const moduleUrl = pathToFileURL(resolve(configPath)).href;
 
     if (ext === 'ts') {
       try {
-        return await import(configPath);
+        return await import(moduleUrl);
       } catch {
         const require = (await import('node:module')).createRequire(import.meta.url);
         return require(configPath);
@@ -101,7 +103,7 @@ class DocbotConfigParser {
     }
 
     if (ext === 'js' || ext === 'mjs') {
-      return await import(configPath);
+      return await import(moduleUrl);
     }
 
     return JSON.parse(readFileSync(configPath, 'utf8'));