explorbot 0.4.8 → 0.4.9

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

@@ -1,3 +1,4 @@
+export declare const EXPLORBOT_CONFIG_PATHS: string[];
 export declare function globalDir(): string;
 export declare function globalEnvPath(): string;
 export declare function globalConfigPath(): string;
@@ -6,6 +7,11 @@ export declare function isGlobalConfigPath(configPath: string): boolean;
 export declare function sitesDir(): string;
 export declare function siteFolderName(url: string): string;
 export declare function listSites(): SiteRecord[];
+export declare function findSiteConfig(dir: string): string | null;
+export declare function loadSiteConfig(dir: string, baseUrl: string): Promise<{
+    path: string;
+    config: any;
+}>;
 export declare function findSiteWith(subpath: string): SiteRecord | undefined;
 export declare function listSitePlanDirs(): string[];
 export declare function registerSite(baseUrl: string): SiteRecord;

package/dist/src/global-config.js

@@ -1,8 +1,19 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import dedent from 'dedent';
 const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
 const SITE_DIRS = ['knowledge', 'experience', 'output'];
+export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
 export function globalDir() {
     return join(os.homedir(), '.explorbot');
 }
@@ -13,12 +24,7 @@ export function globalConfigPath() {
     return join(globalDir(), 'config.js');
 }
 export function findGlobalConfig() {
-    for (const name of GLOBAL_CONFIG_NAMES) {
-        const fullPath = join(globalDir(), name);
-        if (existsSync(fullPath))
-            return fullPath;
-    }
-    return null;
+    return firstExisting(globalDir(), GLOBAL_CONFIG_NAMES);
 }
 export function isGlobalConfigPath(configPath) {
     return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
@@ -38,6 +44,47 @@ export function listSites() {
         .filter((site) => !!site)
         .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
+export function findSiteConfig(dir) {
+    return firstExisting(dir, EXPLORBOT_CONFIG_PATHS);
+}
+function ensureSiteConfig(dir, baseUrl) {
+    const existing = findSiteConfig(dir);
+    if (existing)
+        return existing;
+    const path = join(dir, EXPLORBOT_CONFIG_PATHS[0]);
+    writeFileSync(path, siteConfigTemplate(baseUrl), 'utf8');
+    return path;
+}
+export async function loadSiteConfig(dir, baseUrl) {
+    const path = ensureSiteConfig(dir, baseUrl);
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(path)).href));
+    const config = module.default || module;
+    validateSiteConfig(config, path, baseUrl);
+    return { path, config };
+}
+function validateSiteConfig(config, configPath, baseUrl) {
+    const url = config?.web?.url;
+    if (!url) {
+        throw new Error(dedent `
+      Site config is missing web.url.
+        ${configPath}
+
+      Add it so the config states which site it configures:
+        web: { url: '${baseUrl}' },
+    `);
+    }
+    const declared = URL.parse(url)?.origin;
+    if (declared === baseUrl)
+        return;
+    throw new Error(dedent `
+    Site config declares a different site.
+      ${configPath}
+      web.url:  ${url}
+      site:     ${baseUrl}
+
+    Fix web.url, or explore ${url} to register it as its own site.
+  `);
+}
 export function findSiteWith(subpath) {
     return listSites().find((site) => existsSync(join(site.dir, subpath)));
 }
@@ -88,6 +135,34 @@ export function resolveSiteTarget(target, defaultBaseUrl) {
     }
     return { baseUrl: site.url, path };
 }
