@monoes/monobrowse 1.0.12 → 1.0.14

package/src/cli/commands-element.ts

@@ -0,0 +1,305 @@
+/**
+ * Asking about elements — locating them by semantic query, and reading back
+ * whether one is visible, enabled or checked.
+ *
+ * These answer questions; they never change the page (`highlight` aside, which
+ * draws a temporary overlay).
+ */
+
+import type { ElementRef, FindAction } from '../index.js';
+import { output } from './output.js';
+import { ensureConnected, getBrowser, print, resolveElementObjectId, session } from './session.js';
+import type { Command, CommandContext, CommandResult } from './types.js';
+
+export const isvisibleCommand: Command = {
+  name: 'isvisible',
+  description: 'Check if element is visible. Usage: monomind browse isvisible @e1|"selector"',
+  options: [{ name: 'json', type: 'boolean', description: 'Output as JSON', default: false }],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const arg = ctx.args[0] as string;
+    if (!arg) throw new Error('Usage: monomind browse isvisible @e1|".selector"');
+    const objectId = await resolveElementObjectId(client, sessionId, session.refs, arg);
+    const r = await client.send<{ result: { value?: boolean } }>(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: `function(){var r=this.getBoundingClientRect(),s=window.getComputedStyle(this);return r.width>0&&r.height>0&&s.visibility!=='hidden'&&s.display!=='none'&&parseFloat(s.opacity)>0;}`,
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    const visible = r.result?.value ?? false;
+    if (ctx.flags.json) {
+      print(JSON.stringify({ visible }));
+    } else {
+      output.printSuccess(`isvisible: ${visible}`);
+    }
+    return { success: true, data: { visible } };
+  },
+};
+
+export const isenabledCommand: Command = {
+  name: 'isenabled',
+  description:
+    'Check if element is enabled (not disabled). Usage: monomind browse isenabled @e1|"selector"',
+  options: [{ name: 'json', type: 'boolean', description: 'Output as JSON', default: false }],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const arg = ctx.args[0] as string;
+    if (!arg) throw new Error('Usage: monomind browse isenabled @e1|".selector"');
+    const objectId = await resolveElementObjectId(client, sessionId, session.refs, arg);
+    const r = await client.send<{ result: { value?: boolean } }>(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: `function(){return !this.disabled;}`,
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    const enabled = r.result?.value ?? true;
+    if (ctx.flags.json) {
+      print(JSON.stringify({ enabled }));
+    } else {
+      output.printSuccess(`isenabled: ${enabled}`);
+    }
+    return { success: true, data: { enabled } };
+  },
+};
+
+export const ischeckedCommand: Command = {
+  name: 'ischecked',
+  description:
+    'Check if checkbox/radio is checked. Usage: monomind browse ischecked @e1|"selector"',
+  options: [{ name: 'json', type: 'boolean', description: 'Output as JSON', default: false }],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const arg = ctx.args[0] as string;
+    if (!arg) throw new Error('Usage: monomind browse ischecked @e1|".selector"');
+    const objectId = await resolveElementObjectId(client, sessionId, session.refs, arg);
+    const r = await client.send<{ result: { value?: boolean } }>(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: `function(){var el=this,tag=el.tagName&&el.tagName.toUpperCase();if(tag==='INPUT'&&(el.type==='checkbox'||el.type==='radio'))return el.checked;var role=el.getAttribute&&el.getAttribute('role');if(role&&['checkbox','radio','switch','menuitemcheckbox','menuitemradio','option','treeitem'].indexOf(role)!==-1)return el.getAttribute('aria-checked')==='true';var label=tag!=='LABEL'?el.closest&&el.closest('label'):el;if(label&&label.control&&(label.control.type==='checkbox'||label.control.type==='radio'))return label.control.checked;var inp=el.querySelector&&el.querySelector('input[type="checkbox"],input[type="radio"]');return inp?inp.checked:false;}`,
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    const checked = r.result?.value ?? false;
+    if (ctx.flags.json) {
+      print(JSON.stringify({ checked }));
+    } else {
+      output.printSuccess(`ischecked: ${checked}`);
+    }
+    return { success: true, data: { checked } };
+  },
+};
+
+export const isCommand: Command = {
+  name: 'is',
+  description: 'Check element state. Usage: monomind browse is visible|enabled|checked @e1',
+  options: [{ name: 'json', type: 'boolean', description: 'Output as JSON', default: false }],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const check = ctx.args[0] as string;
+    const refArg = ctx.args[1] as string;
+    if (!check || !refArg) throw new Error('Usage: monomind browse is visible|enabled|checked @e1');
+
+    const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+    const ref = await browser.resolveRef(client, sessionId, session.refs, refKey);
+
+    let result: boolean;
+    switch (check) {
+      case 'visible':
+        result = await browser.isVisible(client, sessionId, ref);
+        break;
+      case 'enabled':
+        result = await browser.isEnabled(client, sessionId, ref);
+        break;
+      case 'checked':
+        result = await browser.isChecked(client, sessionId, ref);
+        break;
+      default:
+        throw new Error(`Unknown check: ${check}. Use: visible|enabled|checked`);
+    }
+
+    if (ctx.flags.json) {
+      print(JSON.stringify({ data: { [check]: result } }));
+    } else {
+      print(result ? 'true' : 'false');
+    }
+    return { success: true, data: { [check]: result } };
+  },
+};
+
+export const findCommand: Command = {
+  name: 'find',
+  description:
+    'Find elements by semantic locators. Usage: monomind browse find role|text|label|placeholder|testid|alttext|title|selector <value> [action]',
+  options: [
+    { name: 'name', type: 'string', description: 'Filter by accessible name' },
+    { name: 'exact', type: 'boolean', description: 'Require exact match', default: false },
+    { name: 'nth', type: 'number', description: 'Find nth match' },
+    { name: 'last', type: 'boolean', description: 'Find last match', default: false },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const locator = ctx.args[0] as string;
+    const value = ctx.args[1] as string;
+    const action = ctx.args[2] as FindAction | undefined;
+
+    if (!locator || !value)
+      throw new Error(
+        'Usage: monomind browse find role|text|label|placeholder|testid|alttext|title|selector <value> [action]',
+      );
+
+    const opts = {
+      name: ctx.flags.name as string,
+      exact: ctx.flags.exact as boolean,
+      nth: ctx.flags.nth as number,
+      last: ctx.flags.last as boolean,
+    };
+
+    // alttext: find element by alt attribute (images, icons)
+    if (locator === 'alttext') {
+      // I2: use JS attribute comparison to avoid broken CSS selectors for values with spaces/quotes
+      const valJson = JSON.stringify(value);
+      const found = (await browser.evaluateJs(
+        client,
+        sessionId,
+        `(function(v){var el=document.querySelector('img[alt]')||null;var all=document.querySelectorAll('[alt]');for(var i=0;i<all.length;i++){if(all[i].getAttribute('alt')===v){all[i].setAttribute('data-mm-located','true');return true;}}return false;})(${valJson})`,
+      )) as boolean;
+      if (!found) {
+        output.printWarning(`alttext not found: ${value}`);
+        return { success: false };
+      }
+      output.printSuccess(`Found element with alt="${value}"`);
+      return { success: true, data: { alttext: value } };
+    }
+
+    // title: find element by title attribute
+    if (locator === 'title') {
+      // I2: use JS attribute comparison to avoid broken CSS selectors for values with spaces/quotes
+      const valJson = JSON.stringify(value);
+      const found = (await browser.evaluateJs(
+        client,
+        sessionId,
+        `(function(v){var all=document.querySelectorAll('[title]');for(var i=0;i<all.length;i++){if(all[i].getAttribute('title')===v){all[i].setAttribute('data-mm-located','true');return true;}}return false;})(${valJson})`,
+      )) as boolean;
+      if (!found) {
+        output.printWarning(`title not found: ${value}`);
+        return { success: false };
+      }
+      output.printSuccess(`Found element with title="${value}"`);
+      return { success: true, data: { title: value } };
+    }
+
+    let ref: ElementRef | null = null;
+    switch (locator) {
+      case 'role':
+        ref = await browser.findByRole(client, sessionId, session.refs, value, opts);
+        break;
+      case 'text':
+        ref = await browser.findByText(client, sessionId, session.refs, value, opts);
+        break;
+      case 'label':
+        ref = await browser.findByLabel(client, sessionId, session.refs, value, opts);
+        break;
+      case 'placeholder':
+        ref = await browser.findByPlaceholder(client, sessionId, session.refs, value, opts);
+        break;
+      case 'selector':
+        ref = await browser.findBySelector(client, sessionId, session.refs, value, opts);
+        break;
+      case 'testid': {
+        const sel = await browser.findByTestId(client, sessionId, value);
+        if (!sel) {
+          output.printWarning(`testid not found: ${value}`);
+          return { success: false };
+        }
+        output.printSuccess(`Found testid selector: ${sel}`);
+        return { success: true, data: { selector: sel } };
+      }
+      default:
+        throw new Error(
+          `Unknown locator: ${locator}. Use: role|text|label|placeholder|testid|alttext|title|selector`,
+        );
+    }
+
+    if (!ref) {
+      output.printWarning(`No element found: ${locator}="${value}"`);
+      return { success: false };
+    }
+
+    output.printSuccess(`Found: ${ref.role} "${ref.name}" [@${ref.ref}]`);
+
+    if (action) {
+      switch (action) {
+        case 'click':
+          await browser.clickElement(client, sessionId, ref);
+          break;
+        case 'fill': {
+          const fillValue = ctx.args[3] as string;
+          await browser.fillElement(client, sessionId, ref, fillValue ?? '');
+          break;
+        }
+        case 'type': {
+          const typeValue = ctx.args[3] as string;
+          await browser.typeIntoElement(client, sessionId, ref, typeValue ?? '');
+          break;
+        }
+        case 'hover':
+          await browser.hoverElement(client, sessionId, ref);
+          break;
+        case 'focus':
+          await browser.focusElement(client, sessionId, ref);
+          break;
+        case 'check':
+          await browser.checkElement(client, sessionId, ref, true);
+          break;
+        case 'uncheck':
+          await browser.checkElement(client, sessionId, ref, false);
+          break;
+        case 'text': {
+          const objectId = await browser.getObjectIdForRef(client, sessionId, ref);
+          if (objectId) {
+            const r = await client.send<{ result: { value?: string } }>(
+              'Runtime.callFunctionOn',
+              {
+                functionDeclaration:
+                  'function() { return this.innerText || this.textContent || ""; }',
+                objectId,
+                returnByValue: true,
+              },
+              sessionId,
+            );
+            print(r.result?.value ?? '');
+          }
+          break;
+        }
+      }
+    }
+
+    return { success: true, data: { ref } };
+  },
+};
+
+export const highlightCommand: Command = {
+  name: 'highlight',
+  description: 'Highlight an element for 2 seconds. Usage: monomind browse highlight @e1',
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const refArg = ctx.args[0] as string;
+    if (!refArg) throw new Error('Usage: monomind browse highlight @e1');
+    const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+    const ref = await browser.resolveRef(client, sessionId, session.refs, refKey);
+    await browser.highlightElement(client, sessionId, ref);
+    output.printSuccess(`Highlighted: ${ref.role} "${ref.name}"`);
+    return { success: true };
+  },
+};

