changebook 0.5.0 → 0.7.0

package/dist/scan.js

@@ -0,0 +1,427 @@
+import path from 'node:path';
+import { execFileAsync, FICHEROS_GENERADOS, GIT_MAX_BUFFER_BYTES } from './git.js';
+// ── `changebook scan` · ver el valor antes de tener cuenta (B2) ──────────────
+//
+// LECTURA PURA. No escribe nada, no pide cuenta, no toca la red, no llama a
+// ningún modelo. Todo lo que dice sale de `git log` del repo que tienes delante.
+// Es lo que permite que sea gratis e ilimitado, y lo que permite correrlo sobre
+// el repo de otro sin pedirle permiso a nadie.
+//
+// ── LO QUE ESTE FICHERO NO MIDE, Y POR QUÉ ──────────────────────────────────
+//
+// La ficha de B2 pedía como titular «los 5 ficheros que más han participado en
+// revertidos y hotfixes». Medido sobre este mismo repo antes de escribir una
+// línea: **492 commits y UN revert**. Y de los dos que casan por mensaje, uno es
+// un falso positivo — `932f395` («Avisar cuando tu rama va a revertir el trabajo
+// de otro») es una funcionalidad SOBRE reverts, no un revert.
+//
+// No es que el repo sea pequeño (la ficha ya preveía ese caso): es que **no
+// emite esa señal**. Hace squash-merge desde ramas y escribe los arreglos hacia
+// delante, con mensajes narrativos («El corte de PostgREST deja de mentir»).
+// Muchos repos sí la emiten —`fix:`, `hotfix`, `Revert "…"` es convención común—
+// así que el detector se queda, pero **el informe no la pone de titular cuando
+// no está**: dice cuántas encontró, incluido cero. Un informe que promete un
+// ranking y enseña una lista vacía es peor que uno que dice «aquí no hay».
+//
+// LA TENTACIÓN QUE SE DESCARTÓ. El sustituto obvio es «fichero re-tocado en
+// menos de 24 h» — y este repo tiene 229 así, el primero con 76. Es abundante y
+// es inútil: en un repo con 492 commits en 27 días eso mide ACTIVIDAD, no daño.
+// El primero de la lista es `i18n.ts`, el fichero de traducciones, que se toca
+// siempre y no es frágil. Es el mismo error que el plan ya se reprochó en su
+// línea 928 —«Rotación ≠ daño, y ordené el plan confundiéndolas»— y el mismo que
+// infla el contador de reincidencia. Se calcula y se enseña, pero **etiquetado
+// como lo que es**, nunca como fragilidad.
+//
+// Lo que sí se afirma sin asterisco es el ACOPLAMIENTO: qué ficheros cambian
+// juntos y cuánto arrastra cada uno. Eso no depende de convenciones de mensaje,
+// sale entero de qué ficheros aparecen en el mismo commit, y es exactamente la
+// pregunta que el producto contesta.
+/** Techo de commits leídos. Por encima el informe no mejora y el tiempo sí sube. */
+export const MAX_COMMITS = 1500;
+/**
+ * Un commit que toca 300 ficheros (un `npm install`, un formateo masivo) genera
+ * 44.850 parejas él solo y ahoga la señal real. Por encima de este techo el
+ * commit cuenta para frecuencia pero NO para acoplamiento: no dice nada sobre
+ * qué va con qué.
+ */
+export const MAX_FICHEROS_POR_COMMIT_PARA_PAREJAS = 25;
+/** Ventana del retoque rápido. */
+const VENTANA_RETOQUE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Por debajo de esto el informe enseña hechos y se calla los porcentajes.
+ * No es un umbral de «sirvo / no sirvo»: es dónde deja de haber muestra para
+ * que un porcentaje signifique algo.
+ */
+export const REPO_JOVEN = 50;
+// Ruido que no es código de nadie: no debe salir en ningún ranking.
+//
+// OJO CON LA MAGIA `:(glob)`, QUE NO ES DECORACIÓN. Sin ella, un patrón que
+// empieza por doble-asterisco-barra exige AL MENOS un directorio, así que
+// excluye `sub/package-lock.json` y DEJA PASAR el de la raíz. Es exactamente lo
+// que hacía la primera versión de esto: medido sobre este repo,
+// `package-lock.json` y `deno.lock` estaban en los datos mientras el comentario
+// de aquí arriba decía que no. Un filtro que no filtra y no lo dice.
+//
+// Las tres formas, comprobadas contra git y no deducidas:
+//   :(exclude) + doble-asterisco/x     → excluye el anidado, deja el de la raíz
+//   :(exclude)x                        → excluye el de la raíz, deja el anidado
+//   :(glob,exclude) + doble-asterisco/x → excluye los dos  ← esta
+//
+// `FICHEROS_GENERADOS` (de git.ts) resuelve lo mismo listando las dos formas.
+// Se importa tal cual: funciona, y no es de este fichero cambiarlo.
+//
+// (Y este bloque va con `//` y no con `/* */` porque un patrón así dentro de un
+// comentario de bloque lo CIERRA. Me pasó al escribirlo.)
+const RUIDO = [
+    ':(glob,exclude)**/package-lock.json',
+    ':(glob,exclude)**/*.lock',
+    ':(glob,exclude)**/dist/**',
+    ':(glob,exclude)**/out/**',
+    ...FICHEROS_GENERADOS,
+];
+/** Mensajes que en la convención de la industria significan «esto iba mal». */
+const PATRON_REVERT = /^revert[:\s"]|^revierte\b|\bhotfix\b/i;
+/**
+ * Lee el historial UNA vez. `-z` y `--name-only` con separador nulo porque un
+ * nombre de fichero puede llevar espacios, y `--no-merges` porque un merge
+ * repite ficheros que ya contaron en sus commits.
+ */
+export async function leerHistorial(dir, max = MAX_COMMITS) {
+    const { stdout } = await execFileAsync('git', [
+        'log',
+        `-${max}`,
+        '--no-merges',
+        '--name-only',
+        '--date=unix',
+        '--format=%x00C%x00%H%x00%ad%x00%s',
+        '--',
+        '.',
+        ...RUIDO,
+    ], { cwd: dir, maxBuffer: GIT_MAX_BUFFER_BYTES });
+    const commits = [];
+    let actual = null;
+    const trozos = stdout.split('\0');
+    for (let i = 0; i < trozos.length; i++) {
+        if (trozos[i] === 'C') {
+            if (actual)
+                commits.push(actual);
+            actual = {
+                hash: trozos[i + 1] ?? '',
+                fecha: Number(trozos[i + 2] ?? 0) * 1000,
+                asunto: (trozos[i + 3] ?? '').split('\n')[0] ?? '',
+                ficheros: [],
+            };
+            // El asunto viene pegado al primer fichero por el salto de línea.
+            const resto = (trozos[i + 3] ?? '').split('\n').slice(1).filter(Boolean);
+            actual.ficheros.push(...resto);
+            i += 3;
+            continue;
+        }
+        const lineas = trozos[i].split('\n').filter(Boolean);
+        if (actual)
+            actual.ficheros.push(...lineas);
+    }
+    if (actual)
+        commits.push(actual);
+    return commits;
+}
+/**
+ * Cuántos commits tiene el repo, sin filtrar nada. Es el número que necesita la
+ * estimación de coste de `init`, y NO es el de `leerHistorial`: ese excluye
+ * ruido y topa en MAX_COMMITS, así que usarlo daría una cifra más baja que la
+ * que se va a gastar. Devuelve 0 si no hay repo o no hay commits.
+ */
+export async function contarCommits(dir) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], {
+            cwd: dir,
+        });
+        const n = Number(stdout.trim());
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Todo el cálculo, sin tocar disco ni red: entra historial, sale informe. */
+export function analizar(proyecto, commits) {
+    const cambios = new Map();
+    const juntas = new Map();
+    const vecinos = new Map();
+    const ultimoToque = new Map();
+    const retoque = new Map();
+    const reverts = [];
+    for (const c of commits) {
+        if (PATRON_REVERT.test(c.asunto)) {
+            reverts.push({ hash: c.hash.slice(0, 7), asunto: c.asunto });
+        }
+        const unicos = [...new Set(c.ficheros)];
+        for (const f of unicos) {
+            cambios.set(f, (cambios.get(f) ?? 0) + 1);
+            const previo = ultimoToque.get(f);
+            // El log viene de nuevo a viejo: el «previo» que ya vimos es POSTERIOR.
+            if (previo !== undefined && previo - c.fecha < VENTANA_RETOQUE_MS) {
+                retoque.set(f, (retoque.get(f) ?? 0) + 1);
+            }
+            ultimoToque.set(f, c.fecha);
+        }
+        if (unicos.length > MAX_FICHEROS_POR_COMMIT_PARA_PAREJAS)
+            continue;
+        for (let i = 0; i < unicos.length; i++) {
+            for (let j = i + 1; j < unicos.length; j++) {
+                const [a, b] = unicos[i] < unicos[j] ? [unicos[i], unicos[j]] : [unicos[j], unicos[i]];
+                juntas.set(`${a}\0${b}`, (juntas.get(`${a}\0${b}`) ?? 0) + 1);
+                if (!vecinos.has(a))
+                    vecinos.set(a, new Set());
+                if (!vecinos.has(b))
+                    vecinos.set(b, new Set());
+                vecinos.get(a).add(b);
+                vecinos.get(b).add(a);
+            }
+        }
+    }
+    const porCambios = [...cambios].sort((x, y) => y[1] - x[1]);
+    const totalCambios = porCambios.reduce((s, [, n]) => s + n, 0);
+    // Concentración: cuántos ficheros acumulan la mitad de todos los cambios.
+    let acumulado = 0;
+    let ficherosMitad = 0;
+    for (const [, n] of porCambios) {
+        acumulado += n;
+        ficherosMitad++;
+        if (acumulado * 2 >= totalCambios)
+            break;
+    }
+    const parejas = [...juntas]
+        .map(([k, n]) => {
+        const [a, b] = k.split('\0');
+        const menor = Math.min(cambios.get(a) ?? 1, cambios.get(b) ?? 1);
+        return { a, b, juntas: n, tasa: menor ? n / menor : 0 };
+    })
+        // Dos ficheros que coincidieron una vez no son una pareja, son una casualidad.
+        .filter((p) => p.juntas >= 3)
+        .sort((x, y) => y.tasa - x.tasa || y.juntas - x.juntas);
+    return {
+        proyecto,
+        commits: commits.length,
+        desde: commits.length ? new Date(commits[commits.length - 1].fecha).toISOString().slice(0, 10) : null,
+        hasta: commits.length ? new Date(commits[0].fecha).toISOString().slice(0, 10) : null,
+        ficherosVivos: cambios.size,
+        concentracion: {
+            ficheros: ficherosMitad,
+            porcentaje: cambios.size ? Math.round((ficherosMitad / cambios.size) * 100) : 0,
+        },
+        masCambiados: porCambios.slice(0, 5).map(([fichero, n]) => ({
+            fichero,
+            cambios: n,
+            arrastra: vecinos.get(fichero)?.size ?? 0,
+        })),
+        parejas: parejas.slice(0, 5),
+        retoqueRapido: [...retoque]
+            .sort((x, y) => y[1] - x[1])
+            .slice(0, 5)
+            .map(([fichero, veces]) => ({ fichero, veces })),
+        reverts,
+    };
+}
+const corto = (f, ancho = 46) => f.length <= ancho ? f : `…${f.slice(-(ancho - 1))}`;
+export function informeDeScan(i) {
+    const l = [`ChangeBook · informe de acoplamiento de ${i.proyecto}`, ''];
+    if (i.commits === 0) {
+        l.push('  Este repositorio todavía no tiene historial que leer.');
+        return l.join('\n');
+    }
+    l.push(`  ${i.commits} commits · ${i.ficherosVivos} ficheros · ${i.desde} → ${i.hasta}`, '');
+    // ── Repo joven ────────────────────────────────────────────────────────────
+    //
+    // La ficha de B2 lo pide explícito, y con una instrucción que es la parte
+    // importante: «la respuesta correcta no es "aún no hay datos", es "esto es lo
+    // que ChangeBook está vigilando ya"». Un producto que se presenta diciendo que
+    // no puede decir nada se cierra y no se vuelve a abrir.
+    //
+    // Lo que cambia por debajo NO es el tono, es qué se afirma. El porcentaje de
+    // concentración sobre 12 commits es ruido con pinta de estadística — el mismo
+    // pecado que el contador de reincidencia, un tamaño de muestra más abajo. Así
+    // que con poco historial se enseñan los HECHOS (qué ficheros, qué parejas) y
+    // se calla el PORCENTAJE, en vez de adornarlo con un asterisco que nadie lee.
+    if (i.commits < REPO_JOVEN) {
+        l.push(`  Historial corto todavía (${i.commits} commits), así que aquí no hay`, `  porcentajes: con esta muestra serían ruido con pinta de dato.`, '', '  Esto es lo que ChangeBook ya está viendo, y lo que va a vigilar según crezca:');
+    }
+    else {
+        l.push(`  El ${i.concentracion.porcentaje}% de tus ficheros concentra la mitad de todos los cambios ` +
+            `(${i.concentracion.ficheros} de ${i.ficherosVivos}).`, '', '  Los ficheros que más arrastran cuando los tocas:');
+    }
+    for (const [n, f] of i.masCambiados.entries()) {
+        l.push(`    ${n + 1}. ${corto(f.fichero).padEnd(47)} ${String(f.cambios).padStart(3)} cambios · arrastra ${f.arrastra}`);
+    }
+    if (i.parejas.length) {
+        l.push('', '  Cambian juntos casi siempre — si tocas uno, mira el otro:');
+        for (const p of i.parejas) {
+            l.push(`    ${Math.round(p.tasa * 100)}%  ${corto(p.a, 34)}  ↔  ${corto(p.b, 34)}`);
+        }
+    }
+    // Se dice SIEMPRE, incluido el cero. Un ranking vacío se lee como «no medí»;
+    // un cero explícito se lee como «medí y no hay», que es información.
+    l.push('', i.reverts.length
+        ? `  ${i.reverts.length} revertidos o hotfix por patrón de mensaje:`
+        : i.commits < REPO_JOVEN
+            ? // Con 12 commits, «este repo arregla hacia delante» sería inventarse
+                // un rasgo de cultura a partir de nada. Cero es cero, y ya está.
+                '  Revertidos o hotfix por patrón de mensaje: ninguno todavía.'
+            : '  Revertidos o hotfix por patrón de mensaje: ninguno. Este repo arregla ' +
+                'hacia delante,\n  así que esa señal aquí no dice nada — el acoplamiento de arriba sí.');
+    for (const r of i.reverts.slice(0, 3))
+        l.push(`    ${r.hash}  ${r.asunto}`);
+    if (i.retoqueRapido.length) {
+        l.push('', '  Re-tocados en menos de 24 h (esto es ACTIVIDAD, no fragilidad:', '  un fichero vivo se re-toca mucho sin estar roto):');
+        for (const r of i.retoqueRapido.slice(0, 3)) {
+            l.push(`    ${corto(r.fichero).padEnd(47)} ${String(r.veces).padStart(3)}×`);
+        }
+    }
+    l.push('', '  ¿Quieres que tu agente sepa esto antes de editar?  npx changebook init');
+    return l.join('\n');
+}
+/**
+ * Versión del formato JSON. B4 (la tarjeta y el badge) va a consumir esta
+ * salida, y va a vivir en otro repo y en otra cadencia de despliegue: sin un
+ * número que mirar, el día que aquí se renombre un campo B4 se rompe leyendo
+ * `undefined` — en silencio, que es la peor forma. Súbelo al quitar o renombrar
+ * un campo; añadir uno nuevo no lo mueve.
+ */
+export const FORMATO_JSON = 1;
+/**
+ * Los argumentos de `scan`, separados de `process.argv` para poder probarlos.
+ *
+ * POR QUÉ ES UNA FUNCIÓN Y NO DOS LÍNEAS EN EL `switch`. La primera versión de
+ * esto vivía en index.ts y el test lo comprobaba lanzando el binario
+ * CONSTRUIDO. Pasaba en mi máquina —tenía `dist/` hecho— y en CI reventó con
+ * «Cannot find module .../dist/index.js», porque la puerta hace `npm ci` pero
+ * no `npm run build`. Un test verde solo donde lo escribí.
+ *
+ * El arreglo no es construir el CLI en la puerta (la engorda para todos) ni
+ * saltarse el test cuando falta `dist/` (eso es el verde por vacío). El fallo
+ * que hay que vigilar —que `--json` a secas se tome por directorio— es lógica
+ * pura, así que se saca aquí y se prueba directamente.
+ */
+export function argumentosDeScan(argv) {
+    return {
+        // El directorio es el primer argumento que NO sea una bandera.
+        dir: argv.find((a) => !a.startsWith('--')) ?? process.cwd(),
+        json: argv.includes('--json'),
+        card: argv.includes('--card'),
+        // `--badge` es la ÚNICA bandera de `scan` que necesita cuenta y red: publica
+        // los números para la imagen del README. El cálculo sigue siendo el mismo y
+        // sigue viviendo aquí; lo que toca la red está en `badge.ts`, para que la
+        // promesa de este módulo —sin credenciales, sin red, sin escribir— siga
+        // siendo cierta para las otras tres formas de llamarlo.
+        badge: argv.includes('--badge'),
+        // Apagar es tan barato como encender, y va en el mismo comando a propósito:
+        // un interruptor que se enciende desde la terminal y se apaga solo desde la
+        // web es un interruptor que la gente no se atreve a tocar.
+        off: argv.includes('--off'),
+    };
+}
+/** XML no perdona: una ruta con `&` o `<` rompe el SVG entero, en silencio. */
+const escapar = (s) => s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+// ── La tarjeta (B4) ─────────────────────────────────────────────────────────
+//
+// «El scan produce algo que se puede tuitear.» Sale por STDOUT como el `--json`,
+// no a un fichero: `scan` promete no escribir nada en el repo que analiza y hay
+// un test que lo comprueba, así que la tarjeta se redirige
+// (`changebook scan --card > tarjeta.svg`). De paso es más Unix.
+//
+// AUTOCONTENIDA A PROPÓSITO: sin fuentes remotas, sin imágenes enlazadas, sin
+// CSS externo. Una tarjeta que se comparte y se ve rota en la máquina de otro no
+// sirve de nada, y cualquier recurso remoto es además un rastreador que nadie
+// pidió.
+//
+// Y EL SUJETO ES EL MÓDULO, NUNCA EL AUTOR (invariante 6: «es lo que convirtió a
+// Code Climate Velocity en herramienta de vigilancia percibida»). Aquí se cumple
+// por construcción y no por disciplina: `leerHistorial` no lee el autor de los
+// commits, así que no hay nombre que enseñar aunque alguien quisiera.
+//
+// TAMPOCO DICE «FRAGILIDAD», que es lo que pedía la ficha. Llamar frágil a lo
+// que se toca mucho es el error del contador de reincidencia con otra ropa, y
+// aquí sería público. Dice acoplamiento, que es lo que se mide.
+export function tarjetaSVG(i) {
+    const parejas = i.parejas.slice(0, 3);
+    const corta = (f, n = 30) => escapar(f.length <= n ? f : `…${f.slice(-(n - 1))}`);
+    // GEOMETRÍA MEDIDA, no estimada. La primera versión usaba 62 px de paso para
+    // filas de DOS líneas: el segundo fichero de una fila quedaba a 36 px del
+    // porcentaje de la siguiente y el bloque se leía apelotonado. Y el contenido
+    // acababa sobre los 460 de un lienzo de 630, con media tarjeta vacía debajo.
+    // 84 de paso y arranque en 372 reparten el alto entero.
+    const PASO = 78;
+    const filas = parejas
+        .map((p, n) => {
+        const y = 372 + n * PASO;
+        return `  <text x="80" y="${y}" class="pct">${Math.round(p.tasa * 100)}%</text>
+  <text x="200" y="${y}" class="par ink">${corta(p.a)}</text>
+  <text x="200" y="${y + 30}" class="par dim">${corta(p.b)}</text>`;
+    })
+        .join('\n');
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-label="Informe de acoplamiento de ${escapar(i.proyecto)}">
+  <style>
+    .bg{fill:#131211}.ink{fill:#e7e4df}.dim{fill:#9a938a}.accent{fill:#e8896f}
+    text{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,Roboto,Helvetica,Arial,sans-serif}
+    .t{font-size:44px;font-weight:600}.sub{font-size:22px}
+    .pct{font-size:34px;font-weight:600;fill:#e8896f}
+    .par{font-size:23px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+    .hd{font-size:19px;letter-spacing:.09em}.mark{font-size:19px}
+  </style>
+  <rect class="bg" width="1200" height="630"/>
+  <rect class="accent" x="0" y="0" width="1200" height="6"/>
+  <text class="t ink" x="80" y="132">${escapar(i.proyecto)}</text>
+  <text class="sub dim" x="80" y="180">${i.commits} commits · ${i.ficherosVivos} ficheros · ${escapar(String(i.desde))} → ${escapar(String(i.hasta))}</text>
+  <text class="sub ink" x="80" y="246">El ${i.concentracion.porcentaje}% de sus ficheros concentra la mitad de los cambios.</text>
+  <line x1="80" y1="292" x2="1120" y2="292" stroke="#2e2b27" stroke-width="1"/>
+  <text class="hd dim" x="80" y="322">CAMBIAN JUNTOS — SI TOCAS UNO, MIRA EL OTRO</text>
+${filas}
+  <text class="mark dim" x="80" y="600">Generado con ChangeBook · changebook.app</text>
+</svg>
+`;
+}
+/**
+ * El informe para el final de `init` (B8): «instalar es descubrir, no esperar».
+ *
+ * FALLA ABIERTO A PROPÓSITO. `init` se corre en directorios que pueden no ser un
+ * repo de git, o serlo y estar vacíos, y su trabajo de verdad —registrar el MCP,
+ * los hooks, el sync— ya está hecho cuando esto se ejecuta. Reventar aquí
+ * convertiría una instalación correcta en una que parece fallida. Devuelve
+ * `null` y `init` sigue: exactamente la misma regla que el hook de impacto.
+ */
+export async function informeParaInit(dir) {
+    try {
+        const commits = await leerHistorial(dir);
+        if (commits.length === 0)
+            return null;
+        return informeDeScan(analizar(path.basename(path.resolve(dir)), commits));
+    }
+    catch {
+        return null;
+    }
+}
+/** Punto de entrada del comando. Lectura pura: no escribe, no llama a la red. */
+/**
+ * El informe en crudo, para quien necesita los NÚMEROS y no el texto.
+ *
+ * Lo usa `--badge`, que publica cifras: pedirle a `correrScan` una cadena y
+ * volver a parsearla sería inventar un formato intermedio entre dos funciones
+ * del mismo fichero.
+ */
+export async function informeDeRepo(dir) {
+    const commits = await leerHistorial(dir);
+    return analizar(path.basename(path.resolve(dir)), commits);
+}
+export async function correrScan(dir, opciones = {}) {
+    const informe = await informeDeRepo(dir);
+    if (opciones.card)
+        return tarjetaSVG(informe);
+    return opciones.json
+        ? JSON.stringify({ formato: FORMATO_JSON, ...informe }, null, 2)
+        : informeDeScan(informe);
+}
+//# sourceMappingURL=scan.js.map

package/dist/supabase.js

@@ -183,6 +183,45 @@ export class Supabase {
      * POST one row via PostgREST as the signed-in user (RLS applies). Used for
      * best-effort metering inserts — callers typically fire-and-forget it.
      */
+    /**
+     * La base del despliegue, para construir URLs públicas (el badge). Solo
+     * lectura: `url` sigue siendo privada porque nadie de fuera tiene por qué
+     * poder reapuntar el cliente a otro sitio a mitad de camino.
+     */
+    get baseUrl() {
+        return this.url;
+    }
+    /**
+     * INSERT que actualiza si ya existe. `onConflict` es la columna única sobre la
+     * que se decide: sin ella PostgREST no sabe qué fila estaba pisando y
+     * devuelve un 23505 que se lee como "algo falló" cuando en realidad es
+     * "vuelve a publicar tus números", que es el caso normal.
+     */
+    async upsertRow(table, row, onConflict) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        const enviar = () => fetch(`${this.url}/rest/v1/${table}?on_conflict=${encodeURIComponent(onConflict)}`, {
+            method: 'POST',
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+                Prefer: 'resolution=merge-duplicates,return=minimal',
+            },
+            body: JSON.stringify(row),
+            signal: AbortSignal.timeout(10_000),
+        });
+        let res = await enviar();
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await enviar();
+        }
+        if (!res.ok) {
+            throw new SupabaseError(`Upsert into ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
+        }
+    }
     async insertRow(table, row) {
         if (!this.hasCredentials())
             throw new SupabaseError(AUTH_HELP, 401);
@@ -197,6 +236,44 @@ export class Supabase {
             throw new SupabaseError(`Insert into ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
         }
     }
+    /**
+     * PATCH a PostgREST path as the signed-in user. `pathWithQuery` HAS to carry
+     * the filter (`regression_alerts?id=eq.<uuid>`): PostgREST rejects an
+     * unfiltered PATCH, and that rejection is the only thing standing between a
+     * typo and rewriting the whole table.
+     *
+     * The column grants still apply — `regression_alerts` only allows
+     * `resolved_at, resolution, resolution_by` to `authenticated`, on purpose, so
+     * a client cannot rewrite `module` or `project_id` and move an alert into
+     * someone else's project.
+     */
+    async patchRows(table, filter, patch) {
+        if (!this.hasCredentials())
+            throw new SupabaseError(AUTH_HELP, 401);
+        if (!this.accessToken)
+            await this.refresh();
+        let res = await this.patchOnce(table, filter, patch);
+        if (res.status === 401 && this.refreshToken) {
+            await this.refresh();
+            res = await this.patchOnce(table, filter, patch);
+        }
+        if (!res.ok) {
+            throw new SupabaseError(`Patch on ${table} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
+        }
+    }
+    patchOnce(table, filter, patch) {
+        return fetch(`${this.url}/rest/v1/${table}?${filter}`, {
+            method: 'PATCH',
+            headers: {
+                apikey: this.anonKey,
+                Authorization: `Bearer ${this.accessToken}`,
+                'Content-Type': 'application/json',
+                Prefer: 'return=minimal',
+            },
+            body: JSON.stringify(patch),
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
     /** POST /rest/v1/rpc/<fn> as the signed-in user (definer rules apply). */
     async callRpc(fn, args) {
         if (!this.hasCredentials())
@@ -211,7 +288,13 @@ export class Supabase {
         if (!res.ok) {
             throw new SupabaseError(`RPC ${fn} failed (${res.status}): ${(await res.text()).slice(0, 200)}`, res.status);
         }
-        return (await res.json());
+        // Una RPC que devuelve `void` contesta 204 con el cuerpo VACÍO, y
+        // `res.json()` explota ahí con «Unexpected end of JSON input» — un error que
+        // no dice nada del problema real y que aparece DESPUÉS de que la escritura
+        // ya haya ocurrido, o sea que el usuario ve un fallo de algo que sí se hizo.
+        // Medido llamando a `badge_publicar`.
+        const texto = await res.text();
+        return (texto ? JSON.parse(texto) : null);
     }
     rpcOnce(fn, args) {
         return fetch(`${this.url}/rest/v1/rpc/${fn}`, {