webscope-mcp 0.2.0__py3-none-any.whl

webscope_adaptadores/web/form.js

@@ -0,0 +1,333 @@
+/* Ayudante de formularios para `javascript_tool`: llena por etiqueta, lee de vuelta cada campo y guarda en la captura lo que había antes y después.
+ * `adaptadores/e2e_chrome.py --form` lo entrega listo para pegar; requiere la captura (`--captura`) ya instalada en la página. */
+(() => {
+  const est = window.__e2e;
+  if (!est || !est.detalle) return 'sin captura: pega primero e2e_chrome --captura';
+  const w = (ms) => new Promise((r) => setTimeout(r, ms));
+  const esperar = async (fn, ms = 2500) => {
+    const fin = performance.now() + ms;
+    while (performance.now() < fin) { const v = fn(); if (v) return v; await w(80); }
+    return null;
+  };
+  const base = () => document.querySelector('main') || document.body;
+  const dlg = () => [...document.querySelectorAll('.v-overlay--active')].reverse().find((o) => o.querySelector('.v-card .v-field, .v-card button'))
+    || [...document.querySelectorAll('[role=dialog],[aria-modal=true],.modal.show')].reverse().find((o) => o.offsetParent || o.getClientRects().length)
+    || base();
+  const etiqueta = (f) => (f.querySelector('label')?.textContent || '').trim().replace(/\*$/, '').trim();
+  const esSelect = (f) => !!f.closest('.v-select,.v-autocomplete,.v-combobox');
+  /** Campo marcado obligatorio por `*` en la etiqueta o por `required`/`aria-required` en su entrada. */
+  const obligatorio = (f) => /\*\s*$/.test(f.querySelector('label')?.textContent || '') || !!f.querySelector('input[required],textarea[required],[aria-required=true]');
+  const valor = (f) => {
+    const i = f.querySelector('input,textarea');
+    const visto = esSelect(f) ? [...f.querySelectorAll('.v-select__selection-text,.v-chip__content,.v-autocomplete__selection:not(:has(.v-select__selection-text,.v-chip__content))')].map((s) => s.textContent.trim()).join('|') : '';
+    return { v: i?.value ?? '', visto };
+  };
+  const visibles = () => [...dlg().querySelectorAll('.v-field')].filter((f) => f.offsetParent && etiqueta(f));
+  /** Etiqueta única del campo: la repetida lleva `#n` (`Unidad#2`). */
+  const nombre = (f, todos) => {
+    const igual = todos.filter((x) => etiqueta(x) === etiqueta(f));
+    return igual.length > 1 && igual.indexOf(f) > 0 ? `${etiqueta(f)}#${igual.indexOf(f) + 1}` : etiqueta(f);
+  };
+  const campos = () => { const t = visibles(); return Object.fromEntries(t.map((f) => [nombre(f, t), valor(f)])); };
+  /** Campo por etiqueta exacta; si no la hay, el único cuya etiqueta contiene `l`. */
+  const campo = (l) => {
+    const t = visibles();
+    const parecidos = t.filter((f) => nombre(f, t).toLowerCase().includes(String(l).toLowerCase()));
+    return t.find((f) => nombre(f, t) === l) || (parecidos.length === 1 ? parecidos[0] : undefined);
+  };
+  const menu = () => [...document.querySelectorAll('.v-overlay--active.v-menu .v-list')].pop();
+  const texto = (e) => (e.innerText || e.textContent || '').replace(/\s+/g, ' ').trim();
+  const vivos = (sel, raiz = document) => [...raiz.querySelectorAll(sel)].filter((e) => e.offsetParent || e.getClientRects().length);
+  const PULSABLE = 'button,a,[role=button],[role=tab],[role=menuitem],[role=option],.v-tab,.v-list-item,.v-chip,input[type=checkbox],input[type=radio]';
+  /** Espera a que el DOM pase 400 ms sin cambios y sin peticiones pendientes, hasta `ms`; devuelve los ms que tardó o -1. */
+  const calma = async (ms = 6000) => {
+    const t0 = performance.now();
+    let ultimo = t0;
+    const obs = new MutationObserver(() => { ultimo = performance.now(); });
+    obs.observe(document.body, { childList: true, subtree: true, characterData: true });
+    while (performance.now() - t0 < ms) {
+      await w(100);
+      if ((est.pendientes ?? 0) <= 0 && performance.now() - ultimo > 400) break;
+    }
+    obs.disconnect();
+    const t = Math.round(performance.now() - t0);
+    return t < ms ? t : -1;
+  };
+  /** Elemento pulsable visible por texto (exacto, luego contenido) o por selector CSS si empieza por `#`, `.` o `[`. */
+  const buscarPulsable = (q, raiz) => {
+    if (/^[#.[]/.test(q)) return vivos(q, raiz)[0];
+    const t = q.toLowerCase();
+    const todos = vivos(PULSABLE, raiz);
+    return todos.find((e) => texto(e).toLowerCase() === t || e.getAttribute('aria-label')?.toLowerCase() === t)
+      || todos.find((e) => texto(e).toLowerCase().includes(t));
+  };
+
+  /** Nombre estable de un pulsable: su texto, su aria-label o su icono `mdi-*`. */
+  const nombrePulsable = (e) => texto(e) || e.getAttribute('aria-label') || (e.innerHTML.match(/mdi-[\w-]+/) || [''])[0];
+  /** Vacía el v-model del VSelect/VAutocomplete/VCombobox que contiene `c`; false si Vue no expone el componente (build de producción). */
+  const vaciarModelo = (c) => {
+    let i = c?.__vueParentComponent;
+    while (i && !/^V(Select|Autocomplete|Combobox)$/.test(i.type?.name || '')) i = i.parent;
+    const emitir = i?.vnode.props?.['onUpdate:modelValue'];
+    if (!emitir) return false;
+    [].concat(emitir).forEach((f) => f(i.props.multiple ? [] : null));
+    return true;
+  };
+  let refs = [];
+  /** Lista numerada de lo pulsable visible en `raiz` («3 Guardar»); `__f.clic(3)` pulsa ese número. */
+  const numerar = (raiz) => {
+    refs = [null, ...vivos(PULSABLE, raiz).filter((e) => nombrePulsable(e))].slice(0, 41);
+    return refs.slice(1).map((e, i) => `${i + 1} ${nombrePulsable(e).slice(0, 40)}`);
+  };
+  est.pasos ||= [];
+  let grabar = true;
+  /** Anota un paso para exportarlo luego como test repetible. */
+  const anotar = (m, ...args) => grabar && est.pasos.push([m, ...args]);
+
+  window.__f = {
+    inicial: null,
+    /** Foto de los campos del formulario abierto; se compara al pulsar el botón de guardar. */
+    abrir() { this.inicial = campos(); return Object.keys(this.inicial).length; },
+    campos,
+    /** Etiquetas de los campos obligatorios del formulario abierto. */
+    obligatorios() { const t = visibles(); return t.filter(obligatorio).map((f) => nombre(f, t)); },
+    /** Valor fijo por campo obligatorio según su tipo, para que todas las pruebas usen los mismos datos; texto con `prefijo`.
+     * shortcut: solo ve campos `.v-field` con etiqueta (no interruptores ni selectores propios); fecha sin `type=date` va en dd/mm/aaaa. */
+    valores(prefijo = 'ZZ_E2E') {
+      const t = visibles();
+      const hoy = new Date();
+      const dos = (n) => String(n).padStart(2, '0');
+      return Object.fromEntries(t.filter(obligatorio).map((f) => {
+        const l = nombre(f, t);
+        const i = f.querySelector('input,textarea');
+        if (esSelect(f)) return [l, ''];
+        if (i?.type === 'number') return [l, '1'];
+        if (i?.type === 'date') return [l, `${hoy.getFullYear()}-${dos(hoy.getMonth() + 1)}-${dos(hoy.getDate())}`];
+        if (i?.type === 'email') return [l, `${prefijo.toLowerCase()}@ejemplo.test`];
+        if (/fecha|date/i.test(l)) return [l, `${dos(hoy.getDate())}/${dos(hoy.getMonth() + 1)}/${hoy.getFullYear()}`];
+        const v = `${prefijo}_${l.normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^\w]+/g, '_').toUpperCase()}`;
+        return [l, i?.maxLength > 0 ? v.slice(0, i.maxLength) : v];
+      }));
+    },
+    /** Intenta guardar con cada obligatorio vacío, uno por vez (desplegables con su botón de borrar), y dice si la app lo rechazó;
+     * nunca vacía `clave` (por defecto el primer obligatorio de texto), que lleva el prefijo con el que se limpia la fila. */
+    async probarObligatorios({ valores = this.valores(), guardar = 'Guardar', clave } = {}) {
+      const t = visibles();
+      const todos = t.filter(obligatorio).map((f) => nombre(f, t));
+      clave ??= t.filter((f) => obligatorio(f) && !esSelect(f)).map((f) => nombre(f, t))[0];
+      const r = [];
+      grabar = false;
+      try {
+      for (const l of todos) {
+        if (l === clave) { r.push({ campo: l, resultado: 'no probado: campo clave' }); continue; }
+        for (const [k, v] of Object.entries(valores)) await this.poner(k, v);
+        if (esSelect(campo(l))) {
+          const x = campo(l).querySelector('.v-field__clearable i,.v-field__clearable button,[aria-label*="clear" i],[aria-label*="borrar" i]');
+          if (x) x.click();
+          else if (!vaciarModelo(campo(l))) { r.push({ campo: l, resultado: 'no probado: desplegable sin botón de borrar' }); continue; }
+          await w(200);
+          if (valor(campo(l)).v || valor(campo(l)).visto) { r.push({ campo: l, resultado: 'no probado: el desplegable no se vació' }); continue; }
+        } else await this.poner(l, '');
+        const p = await this.pulsar(guardar);
+        const guardo = (p.red || []).find((x) => /^(POST|PUT|PATCH) 2/.test(x));
+        if (guardo) {
+          const d = est.detalle.filter((x) => x.m !== 'GET').pop();
+          r.push({ campo: l, resultado: `❌ guardó sin el campo (${guardo}${d?.r?.id ? `, id ${d.r.id}` : ''}): límpialo` });
+          break;
+        }
+        const motivo = p.errores?.join('; ') || (p.red || []).find((x) => / 4\d\d /.test(x)) || (p.deshabilitado || p.error ? 'botón sin efecto o deshabilitado' : '');
+        r.push({ campo: l, resultado: motivo ? `rechazado: ${motivo}` : '¿? sin red, sin error y sin guardar' });
+      }
+      } finally { grabar = true; }
+      return r;
+    },
+    /** Pone `v` en el campo de etiqueta `l` y lo lee de vuelta; devuelve '' si quedó o el motivo si no. */
+    async poner(l, v) {
+      const c = campo(l);
+      if (!c) return `❌ «${l}»: no hay campo con esa etiqueta`;
+      const i = c.querySelector('input,textarea');
+      if (!esSelect(c)) {
+        i.value = v; i.dispatchEvent(new Event('input', { bubbles: true })); i.dispatchEvent(new Event('change', { bubbles: true }));
+        anotar('poner', l, v);
+        await w(150);
+        return String(campo(l).querySelector('input,textarea').value) === String(v) ? '' : `❌ «${l}»: pedí ${v}, quedó ${campo(l).querySelector('input,textarea').value}`;
+      }
+      document.body.click(); await w(150);
+      let lista = null;
+      for (let intento = 0; intento < 2 && !lista; intento++) {
+        i.focus(); (c.querySelector('.v-field__input') || c).dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+        if (c.closest('.v-autocomplete,.v-combobox') && v) { i.value = v; i.dispatchEvent(new Event('input', { bubbles: true })); }
+        if (intento) i.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+        lista = await esperar(() => menu()?.querySelector('.v-list-item') && menu());
+      }
+      if (!lista) return `❌ «${l}»: el menú no abrió`;
+      const items = [...lista.querySelectorAll('.v-list-item')];
+      const x = v ? items.find((e) => e.textContent.trim() === v) || items.find((e) => e.textContent.includes(v)) : items[0];
+      if (!x) { document.body.click(); return `❌ «${l}»: no hay opción ${v}; hay ${items.map((e) => e.textContent.trim()).slice(0, 8).join(', ')}`; }
+      const texto = x.textContent.trim();
+      const buscado = texto.split(/\s{2,}|Documento:/)[0].trim();
+      anotar('elegir', l, texto);
+      x.click(); await w(250); document.body.click();
+      const quedo = (await esperar(() => { const q = campo(l) && valor(campo(l)).visto; return q && q.includes(buscado) && q; }, 1500)) || valor(campo(l)).visto;
+      return quedo.includes(buscado) ? '' : `❌ «${l}»: elegí ${texto}, se ve ${quedo || 'vacío'}`;
+    },
+    /** Llena varios campos; devuelve los que no quedaron y los obligatorios que siguen vacíos. */
+    async llenar(o) {
+      const m = [];
+      for (const [l, v] of Object.entries(o)) { const r = await this.poner(l, v); if (r) m.push(r); }
+      const ahora = campos();
+      for (const l of this.obligatorios()) if (!(l in o) && ahora[l] && !ahora[l].v && !ahora[l].visto) m.push(`❌ «${l}»: obligatorio y vacío; llénalo antes de guardar`);
+      for (const l of Object.keys(o)) if ((o[l] !== '' || (campo(l) && esSelect(campo(l)))) && !m.some((x) => x.includes(`«${l}»`)) && ahora[l] && !ahora[l].v && !ahora[l].visto) m.push(`❌ «${l}»: quedó y luego se vació (otro campo lo reinició)`);
+      return m;
+    },
+    /** Compara el formulario reabierto con lo guardado `o` ({etiqueta: valor}); devuelve los campos que no persistieron. */
+    verificar(o) {
+      anotar('verificar', o);
+      const ahora = campos();
+      return Object.entries(o).filter(([l, v]) => !ahora[l] || (String(ahora[l].v) !== String(v) && !ahora[l].visto.includes(v)))
+        .map(([l, v]) => `❌ «${l}»: guardé ${v}, al reabrir ${ahora[l] ? ahora[l].visto || ahora[l].v || 'vacío' : 'no está'}`);
+    },
+    /** Pulsa el botón `txt` del diálogo de arriba (o de la página) y espera a que se calme; avisa si el clic no cambió nada.
+     * La siguiente escritura capturada lleva {etiqueta: [antes, después]} de cada campo. */
+    async pulsar(txt, ms = 6000) {
+      const tiene = (o) => vivos('button', o).some((e) => texto(e).toLowerCase() === txt.toLowerCase());
+      const capas = [...document.querySelectorAll('.v-overlay--active,[role=dialog]')].reverse();
+      const raiz = [dlg(), ...capas].find(tiene) || dlg();
+      const avisoAntes = vivos('.Toastify__toast,.v-snackbar__content', document).map((t) => texto(t)).join('|');
+      const botones = vivos('button', raiz);
+      const b = botones.find((e) => texto(e).toLowerCase() === txt.toLowerCase());
+      if (!b) return { error: `sin botón ${txt}`, hay: botones.map((e) => e.textContent.trim()).filter(Boolean) };
+      const ahora = campos();
+      const ob = new Set(this.obligatorios());
+      est.formPend = Object.keys(ahora).length
+        ? Object.fromEntries(Object.entries(ahora).map(([k, x]) => [k, [this.inicial?.[k]?.v ?? null, x.v, x.visto, ob.has(k) ? 1 : 0]]))
+        : null;
+      const desde = est.detalle.length;
+      const deshabilitado = b.disabled;
+      await w(200);
+      b.click(); await w(150); await calma(ms);
+      this.inicial = null;
+      const errores = vivos('.v-messages__message', dlg()).map(texto).filter(Boolean);
+      const red = est.detalle.slice(desde).filter((d) => d.m !== 'GET').map((d) => `${d.m} ${d.s} ${d.u.replace(/^.*\/api\//, '')}`);
+      if (!red.length) est.formPend = null;
+      anotar('pulsar', txt, red.map((x) => x.replace(/ \d+ /, ' ').replace(/\/\d+(?=\/|$)/g, '/{}')));
+      const avisos = vivos('.Toastify__toast,.v-snackbar__content', document).map((t) => texto(t));
+      const aviso = avisos.map((t) => t.slice(0, 110)).pop();
+      const sinEfecto = !red.length && avisos.join('|') === avisoAntes && !errores.length && b.isConnected && (b.offsetParent || b.getClientRects().length);
+      const otro = !red.length && !b.isConnected && vivos('button', dlg()).some((e) => texto(e).toLowerCase() === txt.toLowerCase());
+      return { ...(deshabilitado ? { deshabilitado } : {}), red, aviso, ...(errores.length ? { errores } : {}),
+        ...(otro ? { otroDialogo: `se abrió otro diálogo con «${txt}» (doble confirmación): vuelve a llamar __f.pulsar('${txt}')` } : {}),
+        ...(sinEfecto ? { error: `pulsé «${txt}» y no pasó nada: sin red, sin aviso y el botón sigue ahí; prueba __f.clic('${txt}')` } : {}) };
+    },
+    /** Abre el menú ⋮ de la fila que cumple `re`; sin `txt` devuelve sus opciones, con `txt` pulsa esa y devuelve el diálogo que abrió. */
+    async menu(re, txt, ms = 1500) {
+      const items = () => [...document.querySelectorAll('.v-overlay--active.v-menu .v-list-item')];
+      if (!items().length) {
+        const tr = [...document.querySelectorAll('tbody tr')].find((t) => re.test(t.textContent));
+        if (!tr) return 'sin fila';
+        tr.querySelector('.mdi-dots-vertical')?.closest('button')?.click(); await w(600);
+      }
+      if (!txt) return items().map((e) => e.textContent.trim());
+      const it = items().find((e) => e.textContent.trim() === txt);
+      if (!it) return `sin ${txt}; hay ${items().map((e) => e.textContent.trim()).join(', ')}`;
+      it.click(); await w(150); await calma(ms);
+      return [...document.querySelectorAll('.v-overlay--active:not(.v-menu)')].map((o) => o.innerText.replace(/\s+/g, ' ').slice(0, 200));
+    },
+    /** Pulsa el icono de la fila que cumple `re`; `icono` es parte de su clase (p. ej. pencil, trash). Si la fila no está en la
+     * página, escribe el texto de `re` en el buscador de la lista y vuelve a mirar. */
+    async fila(re, icono, ms = 2500) {
+      if (dlg() !== base()) return 'diálogo abierto: ciérralo antes';
+      const buscar = () => [...document.querySelectorAll('tbody tr')].find((t) => re.test(t.textContent));
+      let tr = buscar();
+      const caja = !tr && visibles().find((f) => /buscar|search/i.test(etiqueta(f)) && !esSelect(f));
+      if (caja) {
+        const i = caja.querySelector('input');
+        i.value = re.source.replace(/[\\^$.*+?()[\]{}|]/g, ''); i.dispatchEvent(new Event('input', { bubbles: true }));
+        await calma(ms);
+        tr = await esperar(buscar, ms);
+      }
+      if (!tr) return 'sin fila';
+      anotar('fila', re.source, icono);
+      const b = [...tr.querySelectorAll('button,a')].find((e) => e.innerHTML.includes(icono));
+      if (!b) return `sin ${icono}`;
+      if (b.disabled) return `${icono} deshabilitado`;
+      b.click(); await w(150); await calma(ms);
+      return 'ok';
+    },
+    /** La pantalla en texto corto, en lugar de una captura: ruta, título, diálogo abierto, botones, pestañas, filas, avisos y errores. */
+    estado() {
+      const d = dlg();
+      const enDialogo = d !== base();
+      const filas = vivos('tbody tr', d);
+      const r = {
+        ruta: location.pathname + location.search,
+        titulo: texto(vivos('h1,.v-toolbar-title,.v-card-title', d)[0] || document.createElement('i')).slice(0, 80),
+        ...(enDialogo ? { dialogo: true } : {}),
+        botones: [...new Set(vivos('button', d).map(texto).filter(Boolean))].slice(0, 15),
+        pulsables: numerar(d),
+        pestanas: vivos('.v-tab,[role=tab]', d).map((e) => (e.classList.contains('v-tab--selected') || e.getAttribute('aria-selected') === 'true' ? '*' : '') + texto(e)).slice(0, 10),
+        filas: filas.length,
+        primeras: filas.slice(0, 3).map((t) => texto(t).slice(0, 100)),
+        avisos: vivos('.Toastify__toast,.v-snackbar__content,.v-alert', document).map((e) => texto(e).slice(0, 110)),
+        errores: vivos('.v-messages__message', d).map(texto).filter(Boolean).slice(0, 8),
+        cargando: vivos('.v-progress-linear--active,.v-progress-circular,.v-skeleton-loader').length,
+      };
+      return Object.fromEntries(Object.entries(r).filter(([, v]) => v !== '' && v !== 0 && !(Array.isArray(v) && !v.length)));
+    },
+    /** Pulsa por número de `estado().pulsables`, por texto o por selector (en el diálogo abierto si lo hay) y espera a que la
+     * pantalla se calme; devuelve el estado o el error. */
+    async clic(q, ms = 6000) {
+      const e = typeof q === 'number' ? (refs[q]?.isConnected ? refs[q] : null) : buscarPulsable(q, dlg()) || buscarPulsable(q, document);
+      if (!e) return { error: `sin «${q}»`, hay: numerar(dlg()) };
+      if (e.disabled || e.getAttribute('aria-disabled') === 'true') return { error: `«${q}» deshabilitado` };
+      anotar('clic', nombrePulsable(e));
+      e.scrollIntoView({ block: 'center' }); e.click();
+      const t = await calma(ms);
+      return { ms: t, ...this.estado() };
+    },
+    /** Espera hasta `ms` a que aparezca un texto o selector visible; devuelve los ms que tardó o un error. */
+    async esperar(q, ms = 8000) {
+      const t0 = performance.now();
+      const hay = () => (/^[#.[]/.test(q) ? vivos(q)[0] : document.body.innerText.toLowerCase().includes(q.toLowerCase()));
+      return (await esperar(hay, ms)) ? { ms: Math.round(performance.now() - t0) } : { error: `no apareció «${q}» en ${ms} ms`, ...this.estado() };
+    },
+    /** Navega sin recargar (los ayudantes siguen instalados): con el router de Vue si lo hay, si no con history y popstate; espera a que se calme. */
+    async ir(ruta, ms = 8000) {
+      const router = document.querySelector('#app')?.__vue_app__?.config.globalProperties.$router;
+      anotar('ir', ruta);
+      try {
+        if (router) await router.push(ruta);
+        else { history.pushState({}, '', ruta); dispatchEvent(new PopStateEvent('popstate', { state: {} })); }
+      } catch (e) { return { error: String(e).slice(0, 100) }; }
+      const t = await calma(ms);
+      return { ms: t, ...this.estado() };
+    },
+    /** Corre pasos [[metodo, ...args], ...] en una sola llamada y para en el primero que falla; devuelve una línea por paso.
+     * Acepta los pasos anotados (`fila` con texto, `elegir`, `pulsar` con la red esperada); `sello: true` añade un sufijo
+     * por corrida a los valores ZZ_E2E… para no chocar con filas de corridas anteriores. */
+    async pasos(lista, { sello } = {}) {
+      const S = sello && Date.now().toString(36).toUpperCase();
+      const sellar = (v, fila) => typeof v === 'string' ? (/^ZZ_E2E/.test(v) ? v.replace(/_(?=[A-Z]*\d)[0-9A-Z]{8}$/, '') + (fila ? `.*_${S}` : `_${S}`) : v)
+        : v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, sellar(x)])) : v;
+      const log = [];
+      for (let [m, ...args] of lista) {
+        if (S) args = args.map((x, i) => sellar(x, m === 'fila' && i === 0));
+        if (m === 'fila' && typeof args[0] === 'string') args[0] = new RegExp(args[0]);
+        if (m === 'elegir') m = 'poner';
+        const espera = m === 'pulsar' && Array.isArray(args[1]) ? args.splice(1)[0] : null;
+        if (typeof this[m] !== 'function') { log.push(`❌ ${m}: no existe`); break; }
+        const t0 = performance.now();
+        const r = await this[m](...args);
+        const ms = Math.round(performance.now() - t0);
+        const red = (r?.red || []).map((x) => x.replace(/ \d+ /, ' ').replace(/\/\d+(?=\/|$)/g, '/{}'));
+        const falta = espera?.filter((e) => !red.includes(e));
+        const mal = (r && r.error) || (Array.isArray(r) && r.length && r) || (typeof r === 'string' && /^(❌|sin |diálogo)/.test(r) && r)
+          || (falta?.length && `sin ${falta.join(', ')} en la red`);
+        log.push(`${mal ? '❌' : '✓'} ${m}(${args.map((a) => a instanceof RegExp ? String(a) : JSON.stringify(a)).join(', ').slice(0, 60)}) ${ms} ms${mal ? ': ' + JSON.stringify(mal).slice(0, 200) : ''}`);
+        if (mal) break;
+      }
+      return { log, ...this.estado() };
+    },
+  };
+  return "formularios listos: __f.estado() (pulsables numerados), __f.clic('Texto' o número), __f.esperar('Texto'), __f.ir('/ruta'), __f.pasos([[...]]), __f.abrir(), __f.obligatorios(), __f.llenar({...}), __f.pulsar('Guardar'), __f.verificar({...}), __f.fila(/re/, 'pencil'), __f.menu(/re/, 'Opción')";
+})()

webscope_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: webscope-mcp
+Version: 0.2.0
+Summary: MCP server (stdio, standard library only) that gives a coding agent short answers about a project
+License: MIT
+Project-URL: Repository, https://github.com/partprogramming09/webscope
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Webscope
+
+<!-- mcp-name: io.github.partprogramming09/webscope -->
+
+A small MCP server (stdio, JSON-RPC 2.0, Python standard library only) that gives a coding agent short answers about a
+project: grouped search hits, one symbol instead of a whole file, and the output of the project's own read-only scripts,
+trimmed to head and tail. The goal is fewer tokens per question.
+
+Tool names, parameters and messages are in Spanish.
+
+## Requirements
+
+- Python 3.9 or newer (no third-party packages)
+- Optional: [uv](https://docs.astral.sh/uv/), to run it with `uvx` without cloning
+- `grep` on `PATH` (used by `buscar`)
+
+## Installation
+
+1. In your project's root, create its manifest and list the folders and scripts it may use
+   (see [Configuration](#configuration-webscopejson) and [`webscope.example.json`](webscope.example.json)).
+
+2. Register the server. With Claude Code, from the project's root, pick one:
+
+   ```sh
+   # with uv, no clone needed (like npx)
+   claude mcp add --scope project webscope -- uvx --from git+https://github.com/partprogramming09/webscope webscope-mcp --manifest "$PWD/webscope.json"
+
+   # with a clone and plain Python
+   git clone https://github.com/partprogramming09/webscope.git ~/webscope
+   claude mcp add --scope project webscope -- python3 -I ~/webscope/webscope.py --manifest "$PWD/webscope.json"
+   ```
+
+   `--scope project` writes `.mcp.json` so the whole team gets it; use `--scope user` for all your projects. Add
+   `-e WEBSCOPE_ESCRITURA=1` before `--` only if a script declares `escribe` and you want to allow it.
+
+3. Start `claude` in the project, approve the server, and check it with `/mcp`: `webscope` should show as connected
+   with the tools `buscar`, `leer` and `correr`.
+
+Other MCP clients: add the same command to their configuration, for example a `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "webscope": {
+      "command": "python3",
+      "args": ["-I", "/path/to/webscope/webscope.py", "--manifest", "/path/to/your/project/webscope.json"]
+    }
+  }
+}
+```
+
+Instead of `--manifest` you can set the environment variable `WEBSCOPE_MANIFEST`. Without either, the server uses
+`./webscope.json` if it exists; otherwise it serves the current folder with `buscar` and `leer` and no scripts.
+
+### Docker
+
+```sh
+docker build -t webscope .
+docker run -i --rm -v "$PWD:/project:ro" -e WEBSCOPE_MANIFEST=/project/webscope.json webscope
+```
+
+Without `WEBSCOPE_MANIFEST` the image serves the bundled `webscope.example.json`.
+
+## Tools
+
+| Tool | What it does |
+| :--- | :--- |
+| `buscar(texto, donde?, tope?, formato?, contexto?, regex?)` | Case-insensitive search, literal unless `regex=true` (extended regex). Hits grouped by file, most-referenced files first, capped at `tope` lines. `donde` limits it to a folder or file; `contexto` (0-5) adds lines around each hit. `formato="conciso"` returns only the top 5 files with counts. |
+| `leer(archivo, simbolo?, lineas?, max_lineas?, cola?, contiene?, formato?)` | Returns only one function, method or class (PHP, TS, JS, Vue, Python) — or several, if `simbolo` is a list —, one Markdown section by heading, a line range (`lineas="120-180"`), or for `.log`/`.txt`/`.out` files the last `cola` lines and/or the lines containing `contiene`. Without `simbolo` or `lineas` it returns the file's index: headings or definitions with their line numbers. |
+| `correr(nombre?, args?, detalle?)` | Runs a script declared in the manifest and returns `exit N` plus trimmed output. Without `nombre` it lists the scripts; `detalle="esquema"` shows one script's usage. Read-only. |
+| `correr_escritura(nombre, args)` | Only listed when a script declares `escribe`. Runs a write argument; requires `WEBSCOPE_ESCRITURA=1` in the server environment and is marked `destructiveHint` and `anthropic/requiresUserInteraction`. |
+
+Every answer starts with one short line saying what it is and what to do next, and is capped at `tope_tokens`
+(about 4 characters per token).
+
+A malformed request, a non-UTF-8 script output or an unexpected error comes back as an error message; the server keeps
+running. `buscar` skips files that are not valid UTF-8 when the locale is UTF-8 (grep treats them as binary).
+
+## Security model
+
+- **Project root only.** `buscar` and `leer` resolve paths against the manifest's `root` and reject anything outside it.
+- **Secret files are invisible.** `buscar` and `leer` skip `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `id_rsa*`,
+  `id_ed25519*`, `auth.json` and `credentials*` (templates ending in `.example` stay visible).
+- **Fixed commands, no shell.** Scripts run as a fixed argument list from the manifest. Arguments that are absolute paths
+  or contain `..` are rejected (unless the script sets `acepta_barra`, which allows URL-like `/a/b` but still not `..`).
+  Flags listed in `rechaza` are rejected.
+- **Read-only by default.** `correr` refuses any argument listed in a script's `escribe`. Those go through
+  `correr_escritura`, which only exists when declared and only runs when the user sets `WEBSCOPE_ESCRITURA=1`.
+- **Minimal environment.** Scripts do not inherit the server's environment. They receive only `PATH`, `HOME`, `LANG`,
+  `LC_ALL`, `TMPDIR`, the variables named in the manifest's `env_permitidas`, plus `WEBSCOPE_RAIZ` (project root) and
+  `WEBSCOPE_MANIFIESTO` (manifest path).
+- **Bounded output.** Script output is trimmed to head and tail lines, and each response to `tope_tokens`.
+
+The scripts themselves are trusted code: Webscope limits how they are called, not what they do. Only list scripts you
+would run yourself.
+
+## Configuration (`webscope.json`)
+
+See [`webscope.example.json`](webscope.example.json).
+
+```json
+{
+  "root": ".",
+  "recorte": { "cabeza": 10, "cola": 70 },
+  "tope_tokens": 5000,
+  "buscar": { "dirs": ["src"], "extensiones": ["py", "ts"] },
+  "env_permitidas": ["DATABASE_URL"],
+  "scripts": {
+    "report": {
+      "cmd": ["python3", "-I", "scripts/report.py"],
+      "descripcion": "Summarises a table",
+      "uso": "<table>",
+      "rechaza": ["--out"],
+      "escribe": ["--fix"],
+      "timeout": 120
+    }
+  }
+}
+```
+
+| Key | Meaning |
+| :--- | :--- |
+| `root` | Project root, relative to the manifest's folder. |
+| `recorte` | Default head (`cabeza`) and tail (`cola`) lines kept from script output. |
+| `tope_tokens` | Maximum size of any response, in approximate tokens. |
+| `buscar.dirs`, `buscar.extensiones` | Folders and file extensions searched by default. |
+| `env_permitidas` | Extra environment variables passed to scripts. |
+| `scripts.<name>.cmd` | Fixed command as a list; `python3` is replaced by the server's interpreter. |
+| `descripcion`, `uso` | Shown by `correr()` listings. |
+| `rechaza` | Flags that would write files; always refused. |
+| `escribe` | Arguments that write data; only via `correr_escritura` with `WEBSCOPE_ESCRITURA=1`. |
+| `acepta_barra` | Allow arguments starting with `/` (URL paths). |
+| `timeout`, `cabeza`, `cola` | Per-script overrides. |
+
+## Included scripts
+
+The package ships ready-made scripts in `webscope_adaptadores/`. A manifest names them with `{adaptadores}` in `cmd`
+(see [`webscope.example.json`](webscope.example.json)); copy the entries you need and adjust the folders.
+
+| Script | What it answers | Stack |
+| :--- | :--- | :--- |
+| `vue_ts.py` (`mapa`) | Routes, views, API calls, composables and stores of a frontend module; `--recorrido` lists what can be clicked (actions with their `v-if` and permission, links, tabs with their API, form fields); `--cobertura` says which calls an e2e capture exercised | Vue 3 + TS |
+| `laravel.py` (`mapa_back`) | Endpoint, controller, service, model and table behind a frontend module or API path | Laravel |
+| `e2e_chrome.py` | JavaScript for **one** `javascript_tool` call of Claude in Chrome: walks routes and returns per route time, rows, failed requests, console errors and UI problems, without screenshots. `--llamar` reuses the walk already installed in the page; `--captura`/`--detalle` record what the page sends and receives; `--form` installs `__f` to fill a form by label, press Save and read it back, plus screen helpers that replace screenshots and coordinate clicks: `estado()` (the screen as short text), `clic(text)` (click by visible text, then wait until the page settles), `esperar`, `ir(route)` (router navigation without reload) and `pasos([...])` (several steps in one call). With a local receiver: `--servir [port folder]` starts it, `--cargar [port]` installs capture and `__f` from it, `--guardar <name> [port]` sends the whole capture to `<folder>/<name>.txt` (with one `ms <ms> <method> <status> <path>` line per API call; the receiver answers with the 5 slowest) and the steps `__f` recorded to `.claude/webscope/recorridos/<name>.json`, and `--repetir <name>` replays those steps in one call (with a fresh stamp on `ZZ_E2E` values) while the frontend does not change; `--exportar <capture> <url>` writes a Playwright test with the same steps | Any SPA with a router |
+| `payload_check.py` | Checks a capture against the FormRequest rules, the Resource and the table columns; flags keys without a rule, values outside `in:`, `''` sent to a nullable column | Laravel |
+| `limpiar_zz.py` | Lists, and with `--borrar` deletes after a backup, test rows whose code starts with `ZZ_` | Laravel |
+| `costo_sesion.py` | Cost of the latest (or a given) Claude Code session in the project: USD per model at list prices (subagents and advisor included), calls and re-read context per tool, large outputs, repeated calls, and which tool loops would have been cheaper in a subagent | Claude Code |
+| `uso_agentes.py` | Subagent usage: turns, context, models, agents over the turn limit | Claude Code |
+| `uso_webscope.py` | Share of file reads and searches that went through `leer` and `buscar` in sessions where Webscope was available, and the `Read`/`sed`/`grep` calls used instead | Claude Code |
+
+Project-specific settings go in the manifest's `proyecto` section:
+
+| Key | Used by | Meaning |
+| :--- | :--- | :--- |
+| `modulos` | `payload_check` | Backend modules folder (default `app/Modules`) |
+| `prefijo_rutas` | `e2e_chrome` | Prefix the app lives under, e.g. `/demo`, so routes work with or without it |
+| `contenedor` | `mapa_back` | Docker container where `php artisan route:list --json` runs; empty reads the route files |
+| `sql` | `payload_check`, `limpiar_zz` | Script that runs a read-only SQL query and prints TSV with a header |
+| `tinker` | `limpiar_zz` | Script that runs a PHP file against the database (`<script> <file.php> --commit`) |
+| `php_db` | `limpiar_zz` | PHP expression for the connection (default `DB::connection()`) |
+| `capturas` | MCP resources | Captures folder (the one given to `--servir`); its `.txt` files are listed as `webscope://capturas/<file>` next to the saved walks `webscope://recorridos/<file>` |
+
+The Vue index cache and `limpiar_zz` backups go to `~/.cache/webscope/`. The `e2e_chrome` receiver writes captures to the
+folder given to `--servir` (default `capturas`, relative to where it starts). `--servir` does not return: start it from a
+shell in the background (the example manifest lists it in `rechaza`, so `correr` refuses it).
+
+### Using the scripts from a subagent
+
+A subagent sees Webscope only if its definition lists the tools, for example in Claude Code's `.claude/agents/<name>.md`:
+
+```yaml
+tools: Read, Grep, Glob, Bash, mcp__webscope__buscar, mcp__webscope__leer, mcp__webscope__correr
+model: sonnet
+```
+
+Add `mcp__webscope__correr_escritura` only if the agent must run write arguments, plus the browser tools it needs.
+[`agents/recorrido.example.md`](agents/recorrido.example.md) is a ready-made agent that walks one frontend module in
+Chrome with `mapa`, `e2e_chrome` and `limpiar_zz` and returns a summary of at most 25 lines: copy it to
+`.claude/agents/recorrido.md` and replace `<webscope>` (the clone's folder; the receiver runs from the clone, not from
+`uvx`) and the captures folder.
+
+One measurement (a browser walk of one module, one project, one run per condition) found:
+
+- With the walk in the main session, Webscope did not change the cost (+7 % and −5 % in two runs). It changed accuracy:
+  the order of steps (`mapa --recorrido`), the fields that were not saved (`__f.verificar`) and the measured coverage.
+- The same walk in a sonnet subagent that returns a summary of at most 25 lines cost 1.05 USD instead of 6.40, with the
+  same coverage. About 2× came from isolating the context; the rest from the sonnet price.
+- Page reads and screenshots were about 80 % of the re-read context, so the agent reads state with `javascript_tool` and
+  takes screenshots only to understand an error.
+- Subagents that ran for more than about 40 turns grew their context like a main session. Give one module or one bounded
+  task per agent, and tell it to stop at about 40 tool calls and return what is done and what is pending.
+
+`costo_sesion.py --raiz <project>` and `uso_agentes.py --raiz <project>` measure the same in another project. The USD
+come from the price table at the top of `costo_sesion.py` (list prices, October 2026), which only lists models checked
+against the cost reported by `claude -p` (Opus 5.5, Sonnet 5.5, Fable 5.1: within 0.01 USD on three runs); any other
+model is shown as `sin precio` until it is added.
+
+## Hook: suggest Webscope
+
+Agents often keep using `Read`, `cat`, `sed -n` and `grep` even when Webscope is available. `hooks/sugerir_webscope.py`
+is a Claude Code `PostToolUse` hook that, after such a call, adds one line to the model's context with the equivalent
+Webscope call (for example `leer(archivo, lineas="120-180")`). It never blocks and speaks at most 3 times per session.
+Add it to the project's `.claude/settings.json` or `.claude/settings.local.json`:
+
+```json
+{"hooks": {"PostToolUse": [{"matcher": "Read|Bash", "hooks": [{"type": "command",
+  "command": "python3 -I /path/to/webscope/hooks/sugerir_webscope.py"}]}]}}
+```
+
+`uso_webscope.py` measures whether it works: the share of reads and searches that go through Webscope.
+
+## Browser UI check
+
+`webscope_adaptadores/web/chequeo-ui.js` is a standalone snippet for a browser automation tool (`page.evaluate` in Playwright, or a
+JavaScript tool in a browser extension). It returns only the problems on the current page: horizontal overflow, empty
+chips or badges, untranslated i18n keys, raw values (`undefined`, `NaN`…), overlapping text and unnamed buttons.
+
+```sh
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> node webscope_adaptadores/web/test_chequeo_ui.mjs
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> PW_CHANNEL=chrome node webscope_adaptadores/web/test_form.mjs
+```
+
+`PW_CHANNEL=chrome` uses the installed Chrome when Playwright's own browser is missing.
+
+## Tests
+
+```sh
+python3 -I test_webscope.py
+```
+
+## Out of scope
+
+Webscope does not replace a language server or a browser automation server, does not run code written by the agent, and
+is not a test framework.
+
+## License
+
+[MIT](LICENSE)

webscope_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+webscope.py,sha256=NkCblcsmVGPD_GjAvp3uwygbTDf41RQnGuEq6jqf_p4,40050
+webscope_adaptadores/__init__.py,sha256=dcymvVh5mx0vEXA9CK7JNlmqE8ffTLB1YPx1Rv4RP80,105
+webscope_adaptadores/costo_sesion.py,sha256=8E7R5sHZgqjbLcI4eCnaevwg7pyYQez0W-MVM7wPJP0,9667
+webscope_adaptadores/e2e_chrome.py,sha256=CkWzwwSWQHTWQNFhmvXBKRfvm4Q1owTdsgqiLpI_API,15522
+webscope_adaptadores/laravel.py,sha256=yrxEyq5k6YaokHCK_bLsSMkH8LZ6aCYjDNPlxaI54Tw,12034
+webscope_adaptadores/limpiar_zz.py,sha256=RceZdwRHd99mX2b8CUu_1qal8_XAHi2sDJYWVBL-dyc,8444
+webscope_adaptadores/payload_check.py,sha256=HgLRvjP3CIn1r5QM5_stI183YMHFCboJ3ys3DHsFb28,14346
+webscope_adaptadores/proyecto.py,sha256=9i0K0493DvQjafYREoD2H1AtzCZOYxZjj0AveAHX5lI,2782
+webscope_adaptadores/uso_agentes.py,sha256=TSREIoPu-BGF9GVN73Nzt-clh8wDuuM8mgcwXCjP-lk,3096
+webscope_adaptadores/uso_webscope.py,sha256=yoM3gGZtSYGa_O416g_t8TGJ5TIaNSExCPKKNiUY57U,4009
+webscope_adaptadores/vue_ts.py,sha256=21T7LJey0HyAAWZO8ZKNIDrhkW0dGqYBVa38f9Yqw9Q,11575
+webscope_adaptadores/web/chequeo-ui.js,sha256=NgZEywYZYa8laKcOcaY7p-3TyXhl7iv6P72-M8ZPN9k,2664
+webscope_adaptadores/web/e2e-rutas.js,sha256=G_ukkmukHXzDnKH-FI7ZnvHphMpItCSLUQ-ofkMFsyE,6669
+webscope_adaptadores/web/form.js,sha256=3xUmVgECLbo2X0LK-HkjZzOSCUFre3-MWZFoQVlIO00,22688
+webscope_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=x0GFTawl3jC5g4RFDzTMMbpvKaf4-wezJjXHuSSmKp8,1074
+webscope_mcp-0.2.0.dist-info/METADATA,sha256=SnMQTqiPGi49ZGBZ68TDTqya9HO8SIdhAxwh3aohMEg,15339
+webscope_mcp-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+webscope_mcp-0.2.0.dist-info/entry_points.txt,sha256=-F-tg_FEBd3xWopfdBKymlmHl-hoBzaYYwSgSiif0mY,47
+webscope_mcp-0.2.0.dist-info/top_level.txt,sha256=Awg4e86U58NouqwsP1cMtKmyi0rNVEdZZEN4Ka8Sico,30
+webscope_mcp-0.2.0.dist-info/RECORD,,

webscope_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

webscope_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+webscope-mcp = webscope:main

webscope_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 partprogramming09
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

webscope_mcp-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+webscope
+webscope_adaptadores