explorbot 0.4.2 → 0.4.3

package/dist/src/api/request-store.js

@@ -10,6 +10,7 @@ export class RequestStore {
     onFailedListeners = [];
     outputDir;
     sessionStartedAt = new Date();
+    readEndpointKeys = new Set();
     constructor(outputDir) {
         this.outputDir = outputDir;
     }
@@ -17,6 +18,14 @@ export class RequestStore {
         this.capturedRequests.push(result);
         result.save(this.outputDir);
     }
+    addReadRequest(result) {
+        const key = readEndpointKey(result);
+        if (this.readEndpointKeys.has(key))
+            return;
+        this.readEndpointKeys.add(key);
+        this.capturedRequests.push(result);
+        result.save(this.outputDir);
+    }
     addFailedRequest(result) {
         this.failedRequests.push(result);
         for (const cb of this.onFailedListeners) {
@@ -47,14 +56,14 @@ export class RequestStore {
     getLastRequest() {
         return this.madeRequests[this.madeRequests.length - 1];
     }
-    toEndpointList(scopePath) {
-        let requests = this.capturedRequests;
+    toEndpointList(scopePath, methods = 'write') {
+        let requests = this.capturedRequests.filter((r) => matchesFamily(r, methods));
         if (scopePath)
-            requests = this.getWriteRequestsForScope(scopePath);
+            requests = this.getRequestsForScope(scopePath, methods);
         const seen = new Set();
         const lines = [];
         for (const req of requests) {
-            const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}`;
+            const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}${queryParamHint(req)}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
@@ -119,6 +128,12 @@ export class RequestStore {
                 const result = RequestResult.load(path.join(requestsDir, file));
                 if (existingIds.has(result.id))
                     continue;
+                if (!result.isWrite) {
+                    const key = readEndpointKey(result);
+                    if (this.readEndpointKeys.has(key))
+                        continue;
+                    this.readEndpointKeys.add(key);
+                }
                 this.capturedRequests.push(result);
             }
             catch {
@@ -127,17 +142,29 @@ export class RequestStore {
         }
     }
     getWriteRequestsForScope(scopePath) {
-        const writes = this.capturedRequests.filter((r) => r.isWrite);
+        return this.getRequestsForScope(scopePath, 'write');
+    }
+    getReadRequestsForScope(scopePath) {
+        return this.getRequestsForScope(scopePath, 'read');
+    }
+    clear() {
+        this.capturedRequests = [];
+        this.madeRequests = [];
+        this.failedRequests = [];
+        this.readEndpointKeys.clear();
+    }
+    getRequestsForScope(scopePath, methods) {
+        const candidates = this.capturedRequests.filter((r) => matchesFamily(r, methods));
         const scopeSegments = scopePath.split('/').filter(Boolean);
         if (scopeSegments.length === 0)
-            return writes;
+            return candidates;
         let scoped = [];
         let fewest = Number.POSITIVE_INFINITY;
         let ambiguous = false;
         for (const segment of scopeSegments) {
             if (isDynamicSegment(segment))
                 continue;
-            const matches = writes.filter((r) => r.path.split('/').includes(segment));
+            const matches = candidates.filter((r) => r.path.split('/').includes(segment));
             if (matches.length === 0 || matches.length > fewest)
                 continue;
             if (matches.length === fewest) {
@@ -153,18 +180,29 @@ export class RequestStore {
             return [];
         return scoped;
     }
-    clear() {
-        this.capturedRequests = [];
-        this.madeRequests = [];
-        this.failedRequests = [];
-    }
 }
 export function isFailedRequest(request) {
     return request.status >= 400 || Boolean(request.error);
 }
-function normalizePathPattern(urlPath) {
-    return urlPath
-        .split('/')
-        .map((segment) => (segment && isDynamicSegment(segment) ? '{id}' : segment))
-        .join('/');
+function readEndpointKey(result) {
+    return `${result.method} ${generalizeUrl(result.path, () => '{id}')}?${queryParamNames(result).join(',')}`;
+}
+function matchesFamily(result, methods) {
+    if (methods === 'write')
+        return result.isWrite;
+    return result.method === 'GET';
+}
+function queryParamHint(result) {
+    if (result.isWrite)
+        return '';
+    const names = queryParamNames(result);
+    if (names.length === 0)
+        return '';
+    return ` ?${names.join(',')}`;
+}
+function queryParamNames(result) {
+    const query = result.fullUrl.split('?')[1];
+    if (!query)
+        return [];
+    return [...new Set(new URLSearchParams(query).keys())].sort();
 }

package/dist/src/api/xhr-capture.d.ts

@@ -7,4 +7,6 @@ export declare class XhrCapture {
     attach(page: any): void;
     detach(page: any): void;
     captureResponse(response: any): Promise<void>;
+    captureReadEndpoint(request: any, response: any): void;
+    toHeaderMap(headers: Record<string, unknown>): Record<string, string>;
 }

package/dist/src/api/xhr-capture.js

@@ -52,24 +52,24 @@ export class XhrCapture {
             });
             this.store.addFailedRequest(failure);
         }
-        if (!WRITE_METHODS.has(method))
-            return;
         const contentType = response.headers()['content-type'] || '';
         if (!JSON_CONTENT_TYPES.test(contentType))
             return;
+        if (method === 'GET') {
+            if (status !== 200)
+                return;
+            this.captureReadEndpoint(request, response);
+            return;
+        }
+        if (!WRITE_METHODS.has(method))
+            return;
         if (status === 304)
             return;
         const parsedUrl = new URL(url);
         const origin = parsedUrl.pathname + parsedUrl.search;
         const id = generateRequestId(method, parsedUrl.pathname, 'xhr_');
-        const requestHeaders = {};
-        for (const [k, v] of Object.entries(request.headers())) {
-            requestHeaders[k] = String(v);
-        }
-        const responseHeaders = {};
-        for (const [k, v] of Object.entries(response.headers())) {
-            responseHeaders[k] = String(v);
-        }
+        const requestHeaders = this.toHeaderMap(request.headers());
+        const responseHeaders = this.toHeaderMap(response.headers());
         let rawBody = '';
         try {
             rawBody = await response.text();
@@ -103,4 +103,29 @@ export class XhrCapture {
         result.rawResponseBodyValue = rawBody;
         this.store.addCapturedRequest(result);
     }
+    captureReadEndpoint(request, response) {
+        const parsedUrl = new URL(request.url());
+        const requestHeaders = this.toHeaderMap(request.headers());
+        const result = new RequestResult({
+            id: generateRequestId('GET', parsedUrl.pathname, 'xhr_'),
+            method: 'GET',
+            path: parsedUrl.pathname,
+            fullUrl: parsedUrl.pathname + parsedUrl.search,
+            requestHeaders,
+            status: response.status(),
+            statusText: response.statusText(),
+            responseHeaders: {},
+            timing: 0,
+            timestamp: new Date(),
+        });
+        result.rawResponseBodyValue = '';
+        this.store.addReadRequest(result);
+    }
+    toHeaderMap(headers) {
+        const map = {};
+        for (const [k, v] of Object.entries(headers)) {
+            map[k] = String(v);
+        }
+        return map;
+    }
 }

package/dist/src/commands/help-json-command.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+export declare class HelpJsonCommand {
+    static register(program: Command): void;
+    static data(cmd: Command, root?: boolean): CommandDefinition;
+    static find(cmd: Command, names: string[]): Command | undefined;
+}
+interface CommandDefinition {
+    name: string;
+    description: string;
+    aliases: string[];
+    version?: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+        variadic: boolean;
+    }[];
+    options: {
+        flags: string;
+        description: string;
+        default?: unknown;
+        choices?: string[];
+    }[];
+    commands: CommandDefinition[];
+    env?: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}
+export {};

package/dist/src/commands/help-json-command.js

@@ -0,0 +1,58 @@
+import { EXPLORBOT_ENV_VARS } from '../config.js';
+const DESCRIPTION = 'Print command definitions as JSON for agents and tools';
+export class HelpJsonCommand {
+    static register(program) {
+        program
+            .command('help-json [command...]')
+            .description(DESCRIPTION)
+            .action(async (names) => {
+            const target = HelpJsonCommand.find(program, names);
+            if (!target) {
+                console.error(`Unknown command: ${names.join(' ')}`);
+                process.exit(1);
+            }
+            const json = JSON.stringify(HelpJsonCommand.data(target, target === program), null, 2);
+            await new Promise((resolve) => process.stdout.write(`${json}\n`, () => resolve()));
+        });
+    }
+    static data(cmd, root = false) {
+        const helper = cmd.createHelp();
+        const definition = {
+            name: cmd.name(),
+            description: cmd.description(),
+            aliases: cmd.aliases(),
+            arguments: cmd.registeredArguments.map((argument) => ({
+                name: argument.name(),
+                description: argument.description,
+                required: argument.required,
+                variadic: argument.variadic,
+            })),
+            options: helper.visibleOptions(cmd).map((option) => ({
+                flags: option.flags,
+                description: option.description,
+                default: option.defaultValue,
+                choices: option.argChoices,
+            })),
+            commands: helper.visibleCommands(cmd).map((sub) => HelpJsonCommand.data(sub)),
+        };
+        if (!root)
+            return definition;
+        definition.version = cmd.version();
+        definition.env = EXPLORBOT_ENV_VARS.map((variable) => ({
+            name: variable.name,
+            description: variable.description,
+            required: !!variable.required,
+        }));
+        return definition;
+    }
+    static find(cmd, names) {
+        let target = cmd;
+        for (const name of names) {
+            const sub = target.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
+            if (!sub)
+                return undefined;
+            target = sub;
+        }
+        return target;
+    }
+}

package/docs/reference/commands.md

@@ -53,6 +53,7 @@ Inside the TUI, use the matching slash command: `/explore`, `/research`, `/plan`
 | List registered sites | `npx explorbot sites` | — | Sites stored in the global installation |
 | Show resolved configuration | `npx explorbot config [url] [--json]` | `/config` | Models, config file, paths and `EXPLORBOT_*` in effect |
 | Show recommended models | `npx explorbot recommended-models [--json]` | `/recommended-models` | Models this version recommends per provider |
+| Describe commands | `npx explorbot help-json [command...]` | — | The command tree as JSON: arguments, options, defaults |
 | Clean generated files | `npx explorbot clean [target]` | `/clean [target]` | Same targets both ways |
 
 ## Common CLI Options

package/docs/reference/configuration.md

@@ -253,6 +253,10 @@ With `'playwright'`, runs are saved as `@playwright/test` `.spec.ts` files using
 
 See [AI providers](../basics/providers.md) for recommended models and provider setup.
 
+### Fisherman agent
+
+Fisherman prepares test data over the API before a scenario runs, and can also answer questions about data that already exists without creating or changing anything. Pilot reaches this read-only capability through its `askApi(question)` tool, calling it to check whether suitable data is already there — or to get the exact name or id of an existing record — before deciding whether to create anything through `precondition()`. In replicate mode, where Fisherman learns the API by watching browser traffic instead of reading a spec, the read endpoints it can query come from successful GET requests observed in the browser, alongside the write endpoints already captured from XHR traffic. The endpoint list shown to the model names only the path and its query-parameter names, never their values; the underlying capture on disk holds the full request URL and headers — what write captures already hold — but no response body.
+
 ## Playwright settings
 
 ### Browser selection