package/src/cli/commands-files.ts

@@ -0,0 +1,248 @@
+/**
+ * Files in and out of the page — screenshots, PDFs, uploads and downloads.
+ */
+
+import { output } from './output.js';
+import {
+  ensureConnected,
+  getBrowser,
+  imageFormat,
+  print,
+  resolveElementObjectId,
+  session,
+} from './session.js';
+import type { Command, CommandContext, CommandResult } from './types.js';
+
+export const screenshotCommand: Command = {
+  name: 'screenshot',
+  description:
+    'Capture a screenshot. Usage: monomind browse screenshot [path] [--annotate] [--hide-scrollbars]',
+  options: [
+    { name: 'full', type: 'boolean', description: 'Full page screenshot', default: false },
+    { name: 'format', type: 'string', description: 'Format: png|jpeg|webp', default: 'png' },
+    { name: 'quality', type: 'number', description: 'Quality 0-100 for jpeg/webp', default: 80 },
+    {
+      name: 'annotate',
+      type: 'boolean',
+      description:
+        'Overlay numbered labels keyed to @eN refs from last snapshot (viewport-only; do not combine with --full)',
+      default: false,
+    },
+    {
+      name: 'hide-scrollbars',
+      type: 'boolean',
+      description: 'Hide native scrollbars via CSS injection before capture',
+      default: false,
+    },
+    { name: 'json', type: 'boolean', description: 'Output JSON with path', default: false },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+
+    const hideScrollbars = ctx.flags['hide-scrollbars'] as boolean;
+    if (hideScrollbars) {
+      await client
+        .send(
+          'Runtime.evaluate',
+          {
+            expression: `(function(){var s=document.getElementById('__mm_noscroll__');if(s)return;var el=document.createElement('style');el.id='__mm_noscroll__';el.textContent='*::-webkit-scrollbar{display:none!important}*{scrollbar-width:none!important;-ms-overflow-style:none!important}';document.head.appendChild(el);})()`,
+            returnByValue: false,
+          },
+          sessionId,
+        )
+        .catch(() => {});
+    }
+
+    const annotate = ctx.flags.annotate as boolean;
+    // eslint-disable-next-line prefer-const
+    let result!: { path: string; dataUrl: string };
+    try {
+      result = await browser.captureScreenshot(client, sessionId, {
+        path: ctx.args[0] as string,
+        fullPage: ctx.flags.full as boolean,
+        format: imageFormat(ctx.flags.format, ['png', 'jpeg', 'webp'] as const, 'png'),
+        quality: ctx.flags.quality as number,
+        annotate,
+        refs: annotate ? session.refs : undefined,
+      });
+    } finally {
+      if (hideScrollbars) {
+        await client
+          .send(
+            'Runtime.evaluate',
+            {
+              expression: `(function(){var s=document.getElementById('__mm_noscroll__');if(s)s.remove();})()`,
+              returnByValue: false,
+            },
+            sessionId,
+          )
+          .catch(() => {});
+      }
+    }
+
+    if (ctx.flags.json) {
+      print(JSON.stringify({ data: { path: result.path } }));
+    } else {
+      output.printSuccess(`Screenshot saved: ${result.path}`);
+    }
+
+    return { success: true, data: result };
+  },
+};
+
+export const uploadCommand: Command = {
+  name: 'upload',
+  description: 'Upload files to a file input. Usage: monomind browse upload @e1 ./file.pdf',
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const refArg = ctx.args[0] as string;
+    const files = ctx.args.slice(1) as string[];
+    if (!refArg || files.length === 0)
+      throw new Error('Usage: monomind browse upload @e1 <file1> [file2...]');
+    const refKey = refArg.startsWith('@') ? refArg.slice(1) : refArg;
+    const ref = await browser.resolveRef(client, sessionId, session.refs, refKey);
+    await browser.uploadFile(client, sessionId, ref, files);
+    output.printSuccess(`Uploaded ${files.length} file(s) to @${refKey}`);
+    return { success: true };
+  },
+};
+
+export const downloadCommand: Command = {
+  name: 'download',
+  description:
+    'Click an element and capture the triggered file download. Usage: monomind browse download @e1 ./output.pdf',
+  options: [
+    {
+      name: 'timeout',
+      short: 't',
+      type: 'number',
+      description: 'Max wait for download in ms',
+      default: 30000,
+    },
+    { name: 'json', type: 'boolean', description: 'Output result as JSON', default: false },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const _browser = await getBrowser();
+    const refOrSel = ctx.args[0] as string;
+    const savePath = ctx.args[1] as string;
+    if (!refOrSel || !savePath)
+      throw new Error('Usage: monomind browse download @e1|selector <save-path>');
+
+    const { mkdir } = await import('node:fs/promises');
+    const { dirname } = await import('node:path');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const downloadDir = join(tmpdir(), `mm-download-${Date.now()}`);
+    await mkdir(downloadDir, { recursive: true });
+
+    // Enable Page.downloadWillBegin / Page.downloadProgress events
+    await client
+      .send(
+        'Browser.setDownloadBehavior',
+        {
+          behavior: 'allow',
+          downloadPath: downloadDir,
+          eventsEnabled: true,
+        },
+        undefined,
+      )
+      .catch(() => {
+        // Fallback: older Chrome API (session-scoped)
+        return client
+          .send(
+            'Page.setDownloadBehavior',
+            {
+              behavior: 'allow',
+              downloadPath: downloadDir,
+            },
+            sessionId,
+          )
+          .catch(() => {});
+      });
+
+    // Track when download completes
+    const downloadPromise = new Promise<string>((resolve, reject) => {
+      let guid = '';
+      // C2: capture off() functions to avoid listener leaks in batch mode
+      const offBegin = client.on('Browser.downloadWillBegin', (params: Record<string, unknown>) => {
+        guid = params.guid as string;
+      });
+      let offProgress: (() => void) | undefined;
+      // cleanup defined before setTimeout so the timeout callback can call it
+      let timeout: ReturnType<typeof setTimeout>;
+      const cleanup = () => {
+        clearTimeout(timeout);
+        offBegin?.();
+        offProgress?.();
+      };
+      timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error('Download timed out'));
+      }, ctx.flags.timeout as number);
+      offProgress = client.on(
+        'Browser.downloadProgress',
+        async (params: Record<string, unknown>) => {
+          if (params.guid === guid && params.state === 'completed') {
+            cleanup();
+            // Find the downloaded file in downloadDir
+            const { readdir, rename, rmdir } = await import('node:fs/promises');
+            const files = await readdir(downloadDir);
+            if (files.length > 0) {
+              const src = join(downloadDir, files[0]);
+              await mkdir(dirname(savePath), { recursive: true });
+              await rename(src, savePath);
+              await rmdir(downloadDir).catch(() => {}); // I1: cleanup temp dir
+              resolve(savePath);
+            } else {
+              await rmdir(downloadDir).catch(() => {}); // I1: cleanup temp dir
+              reject(new Error('Download completed but no file found'));
+            }
+          } else if (params.guid === guid && params.state === 'canceled') {
+            cleanup();
+            reject(new Error('Download was canceled'));
+          }
+        },
+      );
+    });
+
+    // Click the element to trigger download
+    const objectId = await resolveElementObjectId(client, sessionId, session.refs, refOrSel);
+    await client.send<{ result: unknown }>(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: 'function(){ this.click(); }',
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+
+    const finalPath = await downloadPromise;
+    if (ctx.flags.json) print(JSON.stringify({ data: { path: finalPath } }));
+    else output.printSuccess(`Downloaded: ${finalPath}`);
+    return { success: true, data: { path: finalPath } };
+  },
+};
+
+export const pdfCommand: Command = {
+  name: 'pdf',
+  description: 'Save page as PDF. Usage: monomind browse pdf [path]',
+  options: [
+    { name: 'landscape', type: 'boolean', description: 'Landscape orientation', default: false },
+    { name: 'background', type: 'boolean', description: 'Print background', default: true },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const { client, sessionId } = await ensureConnected(session.port);
+    const browser = await getBrowser();
+    const path = await browser.capturePdf(client, sessionId, {
+      path: ctx.args[0] as string,
+      landscape: ctx.flags.landscape as boolean,
+      printBackground: ctx.flags.background as boolean,
+    });
+    output.printSuccess(`PDF saved: ${path}`);
+    return { success: true, data: { path } };
+  },
+};