+function firstExisting(dir, names) {
+    for (const name of names) {
+        const fullPath = join(dir, name);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+function siteConfigTemplate(baseUrl) {
+    return `// Config for ${baseUrl}
+// Extends ~/.explorbot/config.js — set only what differs.
+const config = {
+  web: {
+    url: '${baseUrl}',
+  },
+
+  // ai: {
+  //   model: 'openrouter/openai/gpt-oss-120b',
+  // },
+
+  // playwright: {
+  //   show: true,
+  // },
+};
+
+export default config;
+`;
+}
 function readSite(folder) {
     const dir = join(sitesDir(), folder);
     const metaPath = join(dir, 'site.json');

package/dist/src/utils/html.js

@@ -1283,6 +1283,12 @@ function cleanElement(element) {
         'aria-labelledby',
         'aria-describedby',
         'aria-owns',
+        'aria-checked',
+        'aria-expanded',
+        'aria-selected',
+        'aria-pressed',
+        'aria-current',
+        'aria-disabled',
         'role',
         'title',
         'href',

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

@@ -0,0 +1 @@
+export declare function deepMerge(target: any, source: any): any;

package/dist/src/utils/merge.js

@@ -0,0 +1,11 @@
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) && source[key].constructor === Object) {
+            result[key] = deepMerge(result[key] || {}, source[key]);
+            continue;
+        }
+        result[key] = source[key];
+    }
+    return result;
+}

package/docs/reference/commands.md

@@ -127,7 +127,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 
 `npx explorbot recommended-models` prints, per provider, the model this version recommends for each role, and the two ways to select it. Both need the provider's API key exported. Set `EXPLORBOT_AI_PROVIDER=<name>` and every role takes that provider's recommendation; leave it out and pin the roles yourself with `EXPLORBOT_AI_MODEL`, `EXPLORBOT_VISION_MODEL` and `EXPLORBOT_AGENTIC_MODEL`, each written as `provider/model-id` — the command prints those three lines filled in, ready to paste. A role a provider does not serve is named as such, so you know to pair it with another. It closes with the model variables and provider keys currently exported, and a ready-to-run OpenRouter one-liner. It reads nothing but the bundled recommendations, so it answers before any configuration exists and every CLI carries it: `npx explorbot api recommended-models`, `npx explorbot docs recommended-models`, `npx prima recommended-models`. `--json` prints the bundled recommendations as an object.
 
-Explorbot resolves its configuration in this order: the path given to `--config`, then `explorbot.config.*` in the working directory, then the `EXPLORBOT_*` variables, and finally `~/.explorbot/config.*` from the global installation. A bare provider name fills every model role from the recommendations in [Providers](../basics/providers.md); a `provider/model-id` spec pins one model and splits on the first slash, so `openrouter/openai/gpt-oss-120b:nitro` selects OpenRouter with model `openai/gpt-oss-120b:nitro`. Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`.
+Explorbot resolves its configuration in this order: the path given to `--config`, then `explorbot.config.*` in the working directory, then the `EXPLORBOT_*` variables, and finally `~/.explorbot/config.*` from the global installation, which each site then extends with its own [per-site config](configuration.md#per-site-configuration). A bare provider name fills every model role from the recommendations in [Providers](../basics/providers.md); a `provider/model-id` spec pins one model and splits on the first slash, so `openrouter/openai/gpt-oss-120b:nitro` selects OpenRouter with model `openai/gpt-oss-120b:nitro`. Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`.
 
 In this mode output goes to `~/.explorbot/sites/<host>/output/` (or `EXPLORBOT_OUTPUT`, or a temp directory with `EXPLORBOT_EPHEMERAL=1`), experience is kept beside it unless the run is ephemeral, and the Historian is off, so no generated test files appear. See [Agentic Usage](../workflow/agentic-usage.md) for the full picture.
 
