changebook 0.7.1 → 0.9.0

package/dist/audit.js

@@ -0,0 +1,226 @@
+/**
+ * `changebook audit` — la pieza `[5]`: auditoría ESTÁTICA del setup.
+ *
+ * QUÉ LA DISTINGUE DE UNA LISTA DE BUENAS PRÁCTICAS. Cada comprobación de aquí
+ * se escribió DESPUÉS de encontrar algo real en un setup real (este repo, el
+ * 24/08), no antes. Una lista de comprobaciones inventadas produce avisos que
+ * nadie ha visto fallar nunca, y eso entrena a ignorar la herramienta.
+ *
+ * SIN RED Y SIN CREDENCIALES, como `silence` y `scan`: todo lo que dice sale de
+ * ficheros del repo. Así contesta el mismo día en que alguien lo instala, antes
+ * de tener cuenta, y no puede quedarse callada por un fallo de red — que es la
+ * forma en que una auditoría miente.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Los ficheros de contexto que un agente lee al abrir, por convención. */
+export const FICHEROS_DE_CONTEXTO = ['CLAUDE.md', 'AGENTS.md'];
+const INICIO = '<!-- changebook:start -->';
+const FIN = '<!-- changebook:end -->';
+/**
+ * Las rutas citadas entre backticks que parecen ficheros.
+ *
+ * Se exige extensión conocida a propósito: sin ella, cualquier `foo.bar` de la
+ * prosa entraría como ruta y la auditoría publicaría falsos positivos — que en
+ * una herramienta que se corre a mano es peor que no publicar nada.
+ */
+export function rutasCitadas(texto) {
+    const re = /`([A-Za-z0-9_./-]+\.(?:ts|tsx|js|mjs|cjs|sql|yml|yaml|json|sh))`/g;
+    return [...new Set([...texto.matchAll(re)].map((m) => m[1]))];
+}
+/** El bloque auto-generado, si lo hay. */
+export function partirContexto(texto) {
+    const i = texto.indexOf(INICIO);
+    const j = texto.indexOf(FIN);
+    if (i === -1 || j === -1 || j < i)
+        return { auto: '', aMano: texto };
+    const auto = texto.slice(i, j + FIN.length);
+    return { auto, aMano: texto.replace(auto, '') };
+}
+/**
+ * ¿Existe? Y si no, ¿hay algo que se le parezca?
+ *
+ * El «quizá quisiste decir» no es adorno: los dos casos reales que encontró
+ * esto el 24/08 —`test/aliasEnLasToolsDelCli.ts` y `test/sinRayasEnLaWeb.ts`—
+ * eran el mismo fichero con `.test.ts`. Un aviso que sólo dice «no existe»
+ * manda a buscar; uno que dice el nombre bueno se arregla en diez segundos.
+ */
+export function resolverCita(raiz, cita) {
+    if (fs.existsSync(path.join(raiz, cita)))
+        return { existe: true };
+    // UN NOMBRE A SECAS NO ES UNA RUTA ROTA. La primera versión avisaba de
+    // `publish-extension.yml` —que existe, en `.github/workflows/`— porque se
+    // cita por su nombre. Ese falso positivo enseña a ignorar los avisos buenos,
+    // que era justo el riesgo escrito en la cabecera de este fichero. Cazado el
+    // 24/08 corriendo la auditoría contra su propio repo.
+    if (!cita.includes('/')) {
+        return { existe: buscarPorNombre(raiz, cita) };
+    }
+    const dir = path.join(raiz, path.dirname(cita));
+    const base = path.basename(cita, path.extname(cita));
+    let vecinos;
+    try {
+        vecinos = fs.readdirSync(dir);
+    }
+    catch {
+        return { existe: false };
+    }
+    const parecido = vecinos.find((v) => v.startsWith(`${base}.`) && v !== path.basename(cita));
+    return parecido
+        ? { existe: false, parecido: path.join(path.dirname(cita), parecido) }
+        : { existe: false };
+}
+/**
+ * ¿Existe algún fichero con ese nombre, en cualquier parte del repo?
+ *
+ * Con tope de profundidad y saltándose lo que no se versiona: sin eso, un
+ * `node_modules` convierte una orden instantánea en una que se piensa.
+ */
+function buscarPorNombre(raiz, nombre, profundidad = 6) {
+    const saltar = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+    const pila = [[raiz, 0]];
+    while (pila.length > 0) {
+        const [dir, nivel] = pila.pop();
+        let entradas;
+        try {
+            entradas = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entradas) {
+            if (e.isFile() && e.name === nombre)
+                return true;
+            if (e.isDirectory() && !saltar.has(e.name) && nivel < profundidad) {
+                pila.push([path.join(dir, e.name), nivel + 1]);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Citas rotas en los ficheros de contexto.
+ *
+ * DE DÓNDE SALE: 2 de 9 rutas citadas en el `CLAUDE.md` de este repo no
+ * existían. Una regla que apunta a código que no está es peor que no tener la
+ * regla — le enseña al agente a desconfiar del documento entero, incluidas las
+ * partes que sí valen.
+ */
+export function citasRotas(raiz) {
+    const out = [];
+    for (const nombre of FICHEROS_DE_CONTEXTO) {
+        let texto;
+        try {
+            texto = fs.readFileSync(path.join(raiz, nombre), 'utf8');
+        }
+        catch {
+            continue; // No tenerlo no es un fallo: no todos los repos los tienen.
+        }
+        // Sólo lo escrito A MANO: el bloque auto-generado se regenera solo y sus
+        // rutas salen de la base de datos, no de la prosa de nadie.
+        const { aMano } = partirContexto(texto);
+        const rotas = rutasCitadas(aMano)
+            .map((c) => ({ cita: c, ...resolverCita(raiz, c) }))
+            .filter((c) => !c.existe);
+        if (rotas.length === 0)
+            continue;
+        out.push({
+            nivel: 'aviso',
+            titulo: `${nombre}: ${rotas.length} cita(s) apuntan a ficheros que no existen`,
+            detalle: rotas.map((r) => r.parecido ? `${r.cita} → ¿quisiste decir ${r.parecido}?` : r.cita),
+        });
+    }
+    return out;
+}
+/**
+ * El peso de contexto que se paga en CADA sesión.
+ *
+ * DE DÓNDE SALE, medido el 24/08 en este repo: el bloque auto-generado se
+ * raciona a 2.000 chars —hay una PR entera dedicada a que sea honesto cuando
+ * recorta— y al lado había **12.407 chars escritos a mano, seis veces más**,
+ * sin tope y sin que nadie los midiera. No se juzga si sobran: se ponen delante.
+ */
+export function pesoDeContexto(raiz, topeAuto = 2000) {
+    const out = [];
+    for (const nombre of FICHEROS_DE_CONTEXTO) {
+        let texto;
+        try {
+            texto = fs.readFileSync(path.join(raiz, nombre), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const { auto, aMano } = partirContexto(texto);
+        const detalle = [
+            `total ${texto.length} chars`,
+            `auto-generado ${auto.length} (tope ${topeAuto})`,
+            `escrito a mano ${aMano.length}, sin tope`,
+        ];
+        // El aviso salta cuando lo de a mano PASA del bloque racionado: hasta ahí,
+        // la comparación no dice nada que preocupe.
+        out.push({
+            nivel: aMano.length > topeAuto ? 'aviso' : 'nota',
+            titulo: aMano.length > topeAuto
+                ? `${nombre}: lo escrito a mano pesa ${(aMano.length / topeAuto).toFixed(1)}× el bloque racionado`
+                : `${nombre}: ${texto.length} chars en cada sesión`,
+            detalle,
+        });
+    }
+    return out;
+}
+/**
+ * El hook de contexto: ¿está puesto, y su orden existe?
+ *
+ * Un hook cuyo comando no resuelve falla en silencio para siempre — la línea
+ * que instala el propio producto acaba en `|| true`, así que ni siquiera deja
+ * un exit distinto de cero. Es el Invariante 17 en la instalación.
+ */
+export function hookDeImpacto(raiz) {
+    const p = path.join(raiz, '.claude', 'settings.json');
+    let crudo;
+    try {
+        crudo = fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        return [
+            {
+                nivel: 'aviso',
+                titulo: 'No hay hook de impacto instalado',
+                detalle: [
+                    'Sin él, nadie te avisa de qué depende del fichero que vas a tocar.',
+                    'Se instala con `changebook init`.',
+                ],
+            },
+        ];
+    }
+    const puesto = /changebook\s+impact/.test(crudo);
+    return puesto
+        ? []
+        : [
+            {
+                nivel: 'aviso',
+                titulo: '.claude/settings.json existe pero no lanza `changebook impact`',
+                detalle: ['Se reinstala con `changebook init`.'],
+            },
+        ];
+}
+/** Todas las comprobaciones, en el orden en que conviene leerlas. */
+export function auditarSetup(raiz) {
+    return [...citasRotas(raiz), ...hookDeImpacto(raiz), ...pesoDeContexto(raiz)];
+}
+export function informeDeAuditoria(hallazgos) {
+    const avisos = hallazgos.filter((h) => h.nivel === 'aviso');
+    if (hallazgos.length === 0)
+        return 'Setup sin nada que señalar.';
+    const cabecera = avisos.length === 0
+        ? 'Setup sin avisos.'
+        : `${avisos.length} aviso(s) sobre tu setup:`;
+    return [
+        cabecera,
+        ...hallazgos.map((h) => [
+            `${h.nivel === 'aviso' ? '⚠' : '·'} ${h.titulo}`,
+            ...h.detalle.map((d) => `    ${d}`),
+        ].join('\n')),
+    ].join('\n');
+}
+//# sourceMappingURL=audit.js.map

package/dist/friccionDelBrief.js

@@ -0,0 +1,102 @@
+/**
+ * La entrega de la fricción por el MCP **local** (stdio), gemela de
+ * `supabase/functions/_shared/friccionConsultas.ts`.
+ *
+ * POR QUÉ EXISTE, medido el 24/08: el bloque de fricción se implementó sólo en
+ * la edge function, así que un agente conectado por el **CLI del paquete npm**
+ * —que es como se conecta la mayoría, y como estaba conectada la sesión que
+ * escribió esto— no veía la fricción JAMÁS. El lector y el comando
+ * `changebook friction` sí estaban en el CLI; lo que faltaba era la entrega.
+ *
+ * Es la misma deriva entre las dos implementaciones que ya costó las once
+ * portadas del paquete: el MCP stdio registraba 4 tools y su propio `sync.ts`
+ * pedía 7. Por eso esto vive en un fichero gemelo del del servidor y no
+ * mezclado con el lector: `test/laFriccionEsLaMismaEnLosDosLados.test.ts` los
+ * compara función a función, y un gemelo que se quede corto pone rojo.
+ *
+ * El corte es el MISMO que en el servidor: `friction.ts` rinde la línea de un
+ * suceso, esto arma la consulta y el bloque.
+ *
+ * ⚠ LO QUE SIGUE SIN CUBRIRSE, Y ES DELIBERADO: el hospedado sirve además la
+ * TASA por fichero en `atlas_file_context`, y el CLI no. No es un olvido: esa
+ * línea exige ≥2 correcciones sobre el mismo fichero y, medido el 24/08 contra
+ * las 1.509 filas de producción, la cumple **1 fichero de 341**. Pagar una
+ * consulta de red en el camino que corre ANTES DE CADA EDICIÓN para eso es un
+ * mal cambio. Si algún día la densidad sube, el gemelo que falta es
+ * `consultaPorFicheros` + `friccionPorRuta`, y el contrato de paridad de
+ * `test/laFriccionEsLaMismaEnLosDosLados.test.ts` es donde se engancha.
+ */
+import { lineaDeSuceso, VENTANA_DIAS } from "./friction.js";
+/**
+ * El techo de PostgREST. Pedir más no trae más: trae 1.000 y se calla.
+ *
+ * Aquí casi no muerde, y a propósito: la consulta filtra por veredicto en el
+ * servidor, así que lo que cuenta contra el techo son las correcciones (8 en 30
+ * días, medido) y no las ediciones (1.509).
+ */
+export const TOPE_DE_FILAS = 1000;
+/**
+ * Cuántos sucesos como mucho en el brief. Es lo PRIMERO que lee el agente al
+ * abrir y ya es largo: cinco caben sin desplazar a los avisos abiertos.
+ */
+export const MAX_SUCESOS = 5;
+export function desdeLaVentana(ahoraMs) {
+    return new Date(ahoraMs - VENTANA_DIAS * 24 * 60 * 60 * 1000).toISOString();
+}
+/**
+ * La consulta de sucesos. Idéntica a la del servidor, y el contrato de paridad
+ * lo exige carácter a carácter: dos URLs que difieran en el `order` o en el
+ * filtro darían briefs distintos según por dónde te conectes.
+ */
+export function consultaDeSucesos(filtroProyecto, ahoraMs) {
+    return (`friction_event?select=occurred_at,path,module` +
+        `&veredicto=eq.correccion` +
+        `&occurred_at=gte.${desdeLaVentana(ahoraMs)}` +
+        `&order=occurred_at.desc&limit=${TOPE_DE_FILAS}${filtroProyecto}`);
+}
+export function sucesosDeFriccion(filas) {
+    // Se reordena aquí aunque la consulta ya pida `order=occurred_at.desc`: esta
+    // función es pura y tiene contrato propio, y un contrato que depende del
+    // `order` de OTRO módulo se rompe el día que alguien reutilice ésta con filas
+    // de otra procedencia.
+    return filas
+        .map((f) => ({ fecha: f.occurred_at, ruta: f.path, modulo: f.module }))
+        .sort((a, b) => (b.fecha ?? "").localeCompare(a.fecha ?? ""));
+}
+/**
+ * Las líneas del bloque del brief, o `[]` si no hay nada que decir.
+ *
+ * Publica SUCESOS, no una tasa: con 8 correcciones en 30 días un porcentaje no
+ * informa de nada, y ocho hechos con su fecha sí. El razonamiento entero está
+ * en `docs/superpowers/specs/2026-08-23-mapa-de-friccion-design.md`.
+ */
+export function bloqueDeFriccion(filas) {
+    if (filas.length === 0)
+        return [];
+    const truncado = filas.length >= TOPE_DE_FILAS;
+    const sucesos = sucesosDeFriccion(filas);
+    const mostrados = sucesos.slice(0, MAX_SUCESOS);
+    // «al menos» cuando el servidor cortó: el conteo sigue siendo cierto como
+    // cota inferior, y decir el número pelado sería afirmar de más.
+    const cuantas = truncado ? `at least ${sucesos.length}` : `${sucesos.length}`;
+    const lineas = [
+        "",
+        `## Where work got redone (${cuantas} in the last ${VENTANA_DIAS} days)`,
+        ...mostrados.map((s) => `- ${lineaDeSuceso(s)}`),
+    ];
+    // No recortar en silencio: un tope alcanzado sin decirlo se lee como «esto es
+    // todo».
+    if (sucesos.length > mostrados.length) {
+        lineas.push(`- …and ${sucesos.length - mostrados.length} more.`);
+    }
+    return lineas;
+}
+/** La forma del structured, armada aquí para que el brief sólo la esparza. */
+export function friccionParaStructured(filas) {
+    return sucesosDeFriccion(filas).map((x) => ({
+        date: (x.fecha ?? "").slice(0, 10),
+        path: x.ruta,
+        module: x.modulo,
+    }));
+}
+//# sourceMappingURL=friccionDelBrief.js.map