@flrande/browserctl 0.4.0 → 0.5.0-dev.19.1

package/packages/driver-remote-cdp/src/remote-cdp-driver.ts

@@ -102,6 +102,8 @@ export type RemoteCdpPage = {
   content(): Promise<string>;
   screenshot?(options?: Record<string, unknown>): Promise<unknown>;
   locator(selector: string): RemoteCdpLocator;
+  route?(url: string, handler: RemoteCdpNetworkMockHandler): Promise<void>;
+  unroute?(url: string, handler?: RemoteCdpNetworkMockHandler): Promise<void>;
   keyboard?: RemoteCdpKeyboard;
   on?(eventName: string, listener: (payload: unknown) => unknown): void;
 };
@@ -140,8 +142,12 @@ type RemoteCdpTargetOperationState = {
   uploadFiles: string[];
   dialogArmedCount: number;
   triggerCount: number;
+  nextNetworkMockNumber: number;
+  networkMocks: Map<string, RemoteCdpNetworkMockBinding>;
+  requestedDownloadPath?: string;
   downloadInFlight?: Promise<RemoteCdpDownloadArtifact>;
   latestDownload?: RemoteCdpDownloadArtifact;
+  latestRawDownload?: unknown;
 };
 
 type RemoteCdpDownloadArtifact = {
@@ -151,6 +157,12 @@ type RemoteCdpDownloadArtifact = {
   mimeType?: string;
 };
 
+type RemoteCdpNetworkMockHandler = (...args: unknown[]) => Promise<void>;
+type RemoteCdpNetworkMockBinding = {
+  urlPattern: string;
+  handler: RemoteCdpNetworkMockHandler;
+};
+
 type RemoteCdpTargetTelemetryState = {
   consoleEntries: RemoteCdpConsoleEntry[];
   requestSummaries: RemoteCdpNetworkRequestSummary[];
@@ -196,7 +208,9 @@ function createTargetOperationState(): RemoteCdpTargetOperationState {
   return {
     uploadFiles: [],
     dialogArmedCount: 0,
-    triggerCount: 0
+    triggerCount: 0,
+    nextNetworkMockNumber: 1,
+    networkMocks: new Map<string, RemoteCdpNetworkMockBinding>()
   };
 }
 
@@ -894,21 +908,26 @@ export function createRemoteCdpDriver(
     profileId: ProfileId,
     targetId: TargetId,
     tab: RemoteCdpTab,
-    operationState: RemoteCdpTargetOperationState
+    operationState: RemoteCdpTargetOperationState,
+    requestedPath?: string
   ): Promise<RemoteCdpDownloadArtifact> {
+    if (requestedPath !== undefined) {
+      operationState.requestedDownloadPath = requestedPath;
+    }
+
     if (operationState.downloadInFlight !== undefined) {
       return operationState.downloadInFlight;
     }
 
-    const fallbackPath = createDownloadPath(
-      profileId,
-      targetId,
-      Math.max(operationState.triggerCount, 1)
-    );
+    const fallbackPath =
+      operationState.requestedDownloadPath ??
+      createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
     const waitForEventMethod = getObjectMethod(tab.page, "waitForEvent");
     if (typeof waitForEventMethod !== "function") {
       const artifact: RemoteCdpDownloadArtifact = { path: fallbackPath };
+      operationState.requestedDownloadPath = undefined;
       operationState.latestDownload = artifact;
+      operationState.latestRawDownload = undefined;
       const resolved = Promise.resolve(artifact);
       operationState.downloadInFlight = resolved;
       return resolved;
@@ -916,8 +935,13 @@ export function createRemoteCdpDriver(
 
     const inFlight = (async () => {
       const rawDownload = await waitForEventMethod.call(tab.page, "download");
-      const artifact = await readDownloadArtifact(rawDownload, fallbackPath);
+      operationState.latestRawDownload = rawDownload;
+      const persistedPath =
+        operationState.requestedDownloadPath ??
+        createDownloadPath(profileId, targetId, Math.max(operationState.triggerCount, 1));
+      const artifact = await readDownloadArtifact(rawDownload, persistedPath);
       operationState.latestDownload = artifact;
+      operationState.requestedDownloadPath = undefined;
       return artifact;
     })().finally(() => {
       if (operationState.downloadInFlight === inFlight) {
@@ -929,6 +953,30 @@ export function createRemoteCdpDriver(
     return inFlight;
   }
 
+  async function resolveDownloadArtifactPath(
+    operationState: RemoteCdpTargetOperationState,
+    artifact: RemoteCdpDownloadArtifact,
+    requestedPath?: string
+  ): Promise<RemoteCdpDownloadArtifact> {
+    if (requestedPath === undefined || requestedPath.trim().length === 0 || artifact.path === requestedPath) {
+      return artifact;
+    }
+
+    const failurePrefix = `Failed to persist download to requested path: ${requestedPath}`;
+    const saveAsMethod = getObjectMethod(operationState.latestRawDownload, "saveAs");
+    if (typeof saveAsMethod !== "function") {
+      throw new Error(failurePrefix);
+    }
+
+    try {
+      await saveAsMethod.call(operationState.latestRawDownload, requestedPath);
+      return { ...artifact, path: requestedPath };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(message.length > 0 ? `${failurePrefix} (${message})` : failurePrefix);
+    }
+  }
+
   return {
     status: async () => ({ kind: "remote-cdp", connected: browser !== undefined, endpoint }),
     listProfiles: async () => {
@@ -1163,6 +1211,141 @@ export function createRemoteCdpDriver(
             await tab.page.keyboard.press(key);
             return { ok: true, executed: true };
           }
+          case "networkMockAdd": {
+            const urlPattern = readActionPayloadString(payload, "urlPattern");
+            if (urlPattern === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.urlPattern is required for networkMockAdd action."
+              };
+            }
+
+            const routeMethod = getObjectMethod(tab.page, "route");
+            if (typeof routeMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const methodFilter = readActionPayloadString(payload, "method")?.toUpperCase();
+            const status = readActionPayloadNumber(payload, "status") ?? 200;
+            if (!Number.isInteger(status) || status < 100 || status > 599) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.status must be an integer between 100 and 599 for networkMockAdd action."
+              };
+            }
+            const body = readActionPayloadString(payload, "body") ?? "";
+            const contentType = readActionPayloadString(payload, "contentType") ?? "text/plain";
+            const mockId = `mock:${operationState.nextNetworkMockNumber}`;
+            operationState.nextNetworkMockNumber += 1;
+            const handler: RemoteCdpNetworkMockHandler = async (...args) => {
+              const route = args[0];
+              const explicitRequest = args[1];
+              const request = explicitRequest ?? readObjectMethod<unknown>(route, "request");
+              if (methodFilter !== undefined) {
+                const requestMethod = readObjectMethod<string>(request, "method");
+                if (requestMethod?.toUpperCase() !== methodFilter) {
+                  const continueMethod = getObjectMethod(route, "continue");
+                  if (typeof continueMethod === "function") {
+                    await continueMethod.call(route);
+                    return;
+                  }
+
+                  const fallbackMethod = getObjectMethod(route, "fallback");
+                  if (typeof fallbackMethod === "function") {
+                    await fallbackMethod.call(route);
+                    return;
+                  }
+
+                  return;
+                }
+              }
+
+              const fulfillMethod = getObjectMethod(route, "fulfill");
+              if (typeof fulfillMethod !== "function") {
+                return;
+              }
+
+              await fulfillMethod.call(route, {
+                status,
+                body,
+                headers: {
+                  "content-type": contentType
+                }
+              });
+            };
+
+            await routeMethod.call(tab.page, urlPattern, handler);
+            operationState.networkMocks.set(mockId, {
+              urlPattern,
+              handler
+            });
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                mockId,
+                urlPattern,
+                ...(methodFilter !== undefined ? { method: methodFilter } : {}),
+                status
+              }
+            };
+          }
+          case "networkMockClear": {
+            const unrouteMethod = getObjectMethod(tab.page, "unroute");
+            if (typeof unrouteMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const mockId = readActionPayloadString(payload, "mockId");
+            if (mockId !== undefined) {
+              const binding = operationState.networkMocks.get(mockId);
+              if (binding === undefined) {
+                return {
+                  ok: false,
+                  executed: false,
+                  error: `Unknown network mock id: ${mockId}`
+                };
+              }
+
+              await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
+              operationState.networkMocks.delete(mockId);
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  cleared: 1,
+                  mockId
+                }
+              };
+            }
+
+            let cleared = 0;
+            for (const [registeredId, binding] of operationState.networkMocks.entries()) {
+              try {
+                await unrouteMethod.call(tab.page, binding.urlPattern, binding.handler);
+              } catch {
+                // Ignore per-route cleanup failures.
+              }
+              operationState.networkMocks.delete(registeredId);
+              cleared += 1;
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cleared
+              }
+            };
+          }
           case "domQuery": {
             const selector = readActionPayloadString(payload, "selector");
             if (selector === undefined) {
@@ -2002,11 +2185,47 @@ export function createRemoteCdpDriver(
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
       operationState.dialogArmedCount += 1;
     },
-    waitDownload: async (targetId, profile) => {
+    waitDownload: async (targetId, profile, path) => {
       const profileId = resolveProfileId(profile);
       const { tab } = requireTargetInProfile(profileId, targetId);
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
-      const download = await ensureDownloadInFlight(profileId, targetId, tab, operationState);
+      const requestedPath = path !== undefined && path.trim().length > 0 ? path : undefined;
+      if (operationState.downloadInFlight === undefined && operationState.latestDownload !== undefined) {
+        const download = await resolveDownloadArtifactPath(
+          operationState,
+          { ...operationState.latestDownload },
+          requestedPath
+        );
+        operationState.latestDownload = undefined;
+        operationState.latestRawDownload = undefined;
+        operationState.requestedDownloadPath = undefined;
+        return {
+          path: download.path,
+          profile: profileId,
+          targetId,
+          endpoint,
+          uploadFiles: [...operationState.uploadFiles],
+          dialogArmedCount: operationState.dialogArmedCount,
+          triggerCount: operationState.triggerCount,
+          ...(download.suggestedFilename !== undefined
+            ? { suggestedFilename: download.suggestedFilename }
+            : {}),
+          ...(download.url !== undefined ? { url: download.url } : {}),
+          ...(download.mimeType !== undefined ? { mimeType: download.mimeType } : {})
+        };
+      }
+
+      const inFlightDownload = await ensureDownloadInFlight(
+        profileId,
+        targetId,
+        tab,
+        operationState,
+        requestedPath
+      );
+      const download = await resolveDownloadArtifactPath(operationState, inFlightDownload, requestedPath);
+      operationState.latestDownload = undefined;
+      operationState.latestRawDownload = undefined;
+      operationState.requestedDownloadPath = undefined;
 
       return {
         path: download.path,
@@ -2028,6 +2247,9 @@ export function createRemoteCdpDriver(
       const { tab } = requireTargetInProfile(profileId, targetId);
       const operationState = getOrCreateTargetOperationState(profileId, targetId);
       operationState.triggerCount += 1;
+      operationState.latestDownload = undefined;
+      operationState.latestRawDownload = undefined;
+      operationState.requestedDownloadPath = undefined;
       void ensureDownloadInFlight(profileId, targetId, tab, operationState);
     },
     getConsoleEntries: (targetId, profile) => {

package/packages/transport-mcp-stdio/src/tool-map.ts

@@ -28,6 +28,11 @@ export const V1_TOOL_NAMES = [
   "browser.dom.queryAll",
   "browser.element.screenshot",
   "browser.a11y.snapshot",
+  "browser.wait.element",
+  "browser.wait.text",
+  "browser.wait.url",
+  "browser.network.list",
+  "browser.network.harExport",
   "browser.act",
   "browser.upload.arm",
   "browser.dialog.arm",
@@ -42,7 +47,19 @@ export const V1_TOOL_NAMES = [
   "browser.frame.list",
   "browser.frame.snapshot",
   "browser.console.list",
-  "browser.network.responseBody"
+  "browser.network.responseBody",
+  "browser.memory.status",
+  "browser.memory.resolve",
+  "browser.memory.upsert",
+  "browser.memory.list",
+  "browser.memory.inspect",
+  "browser.memory.delete",
+  "browser.memory.purge",
+  "browser.memory.mode.set",
+  "browser.memory.ttl.set",
+  "browser.trace.get",
+  "browser.session.list",
+  "browser.session.drop"
 ] as const;
 
 const browserStatusHandler: ToolHandler<{ kind: "stdio"; ready: true }> = async () =>