@@ -934,12 +934,20 @@ See [Configuration](configuration.md#running-from-anywhere-the-global-installati
 
 ### `npx explorbot sites`
 
-List the sites registered in the global installation — folder name, base URL, and last run. Sites register themselves the first time you explore them by URL.
+List the sites registered in the global installation — folder name, base URL, last run, and the [per-site config](configuration.md#per-site-configuration) each one uses. Sites register themselves the first time you explore them by URL.
 
 ```bash
 npx explorbot sites
 ```
 
+```
+Registered sites (2):
+  app.example.com    https://app.example.com    last run 2026-09-16 09:57
+                     /home/you/.explorbot/sites/app.example.com/explorbot.config.js
+  other.example.com  https://other.example.com  last run 2026-09-01 10:00
+                     inherits global config
+```
+
 ### `npx explorbot clean [target]`
 
 Clean generated files. Targets: `states`, `research`, `plans`, `tests`, `experiences`, `output`.

package/docs/reference/configuration.md

@@ -413,7 +413,7 @@ Explorbot looks for a config file in this order:
 7. `src/config/explorbot.config.js`
 8. `src/config/explorbot.config.mjs`
 9. `src/config/explorbot.config.ts`
-10. `~/.explorbot/config.js` (or `.mjs`, `.ts`) — the global installation
+10. `~/.explorbot/config.js` (or `.mjs`, `.ts`) — the global installation, extended per site by `~/.explorbot/sites/<host>/explorbot.config.js`
 
 Or pass a custom path:
 
@@ -431,14 +431,15 @@ Env files fill in rather than override: the `.env` of the working directory is r
 
 ```
 ~/.explorbot/
-├── config.js            # AI models and keys, no URL
+├── config.js                    # AI models and keys, shared by every site
 ├── .env
 └── sites/
     ├── app.example.com/
-    │   ├── site.json    # base URL, first and last run
+    │   ├── explorbot.config.js  # this site's settings, extends config.js
+    │   ├── site.json            # base URL, first and last run
     │   ├── knowledge/
     │   ├── experience/
-    │   └── output/      # states, plans, reports, tests
+    │   └── output/              # states, plans, reports, tests
     └── localhost_3000/
 ```
 
@@ -456,6 +457,38 @@ npx explorbot sites                                   # list registered sites
 
 A `dirs` section in the global config is ignored in favor of the layout above. A `web.url` is allowed and acts as the default site for commands that pass no URL of their own.
 
+#### Per-site configuration
+
+`~/.explorbot/config.js` holds what every site shares — models, keys, reporter settings. Anything one site needs differently goes in its own `explorbot.config.js`, written into the site folder the first time that site is explored:
+
+```javascript
+// Config for https://app.example.com
+// Extends ~/.explorbot/config.js — set only what differs.
+const config = {
+  web: {
+    url: 'https://app.example.com',
+  },
+
+  ai: {
+    model: 'openrouter/anthropic/claude-sonnet-5',
+  },
+
+  playwright: {
+    show: true,
+  },
+};
+
+export default config;
+```
+
+The two are merged section by section, and the site wins. A site that overrides `ai.model` keeps the global `ai.visionModel`. Use it to give a slow or unusual app a stronger model, a visible browser, or its own reporter settings, without changing how every other site runs.
+
+`web.url` is required, and must be the site the folder belongs to — it is what makes the file readable on its own rather than meaningful only by where it sits. Explorbot refuses to run when it is missing or names a different site, instead of quietly ignoring the mismatch. To configure a different site, explore it and edit the config in its own folder.
+
+`dirs` and the base URL stay owned by the layout above and cannot be overridden. The file is never rewritten once created, and a site without one simply uses the global config.
+
+Per-site configs apply to the global installation only. A directory with its own `explorbot.config.js` and the `EXPLORBOT_*` environment mode below both resolve to a single config with nothing to extend.
+
 ### Running without a config file
 
 When the working directory has no config file and `EXPLORBOT_AI_PROVIDER` (or `EXPLORBOT_AI_MODEL`) is set, Explorbot synthesizes a configuration from `EXPLORBOT_*` environment variables, in preference to a global installation. Output goes to the site folder `~/.explorbot/sites/<host>/` (`EXPLORBOT_OUTPUT` overrides it, `EXPLORBOT_EPHEMERAL=1` sends it to a temp directory instead), experience is written there and reused by later runs against the same host unless the run is ephemeral, and the Historian is off. This is meant for one-liner CI jobs, demos, and coding agents — see [Agentic Usage](../workflow/agentic-usage.md) for the variable list and the trade-offs.