https://cheroliv.com/ JBake Bootstrap Template en-gb Fri, 25 Sep 2026 01:37:52 +0000 Fri, 25 Sep 2026 01:37:52 +0000 https://cheroliv.com//blog/2026/0126_hyperframes_asciidoc_video_post.html Sun, 31 May 2026 00:00:00 +0000 blog/2026/0126_hyperframes_asciidoc_video_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_agujero_en_el_pipeline_de_video">El Agujero en el Pipeline de Video</a></li> <li><a href="#_hyperframes_el_motor">HyperFrames : El Motor</a></li> <li><a href="#_la_arquitectura_del_plugin">La Arquitectura del Plugin</a> <ul class="sectlevel2"> <li><a href="#_el_pipeline_en_cuatro_pasos">El Pipeline En Cuatro Pasos</a></li> <li><a href="#_el_dsl_asciidoc">El DSL AsciiDoc</a></li> <li><a href="#_el_puente_node_js">El Puente Node.js</a></li> </ul> </li> <li><a href="#_dos_plugins_de_video_dos_usos">Dos plugins de video, dos usos</a></li> <li><a href="#_los_6_epics_de_la_hoja_de_ruta">Los 6 EPICs de la hoja de ruta</a></li> <li><a href="#_por_qué_funciona">¿Por qué funciona?</a></li> <li><a href="#_conclusión_el_eslabón_faltante">Conclusión : El eslabón faltante</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 8 minutes</div> <p>Hace dos semanas, he lanzado`capsule-gradle`— un plugin que transforma un deck reveal.js en cápsula de video WebM con TTS. Hoy, añado un nuevo plugin : <code>hyperframes-gradle</code>. Hace algo que capsule-gradle no hace: transformar el AsciiDoc <strong>directamente</strong> en video MP4, sin pasar por reveal.js.</p> </div> <div class="paragraph"> <p>Aquí está por qué existe este plugin, cómo se articula con lo existente, y lo que el motor HyperFrames de HeyGen aporta al pipeline de producción de contenido.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_agujero_en_el_pipeline_de_video">El Agujero en el Pipeline de Video</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mi pipeline documental produce dos tipos de videos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Cápsula de revisión</strong> (capsule-gradle) — un deck reveal.js capturado en WebM con</p> </li> </ol> </div> <div class="paragraph"> <p>narración TTS. Perfecto para revisar un módulo.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Diapositivas de animación</strong> (slider-gradle) — una presentación reveal.js HTML interactiva para</p> </li> </ol> </div> <div class="paragraph"> <p>el formador presencial.</p> </div> <div class="paragraph"> <p>Pero falta un tercer formato: el <strong>video independiente</strong>.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5565%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">caso de uso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solución actual</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Falta</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides formador</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">slider-gradle → reveal.js</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cápsula de revisión</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Vídeo avance</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ninguna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Demo técnica animada</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ninguna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>De documento a video</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ninguna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El primer caso de uso es crítico: ¿cómo generar automáticamente? un video de 60 segundos que presenta un proyecto o un módulo, con animaciones GSAP, narración TTS, y música de fondo—todo desde el mismo archivo AsciiDoc ¿qué tal las diapositivas?</p> </div> <div class="paragraph"> <p>Capsule-gradle no puede responder: <strong>ya</strong> necesita un deck reveal.js. slider-gradle produce bien este deck, pero no está diseñado para el renderizado de video. Era necesario un pipeline <strong>direct</strong> : AsciiDoc → video.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_el_motor">HyperFrames : El Motor</h2> <div class="sectionbody"> <div class="paragraph"> <p>He descubiertohttps://github.com/heygen-com/hyperframes[HyperFrames] il y a unos días. Es un framework de código abierto (Apache 2.0) creado por HeyGen, el unicornio del video IA. 22 700 estrellas en GitHub. El pitch mantiene en una frase:</p> </div> <div class="paragraph"> <p>Escribe HTML. Renderiza video. Construido para agentes.</p> </div> <div class="paragraph"> <p>El principio: escribes HTML con`data-*`atributos, usted referencia una animación GSAP (o CSS, Lottie, Three.js…), y el motor renderiza todo en MP4 via Puppeteer (headless Chrome) + FFmpeg. Resultado determinista: misma entrada, mismos frames, mismo video.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><div id="stage" data-composition-id="intro" data-start="0" data-width="1920" data-height="1080"> <video class="clip" data-start="0" data-duration="6" data-track-index="0" src="background.mp4" muted playsinline></video> <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1"> Formation Docker & Kubernetes </h1> <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.3" src="music.wav"></audio> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.__timelines = window.__timelines || {}; window.__timelines.intro = tl; </script> </div></code></pre> </div> </div> <div class="paragraph"> <p>¿Qué hace que HyperFrames sea diferente de Remotion? Nada de React, nada de bundler, sin JSX. HTML sin formato que los agentes IA pueden escribir de forma nativa. Está diseñado <strong>exactamente</strong> para mi pipeline: planner-gradle con deepseek puede generar este HTML a partir de un plan SPG/SPD, y un plugin Gradle puede convertirlo a MP4.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_arquitectura_del_plugin">La Arquitectura del Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle sigue el mismo patrón que todos mis plugins: el <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">pattern « Plugin Independiente + Raíz Consumidor »</a></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">hyperframes-gradle/ ├── settings.gradle.kts ← racine consommateur (dogfood) ├── build.gradle.kts ← 3 lignes : apply plugin hyperframes ├── hyperframes-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── build.gradle.kts ← java-gradle-plugin │ ├── src/main/kotlin/education/cccp/hyperframes/ │ │ ├── HyperframesPlugin.kt │ │ ├── GenerateHyperframesHtmlTask.kt │ │ ├── RenderHyperframesTask.kt │ │ └── HyperframesExtension.kt │ ├── .agents/ ← gouvernance agent │ └── doc/ │ └── HYPERFRAMES_ARCHITECTURE.adoc └── video.yml ← configuration dogfood</code></pre> </div> </div> <div class="sect2"> <h3 id="_el_pipeline_en_cuatro_pasos">El Pipeline En Cuatro Pasos</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Pipeline hyperframes-gradle rectangle "AsciiDoc fuente" as adoc #LightYellow ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Pipeline hyperframes-gradle rectangle "AsciiDoc fuente" as adoc #LightYellow rectangle "AsciidoctorJ" as asciidoctorj #LightBlue rectangle "HTML HyperFrames (data-* atributos)" as html #LightGreen rectangle "HyperFrames CLI (Node.js 22+)" as cli #Lavender rectangle "video.mp4" as mp4 #Gold adoc -right-> asciidoctorj : parse blocs customs asciidoctorj -right-> html : génère HTML html -right-> cli : ProcessBuilder\nnpx hyperframes render cli -right-> mp4 : Puppeteer + FFmpeg @enduml</pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>AsciidoctorJ</strong> analiza la fuente AsciiDoc y extrae los bloques customs</p> </li> </ol> </div> <div class="paragraph"> <p><code>[hyperframes-composition]</code>, <code>[hyperframes-track]</code>, <code>[hyperframes-animation]</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>GenerateHyperframesHtmlTask</strong> genera el HTML HyperFrames con los</p> </li> </ol> </div> <div class="paragraph"> <p>`data-*`atributos correspondientes.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RenderHyperframesTask</strong> llama a la CLI de HyperFrames mediante`ProcessBuilder`:</p> </li> </ol> </div> <div class="paragraph"> <p><code>npx hyperframes render --input index.html --output video.mp4</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>El MP4 se despliega en`output/`con un`metadata.json`para la orquestación.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_el_dsl_asciidoc">El DSL AsciiDoc</h3> <div class="paragraph"> <p>El verdadero valor añadido del plugin, es el DSL AsciiDoc. El usuario Nunca escribe HTML. Annota su documento AsciiDoc existente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Formation Docker & Kubernetes :hyperframes-width: 1920 :hyperframes-height: 1080 :hyperframes-fps: 30 [hyperframes-composition, id="intro"] == Introduction Le titre apparaît avec un fondu GSAP sur fond vidéo. [hyperframes-track, index=0, start=0, duration=6] video::assets/background.mp4[muted, playsinline] [hyperframes-track, index=1, start=1, duration=4] Formation Docker & Kubernetes [hyperframes-animation, type=gsap]</code></pre> </div> </div> <div class="paragraph"> <p>const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.<em>timelines = window.</em>timelines || {}; window.__timelines.intro = tl;</p> </div> <div class="paragraph"> <p>Los atributos docinfo (<code>:hyperframes-width:</code>) configuran las dimensiones. Los bloques custom definen las composiciones y los tracks. El bloque `[hyperframes-animation]`contiene el código GSAP bruto — que el agente IA puede generar a partir de una descripción en lenguaje natural.</p> </div> </div> <div class="sect2"> <h3 id="_el_puente_node_js">El Puente Node.js</h3> <div class="paragraph"> <p>El único punto de fricción técnica: HyperFrames está desarrollado con Node.js/TypeScript, y mis plugins están en Kotlin/JVM. La solución es un`ProcessBuilder`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class RenderHyperframesTask : DefaultTask() { @TaskAction fun render() { val process = ProcessBuilder( "npx", "hyperframes", "render", "--input", inputHtml.absolutePath, "--output", outputMp4.absolutePath ) .inheritIO() .start() val exitCode = process.waitFor() require(exitCode == 0) { "HyperFrames render failed with exit code $exitCode" } } }</code></pre> </div> </div> <div class="paragraph"> <p>Cero acoplamiento código JVM ↔ Node.js. El contrato es por línea de comandos. y archivos en disco. Es el mismo patrón que`plantuml-gradle` (que llama a la CLI PlantUML) o`slider-gradle`(que llama a AsciidoctorJ). Nada nuevo bajo el sol — solo aplicado a una herramienta más reciente.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dos_plugins_de_video_dos_usos">Dos plugins de video, dos usos</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.762%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">hyperframes-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fuente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Deck reveal.js (HTML existente)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">AsciiDoc → HTML HyperFrames</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Use case</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cápsula de revisión</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Vídeo explicativo independiente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">naturaleza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides → vídeo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documento → video</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Entregado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Playwright Java → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HyperFrames CLI → MP4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Animación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transiciones nativas de reveal.js</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GSAP/CSS atributos de datos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stack</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% JVM (Kotlin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JVM + CLI externa de Node.js</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>No se reemplazan. Se complementan. La cadena de valor completa:</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ slider-gradle ──→ deck reveal.js ──→ capsule-gradle ──→ WebM (cápsula de revisión)</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ hyperframes-gradle ──→ MP4 (vídeo autónomo)</p> </div> <div class="paragraph"> <p>El usuario escribe un solo archivo AsciiDoc. slider-gradle produce las diapositivas. capsule-gradle produce la cápsula de revisión. hyperframes-gradle produce el vídeo teaser y las demostraciones técnicas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_los_6_epics_de_la_hoja_de_ruta">Los 6 EPICs de la hoja de ruta</h2> <div class="sectionbody"> <div class="paragraph"> <p>El plugin está estructurado en 6 EPICs :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ÉPICO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Descripción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Prioridad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap gobernanza + alcance arquitectura</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅ TERMINADO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plugin Gradle stub + integración AsciidoctorJ</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Puente CLI HyperFrames (ProcessBuilder → npx → MP4)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DSL AsciiDoc costumbres (bloques, docinfo, plantillas)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Integración de runner-gradle (metadata.json)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Listos para usar (title-card, code-diff, captions)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI + publicación Maven Central / Portal de Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La sesión 000 (bootstrap) ya ha finalizado. La sesión 001 atacará HF-1 : el stub del plugin Gradle y la integración AsciidoctorJ</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_funciona">¿Por qué funciona?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tres razones:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HyperFrames está "built for agents</strong>". Mi pipeline se basa en agentes IA</p> </li> </ol> </div> <div class="paragraph"> <p>(planner-gradle + deepseek) que generan contenido. HyperFrames acepta HTML crudo — el formato que los LLM dominan mejor. Sin React, sin de JSX, no hay curva de aprendizaje para el agente.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>El DSL AsciiDoc es natural</strong>. Todo mi ecosistema habla AsciiDoc.</p> </li> </ol> </div> <div class="paragraph"> <p>slider-gradle, codex-gradle, training-gradle — todos consumen de`.adoc`. Agregar bloques personalizados`[hyperframes-composition]`es una extensión lógico, no una ruptura.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>El puente Node.js es un patrón probado</strong>. ProcessBuilder fuera de la JVM</p> </li> </ol> </div> <div class="paragraph"> <p>Esto es lo que ya hago para PlantUML, Graphviz, Piper. Agregar HyperFrames No cambia la arquitectura — es simplemente otra herramienta externa, Controlado desde Gradle.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>La verdadera fuerza del patrón es que no hay <strong>ninguna</strong> dependencia npm en el build Gradle. El plugin no importa código Node.js. Ejecuta una comando de shell. Si HyperFrames evoluciona o se rompe, el plugin no está acoplado — basta con actualizar el comando</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_eslabón_faltante">Conclusión : El eslabón faltante</h2> <div class="sectionbody"> <div class="paragraph"> <p>Con hyperframes-gradle, mi pipeline de vídeo está completo. Tengo :</p> </div> <div class="ulist"> <ul> <li> <p>Las <strong>slides interactivas</strong> (slider-gradle)</p> </li> <li> <p>Los <strong>cápsulas de revisión</strong> (capsule-gradle)</p> </li> <li> <p>Los <strong>videos standalone</strong> (hyperframes-gradle)</p> </li> </ul> </div> <div class="paragraph"> <p>Tres formatos. Un único archivo fuente: AsciiDoc.</p> </div> <div class="paragraph"> <p>El próximo objetivo es HF-1: compilar el plugin y generar un primer HTML HyperFrames a partir de un documento AsciiDoc anotado. La sesión 001 ya está encuadrada.</p> </div> <div class="paragraph"> <p>hyperframes-gradle existe. La gobernanza está establecida. El backlog está escrito. La arquitectura está documentada. El plugin nació.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">Artículo 0124 — La Arquitectura del Plugin Independiente + Raíz Consumidor</a></p> </li> <li> <p><a href="https://github.com/heygen-com/hyperframes">HyperFrames — GitHub</a></p> </li> <li> <p><a href="https://hyperframes.heygen.com/introduction">HyperFrames — Documentación</a></p> </li> <li> <p><code>foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc</code>— Arquitectura detallada</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html Mon, 18 May 2026 00:00:00 +0000 blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_comprender_la_pila_quién_hace_qué">Comprender la pila: ¿Quién hace qué?</a></li> <li><a href="#_introducción_por_qué_una_auditoría">Introducción: ¿Por qué una auditoría?</a></li> <li><a href="#_la_base_de_datos_opencode_una_mina_de_oro">La Base de Datos OpenCode : Una Mina de Oro</a> <ul class="sectlevel2"> <li><a href="#_el_esquema">El esquema</a></li> <li><a href="#_el_código_de_extracción">El Código de Extracción</a></li> </ul> </li> <li><a href="#_los_resultados_73_días_de_consumo">Los Resultados : 73 Días de Consumo</a> <ul class="sectlevel2"> <li><a href="#_vista_global">Vista Global</a></li> <li><a href="#_ventilación_por_modelo_y_proveedor">Ventilación por Modelo y Proveedor</a></li> <li><a href="#_los_modelos_intra_sesión_lo_que_la_tabla_de_sesión_no_ve">Los Modelos Intra-Sesión: Lo que la tabla de sesión no ve</a></li> </ul> </li> <li><a href="#_comparativa_tarifaria_proveedores_occidentales">Comparativa Tarifaria — Proveedores Occidentales</a> <ul class="sectlevel2"> <li><a href="#_anthropic_claude">Anthropic — Claude</a></li> <li><a href="#_openai_gpt">OpenAI — GPT</a></li> <li><a href="#_google_gemini">Google — Gemini</a></li> <li><a href="#_proveedores_de_inferencia_de_huggingface">Proveedores de inferencia de HuggingFace</a></li> <li><a href="#_groq">Groq</a></li> </ul> </li> <li><a href="#_comparativo_tarifario_proveedores_chinos">Comparativo Tarifario — Proveedores Chinos</a> <ul class="sectlevel2"> <li><a href="#_deepseek_api_directo_platform_deepseek_com">DeepSeek API Directo (platform.deepseek.com)</a></li> <li><a href="#_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</a></li> <li><a href="#_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</a></li> </ul> </li> <li><a href="#_tabla_resumen_todos_los_proveedores">Tabla Resumen — Todos los Proveedores</a></li> <li><a href="#_el_costo_oculto_ingeniería_de_prompt_y_iteraciones">El Costo Oculto: Ingeniería de Prompt y Iteraciones</a></li> <li><a href="#_acumular_las_suscripciones_ollama_cloud_pro_el_método_docker">Acumular las suscripciones Ollama Cloud Pro : El método Docker</a></li> <li><a href="#_lo_que_la_auditoría_no_mide">Lo que la auditoría no mide</a></li> <li><a href="#_conclusión_el_veredicto_de_los_números">Conclusión: El Veredicto de los Números</a></li> <li><a href="#_referencias">Referencias</a> <ul class="sectlevel2"> <li><a href="#_fuentes_de_las_tarifas">Fuentes de las Tarifas</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 22 minutes</div> <p>Me preguntan con frecuencia cuánto cuesta mi consumo de IA. Respondo « 20 bolas al mes » y me miran con los ojos muy abiertos. Entonces hoy, te abro la caja negra. Este artículo es la auditoría completa de mis 73 días de vibe coding: la metodología para extraer los datos desde la base SQLite de OpenCode, el código SQL para consultar las tablas, y la comparación exhaustiva con <strong>todos</strong> los proveedores del mercado — occidentales y chinos. El resultado es tan asimétrico que tuve que verificar mis cálculos tres veces.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_comprender_la_pila_quién_hace_qué">Comprender la pila: ¿Quién hace qué?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de sumergirnos en los números, aclaramos la arquitectura. Hay tres actores distintos en mi setup, y es importante no confundirlos:</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 11) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Los Tres Actores de Mi Stack LLM left to right direction actor "Yo (Desarrollador)" as Dev package "OpenCode\n(github.com/anomalyco/opencode)" as OC { rectangle "CLI de vibe coding ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Los Tres Actores de Mi Stack LLM left to right direction actor "Yo (Desarrollador)" as Dev package "OpenCode\n(github.com/anomalyco/opencode)" as OC { rectangle "CLI de vibe coding Código abierto, gratuito" as CLI note right of CLI C'est l'outil que j'utilise pour coder avec des agents IA. Il ne fournit AUCUN modèle. C'est un terminal + un orchestrateur. end note } package "Ollama (Instalación Local)" as OL { rectangle "Cliente de inferencia Instalado en mi máquina" as Client note right of Client C'est le logiciel qui fait tourner les modèles. Il peut les exécuter en local OU les déléguer au cloud selon le tag (:cloud). Il s'authentifie via clé SSH. end note } package "Ollama Cloud (ollama.com)" as OCloud { rectangle "Servicio de inferencia en la nube Suscripción Pro : 20€/mes" as Cloud note right of Cloud C'est le fournisseur d'inférence. Mes modèles avec le tag :cloud sont exécutés sur LEURS serveurs. L'abonnement Pro donne accès à des quotas supérieurs. end note } Dev --> CLI : "Yo tecleo prompts" CLI --> Client : "Llame este modelo" Client --> Cloud : "Clave SSH + solicitud\n(modelos :cloud)" Client --> Client : "Ejecución local (modelos sin :cloud)" @enduml</pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>OpenCode no es un proveedor de modelos.</strong>Es un CLI de código abierto (<a href="https://github.com/anomalyco/opencode">github.com/anomalyco/opencode</a>) que orquesta agentes de IA. No vende suscripciones, no proporciona inferencia. Es el equivalente de`git`para el versionamiento: una herramienta, no un servicio. <strong>Ollama Cloud es el proveedor de inferencia.</strong>Mi instalación local de Ollama actúa como <strong>cliente</strong> — se autentica ante los servidores de Ollama mediante una clave SSH única (Device Key) y delega la ejecución de los modelos etiquetados`:cloud`. La suscripción Pro (20€/mes) desbloquea cuotas superiores y permite acumular varias cuentas en la misma máquina mediante Docker.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_introducción_por_qué_una_auditoría">Introducción: ¿Por qué una auditoría?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hace dos meses, usaba modelos de forma gratuita en mi instalación local de Ollama. Luego contraté mi primera suscripción a Ollama Cloud Pro a 20€/mes, que me permite usar los modelos en la nube (aquellos con la etiqueta`:cloud`) vía el proveedor`ollama-cloud`. Un segundo abonnement siguió un mes después, en una instancia Docker separada con su propia cuenta y su propia clave SSH — el método de acumulación descrito en <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">mi artículo sobre la acumulación de suscripciones</a>.</p> </div> <div class="paragraph"> <p>La pregunta que me martilleaba : <strong>¿Están justificados esos 20€ al mes?</strong> No a ojo. Con cifras.</p> </div> <div class="paragraph"> <p>Para responder, necesitaba datos precisos. No estimaciones. No promedios. Mi consumo <strong>real</strong>, token por token, modelo por modelo, sesión por sesión.</p> </div> <div class="paragraph"> <p>Y OpenCode — la CLI — almacena todo eso en una base SQLite.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_base_de_datos_opencode_una_mina_de_oro">La Base de Datos OpenCode : Una Mina de Oro</h2> <div class="sectionbody"> <div class="paragraph"> <p>OpenCode persiste la totalidad del historial de sus sesiones en un archivo SQLite ubicado en`~/.local/share/opencode/opencode.db`. La mienne pèse 660 Mo pour 73 jours d’utilisation — une base de données de production tout à fait respectable.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ls -lh ~/.local/share/opencode/opencode.db -rw-r--r-- 1 cheroliv cheroliv 660M mai 18 12:25 opencode.db</code></pre> </div> </div> <div class="sect2"> <h3 id="_el_esquema">El esquema</h3> <div class="paragraph"> <p>La base contiene unas veinte tablas, pero tres de ellas son cruciales para nuestra auditoría:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/schema-principal.svg" alt="schema principal" width="684" height="397"> </div> </div> <div class="paragraph"> <p>La tabla`session`es perfecta para una auditoría global: cada sesión tiene su recuento de tokens agregado, su modelo utilizado y su costo. El campo`model`es JSON bruto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "id": "deepseek-v4-pro:cloud", "providerID": "ollama-cloud", "variant": "default" }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>El campo`cost`en la base OpenCode solo refleja los <strong>gastos de API externos</strong> pagados por consumo mediante clave API (Google Gemini, OpenAI, etc.). Las llamadas a través de Ollama — ya sea localmente o mediante Ollama Cloud Pro — están marcadas`cost=0`porque el costo es una tarifa fija (suscripción), no por token. El verdadero costo de estas llamadas es la suscripción mensual.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_el_código_de_extracción">El Código de Extracción</h3> <div class="paragraph"> <p>No es necesario instalar nada. Node.js 22+ incluye un módulo SQLite experimental (<code>node:sqlite</code>) que funciona perfectamente. Aquí está el script que me lo dio todo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const { DatabaseSync } = require('node:sqlite'); const db = new DatabaseSync( `${process.env.HOME}/.local/share/opencode/opencode.db`, { readonly: true } ); // 1. Statistiques globales const global = db.prepare(` SELECT COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(tokens_reasoning) as total_reasoning, SUM(tokens_cache_read) as total_cache_read, SUM(cost) as total_cost FROM session `).get(); // 2. Ventilation par modèle et fournisseur const byModel = db.prepare(` SELECT json_extract(model, '$.id') as model_id, json_extract(model, '$.providerID') as provider, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE model IS NOT NULL GROUP BY model_id, provider ORDER BY SUM(tokens_input) DESC `).all(); // 3. Par mois const monthly = db.prepare(` SELECT strftime('%Y-%m', datetime(time_created/1000, 'unixepoch')) as month, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE time_created IS NOT NULL GROUP BY month ORDER BY month `).all(); // 4. Messages par modèle (détection des changements intra-session) const msgByModel = db.prepare(` SELECT json_extract(m.data, '$.model.providerID') as provider, json_extract(m.data, '$.model.modelID') as model_id, COUNT(*) as messages FROM message m WHERE json_extract(m.data, '$.model') IS NOT NULL GROUP BY provider, model_id ORDER BY COUNT(*) DESC `).all(); console.log({ global, byModel, monthly, msgByModel }); db.close();</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>La bandera`--experimental-sqlite`es necesario en Node.js 22.x. En Node.js 24+, el módulo es estable y ya no requiere una bandera.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_los_resultados_73_días_de_consumo">Los Resultados : 73 Días de Consumo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_vista_global">Vista Global</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">métrico</th> <th class="tableblock halign-left valign-top">Valor</th> <th class="tableblock halign-left valign-top">Contexto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Sesiones OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 022</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~14 sesiones/día en promedio</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Input</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,62 mil millones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No 94,5M de aciertos de caché</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Output</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21 millones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ratio input/output ~125:1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Reasoning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">141 000</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Despreciable — casi sin pensar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Costo API externa</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$0,22</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Costos fuera de suscripción (Gemini + niveles gratuitos)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Esta cifra de $0,22 es crucial: representa todo lo que he pagado <strong>de más</strong> de mi suscripción Ollama Cloud Pro. Es decir, prácticamente nada. La suscripción cubre lo esencial.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Evolución Mensual — Tokens Input rectangle "Marzo 2026 9 sesiones ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Evolución Mensual — Tokens Input rectangle "Marzo 2026 9 sesiones 37,7M tokens" as MARS #FFE082 rectangle "Abril 2026 486 sesiones 1,33 mil millones de tokens" as AVR #81C784 rectangle "Mayo 2026\n527 sesiones\n1,25 mil millones de tokens" as MAI #64B5F6 MARS -right-> AVR : ×35 AVR -right-> MAI : stable (période en cours) note bottom of MAI Mai comptabilisé jusqu'au 18. Projection mois complet : ~2,1 Md tokens si la tendance se maintient. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El despegue entre marzo y abril es espectacular: ×35 en un mes. Es la transición del uso « prueba » al uso « producción » — cuando comencé a ejecutar continuamente agentes OpenCode para mis plugins Gradle.</p> </div> </div> <div class="sect2"> <h3 id="_ventilación_por_modelo_y_proveedor">Ventilación por Modelo y Proveedor</h3> <div class="paragraph"> <p>El campo`model`de la mesa`session`siendo del JSON,`json_extract()`permite ventilar limpiamente :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modelo × Provider</th> <th class="tableblock halign-left valign-top">Sesiones</th> <th class="tableblock halign-left valign-top">Input</th> <th class="tableblock halign-left valign-top">Output</th> <th class="tableblock halign-left valign-top">Costo</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama-cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">63</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">220 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,94 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama-b</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">124</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">463 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4,15 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">252 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,25 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-flash-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">16</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,3 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">279 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">qwen3.6-plus-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">369 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">25 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">gemini-2.5-flash @ google</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">211 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,04</p></td> </tr> </tbody> </table> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Tres proveedores diferentes para exactamente el mismo modelo DeepSeek V4 Pro : * <code>ollama-cloud</code>→ via <strong>suscripción Pro de pago</strong> (cloud gestionado por Ollama) * <code>ollama-b`segunda suscripción Pro", aislado en un contenedor Docker distinto * `ollama</code>→ instance native locale, <strong>gratuita</strong> (se ejecuta directamente en mi máquina) La suma de los tres da 936M entrada, 8,4M salida — es mi consumo total de DeepSeek V4 Pro, todos los proveedores combinados. Sólo`ollama-cloud`(220M entrada) cuesta una suscripción. Los 716M restantes son gratuitos (local o acumulación de suscripciones).</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_los_modelos_intra_sesión_lo_que_la_tabla_de_sesión_no_ve">Los Modelos Intra-Sesión: Lo que la tabla de sesión no ve</h3> <div class="paragraph"> <p>La mesa`session`Solo captura el modelo <strong>principal</strong> de la sesión. Pero durante la misma sesión, un agente OpenCode puede cambiar entre varios modelos. La tabla`message`lo revela:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Modèles utilisés dans les messages (ollama-cloud provider) : ├─ deepseek-v4-pro 1 441 msgs (32%) ├─ qwen3.5:397b 1 217 msgs (27%) ├─ glm-5.1 712 msgs (16%) ├─ kimi-k2.6:cloud 634 msgs (14%) ├─ qwen3-coder:480b 414 msgs (9%) ├─ gpt-oss:20b 34 msgs (0,8%) ├─ qwen3-coder-next 27 msgs (0,6%) └─ gemma4:31b 7 msgs (0,2%)</code></pre> </div> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Ya no utilizo Qwen, GLM, Kimi ni los otros modelos. Aparecen en el historial porque he probado bastante cosas en abril. Desde mediados de mayo, estoy bloqueado en DeepSeek V4 Pro — es el único que soporta la carga en contextos largos con gobernanza de agentes (cf. <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">mi comparación Kimi/GLM/DeepSeek</a>). El 32% de los mensajes deepseek en el historial son engañosos: hoy es 100%.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparativa_tarifaria_proveedores_occidentales">Comparativa Tarifaria — Proveedores Occidentales</h2> <div class="sectionbody"> <div class="paragraph"> <p>La pregunta que fastidia: ¿cuánto costaría este mismo consumo con los proveedores tradicionales?</p> </div> <div class="paragraph"> <p>Mi base de cálculo para la comparación:<strong>220M tokens de entrada + 1,9M tokens de salida</strong>— <strong>únicamente</strong> el volumen pasado por`ollama-cloud`(el único que corresponde a mi suscripción de pago). Los 716M restantes son gratuitos (Ollama local y instancia Docker B).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Proveedor</th> <th class="tableblock halign-left valign-top">Modelo</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Salida \$/M</th> <th class="tableblock halign-left valign-top">Costo/mes</th> <th class="tableblock halign-left valign-top">× mi suscripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mi configuración</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\~20€</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_anthropic_claude">Anthropic — Claude</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modelo</th> <th class="tableblock halign-left valign-top">$/m</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Costo/mes</th> <th class="tableblock halign-left valign-top">× mi suscripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>57×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Soneto 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>34×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>11×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Incluso Haiku 4.5, el modelo más « económico » de Claude, cuesta 11× mi suscripción. Y no conoce nada de mi código base, no genera en mi estilo y alucina en las APIs Gradle Kotlin DSL.</p> </div> </div> <div class="sect2"> <h3 id="_openai_gpt">OpenAI — GPT</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modelo</th> <th class="tableblock halign-left valign-top">$ /M ? No spaces original. Should output "$/M".</th> <th class="tableblock halign-left valign-top">GPT 5.5</th> <th class="tableblock halign-left valign-top">\$5</th> <th class="tableblock halign-left valign-top">\$30</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>58 veces</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>29×</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_google_gemini">Google — Gemini</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modelo</th> <th class="tableblock halign-left valign-top">\$/M</th> <th class="tableblock halign-left valign-top">dólares por metro</th> <th class="tableblock halign-left valign-top">Costo/mes</th> <th class="tableblock halign-left valign-top">× mi suscripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3.1 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,00</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$459</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>3,5×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Gemini 3 Flash a 69€ es el único competidor « cercano » en precio puro — pero es un modelo denso ligero, no un MoE 1.6T como DeepSeek V4 Pro. La calidad del código generado no tiene nada que ver.</p> </div> </div> <div class="sect2"> <h3 id="_proveedores_de_inferencia_de_huggingface">Proveedores de inferencia de HuggingFace</h3> <div class="paragraph"> <p>HuggingFace no hace inferencia por sí mismo — agrega <strong>providers</strong> de terceros (Novita, Together, DeepInfra, Cerebras, SambaNova, Fireworks, Groq…) mediante una API unificada. Se elige el provider más barato o el más rápido. Aquí están los precios recopilados en mayo de 2026 para DeepSeek V4 Pro :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Proveedor HF</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Salida \$/M</th> <th class="tableblock halign-left valign-top">Costo/mes</th> <th class="tableblock halign-left valign-top">× mi suscripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Novita (el más barato)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$374</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepInfra</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$389</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">juntos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$470</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fuegos artificiales</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">tarifa no pública</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[No output, as there is no French text provided to translate]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Incluso el proveedor más barato en HuggingFace (Novita) cobra 19 veces el precio de mi suscripción. Y, a diferencia de Ollama Cloud, HuggingFace cobra <strong>además</strong> los cargos de la plataforma si no tienes una suscripción PRO HF (9 $/mes).</p> </div> </div> <div class="sect2"> <h3 id="_groq">Groq</h3> <div class="paragraph"> <p>Groq no tiene <strong>ninguno</strong> de los modelos que utilizo — su catálogo se limita a GPT-OSS, Llama y Qwen 32B. Imposible de comparar.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparativo_tarifario_proveedores_chinos">Comparativo Tarifario — Proveedores Chinos</h2> <div class="sectionbody"> <div class="paragraph"> <p>La verdadera prueba es el mercado chino. Si DeepSeek es un modelo chino, su API nativa debería ser más barata, ¿no?</p> </div> <div class="sect2"> <h3 id="_deepseek_api_directo_platform_deepseek_com">DeepSeek API Directo (platform.deepseek.com)</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 22.2222%;"> <col style="width: 22.2222%;"> <col style="width: 22.2223%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">período</th> <th class="tableblock halign-left valign-top">\$/M</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Costo/mes</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Promo -75% (fin 31 mayo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,435</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$98</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tarifa completa (a partir de junio)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$390</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Incluso con la agresiva promoción de DeepSeek (-75% prolongada), la API directa cuesta<strong>5×</strong>más caro. A la tarifa normal,<strong>20×</strong>. Y esto es <strong>únicamente</strong> DeepSeek — sin acceso a otros modelos.</p> </div> </div> <div class="sect2"> <h3 id="_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</h3> <div class="paragraph"> <p>Kimi solo propone sus propios modelos. No DeepSeek.</p> </div> </div> <div class="sect2"> <h3 id="_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</h3> <div class="paragraph"> <p>Único proveedor que agrega todos los modelos chinos — pero mediante reventa con margen. Los precios se cargan dinámicamente en JavaScript, lo que hace imposible el scraping.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tabla_resumen_todos_los_proveedores">Tabla Resumen — Todos los Proveedores</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Proveedor</th> <th class="tableblock halign-left valign-top">Modelo</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Salida \$/M</th> <th class="tableblock halign-left valign-top">Costo/mes</th> <th class="tableblock halign-left valign-top">× mi suscripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20€</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3,5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (promo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,44</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$98</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$374</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (normal)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$390</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">20×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Juntos AI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$470</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">23×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">57×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">58×</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Costo Mensual Proyectado — 220M Entrada + 1,9M Salida rectangle "Ollama Cloud Pro ~20€" as OC #4CAF50 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Costo Mensual Proyectado — 220M Entrada + 1,9M Salida rectangle "Ollama Cloud Pro ~20€" as OC #4CAF50 rectangle "Gemini Flash $69" as GF #8BC34A rectangle "Promoción DeepSeek $98" as DSP #FFC107 rectangle "GPT Mini\n\$174" as GM #FF9800 rectangle "Claude Haiku $230" as CH #FF5722 rectangle "HF/Novita\n\$374" as HF #F44336 rectangle "DeepSeek normal\n\$390" as DSN #F44336 rectangle "GPT 5.4 \$579" as G4 #D32F2F rectangle "Claude Sonnet $689" as CS #D32F2F rectangle "Claude Opus $1 148" as CO #B71C1C rectangle "GPT 5.5 $1 157" as G5 #880E4F note bottom of OC DeepSeek V4 Pro 1.6T MoE + accès à tout le catalogue Ollama Cloud (Qwen, GLM, Kimi...) Inclus dans l'abonnement end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_costo_oculto_ingeniería_de_prompt_y_iteraciones">El Costo Oculto: Ingeniería de Prompt y Iteraciones</h2> <div class="sectionbody"> <div class="paragraph"> <p>El costo token solo es una parte de la ecuación. El verdadero costo es el tiempo del desarrollador.</p> </div> <div class="paragraph"> <p>Con OpenCode + Ollama Cloud Pro + mi agente de gobernanza (EAGER/LAZY/Hot/Warm/Cold, descrito en <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">el artículo sobre la gobernanza</a>), obtengo :</p> </div> <div class="ulist"> <ul> <li> <p><strong>0 prompt engineering repetitivo</strong>: el contexto se inyecta automáticamente</p> </li> <li> <p><strong>90%+ primer disparo correcto</strong>: el código compila a la primera</p> </li> <li> <p><strong>Cero alucinaciones deepseek en 8 sesiones consecutivas</strong>(documentado en <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">la comparación Kimi/GLM/DeepSeek</a>)</p> </li> </ul> </div> <div class="paragraph"> <p>Con Claude o GPT <strong>sin</strong> ajuste fino ni gobernanza :</p> </div> <div class="ulist"> <ul> <li> <p>2-3 iteraciones por tarea en promedio</p> </li> <li> <p>Ingeniería de prompts sistemática</p> </li> <li> <p>Alucinaciones sobre las APIs Kotlin/Gradle en cuanto el contexto supera los 30K tokens</p> </li> </ul> </div> <div class="paragraph"> <p>El costo « efectivo » mensual — tokens × iteraciones × tiempo de corrección — es de 27× a 54× el de mi solución, como he demostrado en <a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">el artículo sobre la relación de eficiencia</a>.</p> </div> <div class="paragraph"> <p><em><em>_ No es solo una cuestión de precio por token. Un Claude Opus que cuesta 57 veces el precio y requiere 3 veces más iteraciones tiene un costo efectivo aproximadamente 170 veces superior. Para decirlo crudamente: pagar a un becario el salario de un socio de McKinsey. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_acumular_las_suscripciones_ollama_cloud_pro_el_método_docker">Acumular las suscripciones Ollama Cloud Pro : El método Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si una sola suscripción no basta, las acumulamos. El principio consiste en aislar cada suscripción en su propia instalación de Ollama, con su propia clave SSH de autenticación. Docker lo hace trivial.</p> </div> <div class="paragraph"> <p>El método completo está detallado en <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">el artículo sobre la acumulación de Docker</a>, aquí tienes el principio :</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Arquitectura — Dos suscripciones Ollama Cloud Pro en una máquina left to right direction node "Mi Máquina Física" { frame "Ollama Instancia A (nativo) ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Arquitectura — Dos suscripciones Ollama Cloud Pro en una máquina left to right direction node "Mi Máquina Física" { frame "Ollama Instancia A (nativo) puerto :11434" as Native { database "Identidad A /usr/share/ollama/.ollama/id_ed25519" } frame "Ollama instancia B (Docker) puerto:11435" as Docker { database "Identity B\n~/ollama-b-data/id_ed25519" } } cloud "Ollama Cloud" { actor "Cuenta Pro A\n(email 1)" as A actor "Cuenta Pro B\n(correo 2)" as B } Native --> A : "Clave del dispositivo A" Docker --> B : "Dispositivo tecla B" note bottom of Docker Conteneur Docker isolé : - Clé SSH distincte - Port réseau distinct (11435) - Volume persistant (~/ollama-b-data) - restart: always end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El patrón es simple :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Crear un volumen`~/ollama-b-data`</p> </li> <li> <p>Ejecutar un contenedor Docker`ollama/ollama:0.20.2`mapeado sobre`11435:11434`</p> </li> <li> <p>Recuperar la clave SSH del contenedor → guardarla en ollama.com</p> </li> <li> <p>hacer`ollama signin`con un segundo correo electrónico</p> </li> <li> <p>Configurar OpenCode con dos proveedores (`ollama`sobre :11434,`ollama-b`sobre :11435)</p> </li> </ol> </div> <div class="paragraph"> <p>Dos cuentas, una tarjeta azul, cero conflicto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_la_auditoría_no_mide">Lo que la auditoría no mide</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ángulo muerto</th> <th class="tableblock halign-left valign-top">Impacto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Calidad del código producido</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,6 mil millones de tokens no dicen si el código compila. Mis 8 sesiones DeepSeek V4 Pro tienen una tasa de first-shot >90%.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ecosistema OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El CLI es gratuito, pero su valor (agentes, sandboxes, historial, caché de prompts) es inmenso. No está incluido en el precio de la suscripción — es una herramienta independiente.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Costo de oportunidad</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pasar 2h/día depurando alucinaciones de un modelo inferior cuesta más que 20€/mes.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>paz mental</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tarifa fija = sin sorpresas. Con el per-token, un pico de actividad puede hacer mucho daño.</p></td> </tr> </tbody> </table> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Los precios citados son los de mayo de 2026. Dentro de seis meses, todo habrá bajado. Pero la relación de fuerza estructural — suscripción fija vs pago por uso — seguirá siendo favorable a la suscripción para los grandes consumidores.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_veredicto_de_los_números">Conclusión: El Veredicto de los Números</h2> <div class="sectionbody"> <div class="paragraph"> <p>Después 73 días, 1 022 sessions OpenCode, y 2,6 mil millones de tokens:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 60%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Métrico</th> <th class="tableblock halign-left valign-top">Veredicto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo API externa acumulado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$0,22</strong>(casi nulo)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo suscripción Ollama Cloud Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20€/mes</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente Claude Opus</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$1 148/mes</strong>— 57× más caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$1 157/mes</strong>— 58× más caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$374/mes</strong>— 19× más caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente DeepSeek API directo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$390/mes</strong>— 20× más caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">El equivalente más barato (Gemini Flash)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$69/mes</strong>— 3,5× más caro, modelo inferior</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mejor oferta del mercado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro a 20€/mes</strong>— imbatible</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>No source text was provided for translation. A los 20 € al mes para acceder a DeepSeek V4 Pro (1.6 T params, MoE, CSA+HCA, 1M contexto) vía Ollama Cloud, tengo el mejor relación calidad‑precio del mercado mundial. Incluso los proveedores chinos en directo són de 5× a 20× más caros. Incluso HuggingFace, con su agregación de proveedores low‑cost, es 19× más caro. El mercado occidental (Claude, GPT) está a 50‑60× — otra_planeta.</p> </div> <div class="paragraph"> <p>Esta proporción está tan desequilibrada que no puede durar eternamente. Aprovecha mientras exista. </think></p> </div> <div class="paragraph"> <p>Entonces sí, mis 20 euros al mes, es la mejor inversión técnica de mi vida de desarrollador. Y ahora tienes los números para demostrarlo.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0108_gouvernance_agent_opcode_eager_lazy_post.html">Artículo 0108 — Gobernanza de agente EAGER/LAZY/Hot/Warm/Cold</a></p> </li> <li> <p><a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Artículo 0112 — DeepSeek V4 Pro vs Kimi K2.6 vs GLM 5.1</a></p> </li> <li> <p><a href="0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html">Artículo 0119 — Comparativa DGX Spark vs Cloud vs Suscripciones LLM</a></p> </li> <li> <p><a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">Artículo 0120 — Combinar dos suscripciones Ollama Cloud Pro con Docker</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Artículo 0121 — Plugin Gradle para controlar dos instancias de Ollama</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Artículo 0122 — Ratio Eficacia 27× a 54×</a></p> </li> </ul> </div> <div class="sect2"> <h3 id="_fuentes_de_las_tarifas">Fuentes de las Tarifas</h3> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/pricing">Ollama Cloud — Tarifas Pro \$20/mes</a></p> </li> <li> <p><a href="https://api-docs.deepseek.com/quick_start/pricing">DeepSeek API — Tarifas oficiales V4 Pro</a></p> </li> <li> <p><a href="https://platform.kimi.com/docs/pricing/chat-k26">Kimi Moonshot — Tarifas K2.6</a></p> </li> <li> <p><a href="https://huggingface.co/inference/models">HuggingFace Inference Providers — Tarifas por provider</a></p> </li> <li> <p><a href="https://www.anthropic.com/pricing">Anthropic — Precios Claude API</a></p> </li> <li> <p><a href="https://openai.com/api/pricing/">OpenAI — Tarifas GPT API</a></p> </li> <li> <p><a href="https://together.ai/pricing">Together AI — Tarifas de inferencia</a></p> </li> <li> <p><a href="https://groq.com/pricing">Groq — Tarifas API</a></p> </li> <li> <p><a href="https://deepinfra.com/pricing">DeepInfra — Precios GPU y modelos</a></p> </li> <li> <p><a href="https://help.aliyun.com/zh/model-studio/text-generation-model/">Alibaba Bailian — Modelos disponibles</a></p> </li> <li> <p><a href="https://github.com/anomalyco/opencode">OpenCode — CLI open source en GitHub</a></p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html Thu, 14 May 2026 00:00:00 +0000 blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_tres_arquitecturas_que_me_hicieron_perder_el_tiempo">El Problema: Tres Arquitecturas Que Me Hicieron Perder el Tiempo</a> <ul class="sectlevel2"> <li><a href="#_opción_1_el_plugin_aislado_sin_dogfooding">Opción 1: El Plugin aislado (sin dogfooding)</a></li> <li><a href="#_opción_2_el_monorepo_clásico_includeplugin">Opción 2: El Monorepo Clásico (<code>include(":plugin")</code>)</a></li> <li><a href="#_opción_3_el_build_compuesto_includebuild">Opción 3 : el Build compuesto (<code>includeBuild()</code>)</a></li> </ul> </li> <li><a href="#_la_solución_dos_builds_independientes_una_raíz_consumidora">La Solución: Dos Builds independientes, Una raíz consumidora</a> <ul class="sectlevel2"> <li><a href="#_el_flujo_de_trabajo">El flujo de trabajo</a></li> <li><a href="#_el_workflow_concreto">El Workflow Concreto</a></li> </ul> </li> <li><a href="#_por_qué_esta_arquitectura_me_ha_conquistado">¿Por qué esta arquitectura me ha conquistado?</a> <ul class="sectlevel2"> <li><a href="#_dogfooding_nativo_retroalimentación_instantánea">Dogfooding nativo, retroalimentación instantánea</a></li> <li><a href="#_2_clonación_zero_config">2. Clonación Zero-Config</a></li> <li><a href="#_3_builds_aislados_ci_independientes">3. Builds aislados, CI independientes</a></li> </ul> </li> <li><a href="#_la_anatomía_del_subdirectorio_name_plugin">La anatomía del subdirectorio `{name}-plugin/</a> <ul class="sectlevel2"> <li><a href="#_el_catálogo_de_versiones_dos_archivos_distintos">El Catálogo de Versiones: Dos Archivos Distintos</a></li> </ul> </li> <li><a href="#_lo_que_no_se_hace">Lo Que No Se Hace</a></li> <li><a href="#_comparación_las_tres_arquitecturas_frente_al_dogfooding">Comparación : Las Tres Arquitecturas Frente al Dogfooding</a></li> <li><a href="#_el_contrato_dag_un_build_raíz_nunca_proviene_desde_un_subdirectorio">El Contrato DAG : Un build raíz nunca proviene desde un subdirectorio</a></li> <li><a href="#_conclusión_la_duplicación_aparente_que_ahorra_tiempo">Conclusión : La duplicación aparente que ahorra tiempo</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 11 minutes</div> <p>Estás clonando un repositorio de plugins de Gradle. Abres una terminal. ¿Qué escribes? ¿Entonces?<code>./gradlew tasks</code>, claro. ¿En qué carpeta? ¿La raíz? ¿El submódulo? ¿Hay que leer primero un README para saber cómo construir? Si dudan ni siquiera solo un segundo, la arquitectura del proyecto está rota</p> </div> <div class="paragraph"> <p>Así es como resolví este problema una vez por todas — y por qué esto pattern es hoy la firma de todos mis plugins Gradle en`foundry/public/`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_tres_arquitecturas_que_me_hicieron_perder_el_tiempo">El Problema: Tres Arquitecturas Que Me Hicieron Perder el Tiempo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de converger hacia el patrón actual, he vacilado entre tres enfoques clásicos para organizar un plugin Gradle. Cada uno tenía un defecto imperdonable.</p> </div> <div class="sect2"> <h3 id="_opción_1_el_plugin_aislado_sin_dogfooding">Opción 1: El Plugin aislado (sin dogfooding)</h3> <div class="paragraph"> <p>El proyecto solo contiene el plugin. No hay ejemplo de consumo. No proyecto que lo ejerce. Para probarlo, hay que crear un proyecto externo, y referenciar el plugin mediante`mavenLocal`o un build compuesto, y solo allí verificar que funciona.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone mon-plugin $ cd mon-plugin $ ./gradlew build # le plugin compile $ # ... et maintenant ? comment je l'essaie ?</code></pre> </div> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Un plugin Gradle sin ejemplo de consumo, es una biblioteca sin pruebas de integración. Nunca sabes si la última modificación ha roto la experiencia del usuario.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_opción_2_el_monorepo_clásico_includeplugin">Opción 2: El Monorepo Clásico (<code>include(":plugin")</code>)</h3> <div class="paragraph"> <p>Gradle`init`genera`settings.gradle.kts`con`include("plugin")`. El root y el submódulo comparten el mismo daemon, las mismas configuraciones, los mismos catálogos. práctico, pero acoplado.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts → include("plugin") ├── build.gradle.kts → plugins { id("mon-plugin") } ├── plugin/ │ └── build.gradle.kts → java-gradle-plugin └── gradle/ └── libs.versions.toml</code></pre> </div> </div> <div class="paragraph"> <p>Lo que se atasca:</p> </div> <div class="ulist"> <ul> <li> <p>La raíz<strong>debe</strong>tener la misma versión de Gradle que el submódulo.</p> </li> <li> <p>`libs.versions.toml`es compartido — versión catalogs comunes, dependencias</p> </li> </ul> </div> <div class="paragraph"> <p>que huyen de un módulo a otro</p> </div> <div class="ulist"> <ul> <li> <p>Imposible compilar el plugin independientemente del root.</p> </li> <li> <p>La CI debe compilar los dos módulos, aunque solo el plug‑in haya cambiado.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_opción_3_el_build_compuesto_includebuild">Opción 3 : el Build compuesto (<code>includeBuild()</code>)</h3> <div class="paragraph"> <p>Separamos los dos en builds Gradle distintos y los relacionamos vía <code>includeBuild("mon-plugin")`en`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>Ya está mejor. La compilación del plugin está aislada. Pero el consumidor debe explícitamente referenciar la compilación externa — y la salida de `./gradlew tasks`en la raíz depende de la buena configuración del compuesto. El clonaje no es zero-config: hay que saber que el plugin está en una carpeta aparte, que el root lo referencia, etc.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">. ├── settings.gradle.kts → includeBuild("plugin-build/") ├── build.gradle.kts → plugins { id("mon-plugin") } └── plugin-build/ ├── settings.gradle.kts └── build.gradle.kts</code></pre> </div> </div> <div class="paragraph"> <p>Buscaba algo mejor. Mucho mejor.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_dos_builds_independientes_una_raíz_consumidora">La Solución: Dos Builds independientes, Una raíz consumidora</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aquí está el patrón que acabé adoptando :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts ← racine consommateur ├── build.gradle.kts ← 3 lignes : apply plugin + dogfood ├── gradle/ │ └── libs.versions.toml ← catalogue du consommateur ├── {name}-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── settings.gradle.kts ← rootProject.name = "{name}-plugin" │ ├── build.gradle.kts ← java-gradle-plugin, signing, publish │ ├── gradle/ │ │ ├── libs.versions.toml ← catalogue du plugin │ │ └── wrapper/ │ ├── src/ ← sources du plugin │ ├── .agents/ ← gouvernance agent │ └── *.adoc ← AGENT, PROMPT_REPRISE, snapshot, etc. └── site.yml / slides-context.yml / ... ← configs dogfood</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>La clave:`{name}-plugin/`es un proyecto Gradle <strong>completo y autónomo</strong>. Tiene su propio envoltorio, su propio ajustes, su propio catálogo de versiones. Se clona, se construye, se prueba, y se publica sin necesidad de root estar al tanto de su existencia.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>El root, él, solo hace <strong>una</strong> cosa: aplicar el plugin.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { alias(libs.plugins.bakery) } repositories { mavenLocal() mavenCentral() } bakery { configPath = file("site.yml").absolutePath }</code></pre> </div> </div> <div class="paragraph"> <p>Tres líneas en el caso de`bakery-gradle`. Nada más. Cero`include()<code>, cero`includeBuild()</code>, cero subproyecto. Un build Gradle clásico que aplica un plugin como cualquier ¿qué consumidor lo haría.</p> </div> <div class="sect2"> <h3 id="_el_flujo_de_trabajo">El flujo de trabajo</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 32) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 left to right direction package "RAÍZ (Consumidor)" #CCFFCC { usecase "Clone el repositorio" as Clone usecase "./gradlew tareas" as Tasks usecase "./gradlew bake" as Dogfood note bottom of Dogfood Exerce le plugin Feedback immédiat Zéro config end note } package "{name}-plugin/ (Compilación Independiente)" #CCE5FF { usecase "./gradlew build" as BuildPlugin usecase "./gradlew publishToMavenLocal" as MavenLocal usecase "./gradlew test" as TestPlugin note bottom of BuildPlugin Cycle de vie isolé Tests unitaires + Cucumber CI dédiée possible end note } Clone -down-> Tasks Tasks -down-> Dogfood Dogfood ..> MavenLocal : "depende del plugin publicado localmente" ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 left to right direction package "RAÍZ (Consumidor)" #CCFFCC { usecase "Clone el repositorio" as Clone usecase "./gradlew tareas" as Tasks usecase "./gradlew bake" as Dogfood note bottom of Dogfood Exerce le plugin Feedback immédiat Zéro config end note } package "{name}-plugin/ (Compilación Independiente)" #CCE5FF { usecase "./gradlew build" as BuildPlugin usecase "./gradlew publishToMavenLocal" as MavenLocal usecase "./gradlew test" as TestPlugin note bottom of BuildPlugin Cycle de vie isolé Tests unitaires + Cucumber CI dédiée possible end note } Clone -down-> Tasks Tasks -down-> Dogfood Dogfood ..> MavenLocal : "depende del plugin publicado localmente" BuildPlugin -up-> MavenLocal TestPlugin -up-> BuildPlugin @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_el_workflow_concreto">El Workflow Concreto</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># 1. Builder le plugin $ cd codebase-plugin $ ./gradlew publishToMavenLocal # 2. L'exercer depuis la racine $ cd .. $ ./gradlew indexCodebase queryCodebase snapshot # La boucle est fermée. Le plugin est testé dans des conditions # réelles de consommation, par le projet même qui l'héberge.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_esta_arquitectura_me_ha_conquistado">¿Por qué esta arquitectura me ha conquistado?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tres beneficios que, combinados, valen el costo de la «duplicación» :</p> </div> <div class="sect2"> <h3 id="_dogfooding_nativo_retroalimentación_instantánea">Dogfooding nativo, retroalimentación instantánea</h3> <div class="paragraph"> <p>La mejor prueba de un plugin Gradle es usarlo. No es una prueba unitaria simulada. No es un`GradleRunner`con un proyecto de prueba. Un <strong>verdadero</strong> build que aplica el plugin sobre archivos reales.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone bakery-gradle $ cd bakery-gradle $ ./gradlew bake # ← le plugin est exercé immédiatement</code></pre> </div> </div> <div class="paragraph"> <p>Si el plugin está roto, el build raíz lo dice. No es necesario ir buscar un proyecto de prueba externo. El dogfooding es la <strong>primera</strong> tarea que lanza un nuevo contribuidor. Es la prueba de humo definitiva.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La regla es simple: si la raíz compila y`./gradlew tasks` Muestra tus tareas del plugin, el plugin es funcional. Sin sorpresas en producción</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_clonación_zero_config">2. Clonación Zero-Config</h3> <div class="paragraph"> <p>Un `git clone && ./gradlew tasks`y el recién llegado ve todo caminar sin configurar nada. El`build.gradle.kts`raíz es la documentación viva de uso del plugin. El`site.yml`al lado muestra la configuración esperada.</p> </div> <div class="paragraph"> <p>Compárese con la alternativa: un README de tres párrafos que explica cómo crear el plugin y cómo crear el proyecto de test. Un nuevo colaborador lee el README en diagonal, se equivoca, abre un problema — aunque la información podría ser <strong>ejecutable</strong></p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>La documentación más robusta no es la que se lee. Es esa que uno<strong>ejecuta</strong>. El build raíz es la documentación ejecutable del plugin.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3_builds_aislados_ci_independientes">3. Builds aislados, CI independientes</h3> <div class="paragraph"> <p>El plugin tiene su propio wrapper Gradle, su propio ciclo de vida, sus propias pruebas. Puede:</p> </div> <div class="ulist"> <ul> <li> <p>Actualizar Gradle en el plugin sin tocar la raíz</p> </li> <li> <p>Añadir una dependencia en el plugin sin que se filtre en el root</p> </li> <li> <p>Romper el plugin sin afectar al build raíz (mientras usted no</p> </li> </ul> </div> <div class="paragraph"> <p>No publiquéis la versión rota).</p> </div> <div class="ulist"> <ul> <li> <p>Tener una CI que build/test el plugin, y otra que ejerce el</p> </li> </ul> </div> <div class="paragraph"> <p>root — independientemente</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">.github/workflows/ ├── test-plugin.yml → codebase-plugin/.gradlew build ├── test-root.yml → .gradlew tasks (vérifie que le plugin est consommable) └── publish.yml → codebase-plugin/.gradlew publish</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_anatomía_del_subdirectorio_name_plugin">La anatomía del subdirectorio `{name}-plugin/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Observemos de más cerca lo que vive en la carpeta del plugin:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">codebase-plugin/ ├── gradlew ← wrapper indépendant ├── settings.gradle.kts ← @Suppress("UnstableApiUsage") │ + foobar-resolver-convention ├── build.gradle.kts ← java-gradle-plugin + signing + publish ├── gradle/ │ ├── libs.versions.toml ← catalogue complet (langchain4j, pgvector...) │ └── wrapper/ ├── buildSrc/ ← classes utilitaires buildSrc │ ├── build.gradle.kts │ └── src/main/kotlin/ │ ├── codebase/ ← CodebaseYmlAnonymizer, CodebaseConfiguration │ ├── benchmark/ ← BenchmarkConfig, BenchmarkProtocol │ ├── readme/ ← ReadmeYmlAnonymizer │ ├── site/ ← SiteYmlAnonymizer │ ├── slider/ ← SliderYmlAnonymizer │ └── snapshot/ ← SnapshotManager ├── src/ │ ├── main/kotlin/codebase/ │ │ ├── CodebasePlugin.kt ← class Plugin<Project> │ │ ├── rag/ ← pgvector, embedding, anonymization... │ │ ├── benchmark/ ← BenchmarkRunner, export, comparison... │ │ └── walker/ ← WorkspaceWalker │ └── test/ │ ├── kotlin/codebase/scenarios/ ← steps Cucumber │ ├── features/ ← .feature files │ └── resources/datasets/ ← fixtures .adoc, .yml, .json ├── .agents/ ← gouvernance agent (INDEX, SESSIONS, etc.) ├── AGENT.adoc ← règles agent ├── PROMPT_REPRISE.adoc ← mission session ├── BACKLOG.adoc ← backlog produit ├── snapshot.adoc ← snapshot auto-généré du projet └── embeds.yml ← config RAG embeds</code></pre> </div> </div> <div class="paragraph"> <p>Todo está ahí. No hay dispersión entre la raíz y el subdirectorio. El desarrollador que trabaja en el plugin nunca necesita salir`codebase-plugin/`. El desarrollador que usa el plugin solo mira la raíz — y el`build.gradle.kts`de 3 líneas le dice todo lo que necesita saber</p> </div> <div class="sect2"> <h3 id="_el_catálogo_de_versiones_dos_archivos_distintos">El Catálogo de Versiones: Dos Archivos Distintos</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle/libs.versions.toml</code>(raíz)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{name}-plugin/gradle/libs.versions.toml</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Número de dependencias</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2-3 (plugin + readme opcionalmente)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">más de 30 (langchain4j, pgvector, cucumber…​)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">rol</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consumir el plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Construye el plugin</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">¿Quién lo lee?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El usuario del plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El desarrollador del plugin</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El root tiene un catálogo voluntariamente minimal. El plugin tiene un catálogo completo. La confusión es imposible: cada build tiene su propio scope de dependencias</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Si ya has pasado una hora depurando una colisión de dependencias entre tu plugin y tu proyecto de prueba, comprendes el valor de esta separación. Los catálogos independientes eliminan este problema por construcción.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_no_se_hace">Lo Que No Se Hace</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este patrón no es mágico. Impone una restricción que yo me inflige de buena gana :</p> </div> <div class="paragraph"> <p><strong>root no construye el plugin.</strong> Debes`publishToMavenLocal` ou desplegar en un repositorio antes de que root pueda consumirlo.</p> </div> <div class="paragraph"> <p>Es un costo mínimo, y es la <strong>buena</strong> restricción. El root consume el plugin como un cliente externo — vía Maven. Exactamente como lo haría un proyecto de terceros. Si el plugin no es publicable, el root te lo dice de inmediato.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># La seule "friction" du pattern $ cd codebase-plugin && ./gradlew publishToMavenLocal && cd .. $ ./gradlew tasks --group=codebase</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparación_las_tres_arquitecturas_frente_al_dogfooding">Comparación : Las Tres Arquitecturas Frente al Dogfooding</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plugin aislado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Monorepo`include()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Compuesto`includeBuild()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Raíz + plugin independiente</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`git clone && gradlew tasks`da las tareas del plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"></think> (The assistant returns no text, as there is no source content to translate.)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Build plugin independiente del root</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Catálogo de versiones separadas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No`include()` ni <code>includeBuild()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"></think> </think></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dogfood nativo sin configuración</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">CI plugin independiente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">El root es un ejemplo de consumo real</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La columna de la derecha marca todas las casillas. Es por eso que yo no Volveré más atrás</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_contrato_dag_un_build_raíz_nunca_proviene_desde_un_subdirectorio">El Contrato DAG : Un build raíz nunca proviene desde un subdirectorio</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta arquitectura se integra naturalmente en el DAG N0→N3 de mi workspace. El patrón es : <strong>el plugin N2 es el hub de sus propias dependencias, la raíz N3 es un terminal que aplica los hubs</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/contrat-dag-architecture.svg" alt="contrat dag architecture" width="1826" height="5508"> </div> </div> <div class="paragraph"> <p>Le <code>codebase-gradle/build.gradle.kts`hace 6 líneas. No`src/</code>, no`buildSrc/<code>, no`gradle/rag-bench.gradle.kts</code>. justo <code>plugins { alias(libs.plugins.codebase) }`y los repositorios. Toda la complejidad vive en`codebase-plugin/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_la_duplicación_aparente_que_ahorra_tiempo">Conclusión : La duplicación aparente que ahorra tiempo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando muestro esta estructura a alguien, la primera reacción es a menudo : « Pero tienes dos`gradlew`, dos`settings.gradle.kts`, dos`libs.versions.toml`— ¡Es duplicado!</p> </div> <div class="paragraph"> <p>Sí. Y no.</p> </div> <div class="paragraph"> <p>La «duplicación», es reproducir la misma información en dos lugares. Aquí, son dos archivos <strong>distintos</strong> que sirven para dos usos <strong>distintos</strong> : el catálogo del plugin (30+ dependencias para builder) y el catálogo de la raíz (2-3 dependencias para consumir). El wrapper del plugin (versión bloqueada para el desarrollo) y el envoltorio de la raíz (versión potencialmente diferente, para el ejercicio del plugin).</p> </div> <div class="paragraph"> <p>No es duplicación. Es <strong>separación des responsabilidades</strong> aplicada al sistema de compilación. Cada compilación. Hace una cosa, y solo una. La raíz consume. El plugin se compila.</p> </div> <div class="paragraph"> <p>¿El costo? Un pedido`publishToMavenLocal`entre el build del plugin y la compilación de la raíz. ¿El beneficio? Una claridad arquitectónica que elimina horas de depuración aguas abajo.</p> </div> <div class="paragraph"> <p>Desde que he desplegado este patrón sobre`bakery-gradle`, <code>plantuml-gradle</code>, <code>codebase-gradle</code>, y los otros plugins de`foundry/public/<code>, no tengo nunca más dudado al abrir una terminal en uno de mis repositorios. El primer reflejo—</code>./gradlew tasks`— camina siempre, da siempre las buenas tareas, y me dice al instante si todo está sano.</p> </div> <div class="paragraph"> <p>Así es la buena arquitectura. No se lee en un README. Se experimenta en una terminal, en menos de diez segundos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Artículo 0105 — Integrar Graphify en un flujo de trabajo Gradle</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — La Granularización OSS/CSS</a></p> </li> <li> <p><a href="0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html">Artículo 0123 — El Knowledge Graph como motor de recomendación</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html Tue, 12 May 2026 00:00:00 +0000 blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_martes_12_de_mayo_1730">La Escena : Martes 12 de mayo, 17:30</a></li> <li><a href="#_el_diagnóstico_tres_tipos_de_relaciones_que_ninguna_plantilla_ve">El diagnóstico: Tres tipos de relaciones que ninguna plantilla ve</a></li> <li><a href="#_la_solución_un_pipeline_gradle_no_una_llamada_llm_en_caliente">La Solución: Un Pipeline Gradle, No una Llamada LLM en Caliente</a> <ul class="sectlevel2"> <li><a href="#_la_arquitectura_bakery_importa_graphify_no_engine">La Arquitectura: Bakery importa Graphify, No Engine</a></li> <li><a href="#_el_pipeline_escaneo_grafo_plantilla">El pipeline: Escaneo → Grafo → Plantilla</a></li> <li><a href="#_respaldo_cronológico">Respaldo cronológico</a></li> </ul> </li> <li><a href="#_la_ontología_emergente_cuando_los_artículos_se_reagrupan_sin_conocerse">La ontología emergente: Cuando los artículos se reagrupan sin conocerse</a></li> <li><a href="#_el_contrato_dag_quién_importa_quién">El Contrato DAG: Quién Importa Quién</a></li> <li><a href="#_lo_que_se_gana_y_lo_que_no_se_gana">Lo que se gana (y lo que no se gana)</a></li> <li><a href="#_perspectivas_el_blog_como_knowledge_graph_público">Perspectivas : El Blog Como Knowledge Graph público</a></li> <li><a href="#_conclusion_el_sistema_de_archivos_sabe_lo_que_la_plantilla_ignora">Conclusion : El Sistema de Archivos Sabe Lo Que la Plantilla Ignora</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 14 minutes</div> <p>Está leyendo un artículo sobre la integración de pgvector con LangChain4j. Al final de la página, JBake le sugiere « Artículos relacionados ». Usted hace clic. Este es un artículo sobre…​ la configuración de Kitty Terminal. ¿Cuál es el único punto en común entre los dos? Han sido publicados hace menos de quince días de diferencia. No es una recomendación. Es un calendario disfrazado de editorial.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_martes_12_de_mayo_1730">La Escena : Martes 12 de mayo, 17:30</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estoy releyendo uno de mis artículos — <a href="0106_knowledge_graph_outil_compréhension_codebase_post.html">ese sobre el Knowledge Graph como herramienta de comprensión de la base de código</a> El contenido es denso : nodos, aristas, comunidades, PlantUML, incorporación. Un artículo técnica de 15 minutos de lectura que moviliza`graphify-gradle`, <code>plantuml-gradle</code>, y los conceptos de topología de grafos.</p> </div> <div class="paragraph"> <p>Al pie de página, los « Artículos relacionados » me sugieren:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Un artículo sobre Firebase Contact Form (0113)</p> </li> <li> <p>Un artículo sobre el mecanismo Eager/Lazy (0108)</p> </li> <li> <p>Un artículo sobre la migración Gradle script → plugin (0102)</p> </li> <li> <p>Un artículo sobre la acumulación de suscripciones Ollama Pro (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>Tres de estos cuatro artículos no tienen <strong>ninguna</strong> relación con el Knowledge Graph. Están allí porque son los últimos publicados — vecindad temporal, no vecindario semántico.</p> </div> <div class="paragraph"> <p>Estoy mirando el template`post.thyme`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes (liens internes SEO) --> <th:block th:each="post,postStat : ${published_posts}"> <th:block th:if="${!post.uri.equals(content.uri) and postStat.index lt 4}"> ... </th:block> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>`published_posts`es una lista cronológica.`postStat.index lt 4`toma los los cuatro primeros que no son el post actual. Eso es todo. Ninguna lógica de similitud. Ninguna noción de contenido. Sólo un bucle`for`disfrazada de recomendación</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>No es un error de JBake. Es el comportamiento predeterminado de todo generador de sitio estático: la lista de posts es plana y ordenada por fecha. La plantilla hace lo que puede con lo que tiene.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Pero eso no es una razón para aceptarlo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_diagnóstico_tres_tipos_de_relaciones_que_ninguna_plantilla_ve">El diagnóstico: Tres tipos de relaciones que ninguna plantilla ve</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mi corpus de artículos — 23 publicaciones en 4 meses — tiene una estructura rica que la plantilla cronológica sobrescribe completamente :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Referencias explícitas</strong> : utilizo`xref:`masivamente en mis artículos.</p> </li> </ol> </div> <div class="paragraph"> <p>El artículo 0122 referencia 0106 (knowledge graph) y 0116 (compartimentado epistemológico). Estos enlaces son de <strong>hard linking</strong> editorial — tengo ha decidido deliberadamente conectar estos conceptos.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Etiquetas compartidas</strong> : cada artículo tiene algunos`:jbake-tags:`. El artículo sobre</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) a`gradle, graphify, plantuml, knowledge-graph`. El artículo sobre el Knowledge Graph (0106) tiene <code>knowledge-graph, graphify, plantuml</code>. Tres etiquetas en común de siete — 43% de superposición.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Entidades nombradas co-ocurrentes</strong> : « pgvector », « RAG », « embedding</p> </li> </ol> </div> <div class="paragraph"> <p>aparecen juntos en cuatro artículos diferentes. « LangChain4j », Ollama », « plugin Gradle » en seis otros. No son etiquetas declarados — son <strong>patrones emergentes</strong> del corpus que solo un NLP puede detectar.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/trois-couches-relation-articles.svg" alt="trois couches relation articles" width="1761" height="5492"> </div> </div> <div class="paragraph"> <p>Hoy, mi sitio no utiliza <strong>ninguna</strong> de estas tres capas. Utiliza la capa cero: el orden de inserción en una lista Java.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_un_pipeline_gradle_no_una_llamada_llm_en_caliente">La Solución: Un Pipeline Gradle, No una Llamada LLM en Caliente</h2> <div class="sectionbody"> <div class="paragraph"> <p>La primera tentación sería llamar a un LLM en el momento del bake : « Para este artículo, encuentre los tres artículos más similares en el corpus. No lo hace.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Una llamada LLM a cada`./gradlew bake`cuesta tiempo, dinero y Introduce no determinismo en tu build. La respuesta del LLM puede cambiar entre dos builds sin que el contenido haya cambiado. Tu CI se vuelve No reproducible, sus pruebas se vuelven inestables.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>La solución es determinista: un pipeline Gradle que precalcula el grafo de similitud y lo almacena en`graph.json`. La plantilla lee el resultado — nunca desencadena un cálculo.</p> </div> <div class="sect2"> <h3 id="_la_arquitectura_bakery_importa_graphify_no_engine">La Arquitectura: Bakery importa Graphify, No Engine</h3> <div class="paragraph"> <p>Es el punto de arquitectura más importante. La tentación sería de cablear la colaboración en`engine/build.gradle.kts`: motor aplica graphify para el scan, bakery para el bake, y engine hace el puente entre los dos</p> </div> <div class="paragraph"> <p>Es un anti-patrón. Engine es un <strong>terminal consumidor</strong> — lo aplica de los plugins, no implementa lógica de negocio. La regla es : <strong>la carga de la prueba está sobre el plugin propietario.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/bakery-import-graphify.svg" alt="bakery import graphify" width="1787" height="5700"> </div> <div class="title">Figure 1. Arquitectura correcta — Bakery importa Graphify</div> </div> <div class="paragraph"> <p>El contrato DAG se cumple: bakery (N2) importa graphify (N0), N2 > N0, ninguna violación. Engine (N3) importa bakery (N2), N3 > N2, OK.</p> </div> <div class="paragraph"> <p>Engine no tiene <strong>ninguna</strong> línea de código que referencia`graph.json`, <code>relatedPosts</code>, o cualquier otra noción de similitud. Aplica bakery, punto. La colaboración es interna a bakery</p> </div> </div> <div class="sect2"> <h3 id="_el_pipeline_escaneo_grafo_plantilla">El pipeline: Escaneo → Grafo → Plantilla</h3> <div class="paragraph"> <p>Aquí está el pipeline completo en tres pasos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Scan</strong> (graphify):`graphify-plugin`escanea el workspace. En su</p> </li> </ol> </div> <div class="paragraph"> <p>forma actual, ya detecta los`xref:`entre`.adoc`y los mostrado en`graph.json`como edges de tipo`reference`.<br> Lo enriquecemos para el contenido editorial: * Analiza los metadatos JBake`:jbake-tags:`, <code>:jbake-description:</code>) de cada`.adoc`del blog * Calcula las co-ocurrencias de tags → edges`tag_cooccurrence`con peso * Extrae las entidades nombradas de las descripciones mediante TF-IDF → edges`entity_overlap` * Injecta una sección`blog_articles`en el`graph.json`existente<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Extrait de l'enrichissement graphify pour le blog fun enrichBlogSection(graphJson: File, blogDir: File): GraphJson { val articles = blogDir.listFiles { f -> f.extension == "adoc" } .map { parseJbakeMetadata(it) } val nodes = articles.map { ArticleNode(it.slug, it.title, it.tags) } val edges = mutableListOf<GraphEdge>() // Couche 1 : xref (déjà fait par scanWorkspace) // Couche 2 : co-occurrences de tags for (a in articles) { for (b in articles) { if (a.slug == b.slug) continue val common = a.tags.intersect(b.tags) if (common.isNotEmpty()) { edges.add(GraphEdge( source = a.slug, target = b.slug, type = "tag_cooccurrence", weight = common.size.toDouble() / (a.tags.size + b.tags.size) )) } } } return graphJson.copy( blogArticles = BlogSection(nodes, edges) ) }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Bake</strong> (panadería) : en el momento de`./gradlew bake`, `BakeryPlugin`cama</p> </li> </ol> </div> <div class="paragraph"> <p>`graph.json`y resuelve los artículos relacionados para cada publicación.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BakeryPlugin — résolution des articles connexes fun resolveRelatedPosts( currentSlug: String, graph: GraphJson, maxResults: Int = 4 ): List<RelatedPost> { val edges = graph.blogArticles.edges .filter { it.source == currentSlug || it.target == currentSlug } return edges .sortedByDescending { it.weight } .take(maxResults) .map { edge -> val relatedSlug = if (edge.source == currentSlug) edge.target else edge.source graph.blogArticles.nodes.first { it.slug == relatedSlug } } }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>(Note: The assistant must output nothing as there is no French text to translate.)<code>post.thyme</code>) : el modelo JBake recibe un mapa</p> </li> </ol> </div> <div class="paragraph"> <p>estructurada en lugar de una lista cronológica plana<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes basés sur le Knowledge Graph --> <th:block th:if="${relatedPosts != null and !relatedPosts.empty}"> <section class="mt-5 pt-4 border-top"> <h2 class="h4 mb-3">Articles connexes</h2> <th:block th:each="related : ${relatedPosts}"> <div class="mb-2"> <a th:href="${content.rootpath} + ${related.uri}" th:text="${related.title}" class="fw-semibold"></a> <br/> <small class="text-muted"> <th:block th:each="reason,iterStat : ${related.reasons}"> <span class="badge bg-light text-dark" th:text="${reason}"></span> </th:block> </small> </div> </th:block> </section> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>La plantilla es la misma — no sabe <strong>de dónde</strong> vienen los datos. Sólo el contrato entre bakery y JBake ha cambiado :`published_posts`(lista cronológico) se vuelve`relatedPosts`(mapa ponderado por el grafo).</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>El distintivo « razón » (ej:`xref 0122`, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) explique al lector <strong>por qué</strong> este artículo está relacionado. No es solo de transparencia — es pedagogía sobre la topología de su propio contenido.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_respaldo_cronológico">Respaldo cronológico</h3> <div class="paragraph"> <p>Si `graph.json`está ausente(compilación local sin escaneo previo, primero) despliegue, CI que aún no ha integrado el escaneo graphify), la plantilla debe degradarse con elegancia:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveRelatedPosts(currentSlug: String, graph: GraphJson?): List<RelatedPost> { if (graph != null && graph.blogArticles != null) { return resolveFromGraph(currentSlug, graph) } // Fallback chronologique — même comportement qu'aujourd'hui logger.warn("[bakery] graph.json absent — fallback chronologique") return resolveFromChronology(currentSlug) }</code></pre> </div> </div> <div class="paragraph"> <p>El comportamiento predeterminado es idéntico al comportamiento actual. El motor de recomendación es una <strong>mejora progresiva</strong> — no un cambio disruptivo</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_ontología_emergente_cuando_los_artículos_se_reagrupan_sin_conocerse">La ontología emergente: Cuando los artículos se reagrupan sin conocerse</h2> <div class="sectionbody"> <div class="paragraph"> <p>La capa más interesante es la tercera: la ontología emergente. Artículos que no se citan, que no tienen los mismos tags, pero que <strong>hablan de lo mismo</strong> sin saberlo.</p> </div> <div class="paragraph"> <p>Tomemos un ejemplo concreto. Tres artículos de mi corpus :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — Benchmark DGX Spark vs Cloud Suscripción LLM</p> </li> <li> <p>0121 — Plugin Gradle Gestionar Dos Instancias Ollama Pro</p> </li> <li> <p>0122 — Ratio de Eficiencia 27x 45x Flota Expertos IA</p> </li> </ol> </div> <div class="paragraph"> <p>Estos tres artículos no tienen <strong>ninguno</strong> xref entre ellos. Sus etiquetas no se coinciden únicamente en un 20% (« ollama », « llm » comunes). Pero un NLP ligero en las descripciones revela un clúster obvio: « costo », « suscripción », nube », « GPU », « clave API », « Ollama Pro », « eficiencia », « ratio</p> </div> <div class="paragraph"> <p>Forman un cluster ontológico : <strong>la economía del LLM self-hosted vs cloud</strong>. Este clúster no está declarado en ninguna parte. Surge del corpus.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cluster-ontologique-exemple.svg" alt="cluster ontologique exemple" width="1746" height="5456"> </div> </div> <div class="paragraph"> <p>Este clúster ontológico se convierte en una arista compuesta en`graph.json`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "source": "0119-benchmark-dgx-spark", "target": "cluster:economie-llm", "type": "entity_cluster", "weight": 0.73, "metadata": { "clusterLabel": "Économie LLM Self-Hosted vs Cloud", "commonEntities": ["coût", "GPU", "abonnement", "Ollama Pro", "ratio"], "articlesInCluster": [ "0119-benchmark-dgx-spark", "0121-ollama-pro-deux-instances", "0122-ratio-efficacite-flotte-experts" ] } }</code></pre> </div> </div> <div class="paragraph"> <p>El NLP es voluntariamente ligero — TF-IDF + cosine similarity sobre los descripciones. No se necesita BERT, no se necesita un modelo de lenguaje. El corpus tiene 23 artículos, la matriz de similitud cabe en un archivo JSON de 50 KB.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La potencia del NLP no viene de la sofisticación del algoritmo pero del <strong>tamaño del corpus</strong> y de la <strong>calidad de las descripciones</strong>. `:jbake-description:`bien escrita de 150 caracteres contiene más de señal para TF-IDF que un artículo completo de 3000 palabras</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_contrato_dag_quién_importa_quién">El Contrato DAG: Quién Importa Quién</h2> <div class="sectionbody"> <div class="paragraph"> <p>Es el punto donde la disciplina arquitectónica paga. El DAG N0→N3 definido en`engine/build.gradle.kts`da una regla simple : ningún proyecto importa un proyecto de nivel superior</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 27.2728%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Plugin consumidor</th> <th class="tableblock halign-left valign-top">Plugin importado</th> <th class="tableblock halign-left valign-top">Nivel consumidor</th> <th class="tableblock halign-left valign-top">Nivel importado</th> <th class="tableblock halign-left valign-top">¿Válido?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N2 > N0 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">motor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N3 > N2 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">motor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Técnica OK, <strong>conceptualmente falso</strong> — la colaboración es interna de bakery</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Engine aplica panadería. Panadería aplica graphify. Eso es todo. Si algún día Quiero agregar el codebase del vector store (N1) para investigación semántica cross-corpus, la panadería también lo importa. el motor no cambia.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>El patrón es: <strong>el plugin N2 es el hub de sus propias dependencias</strong> Engine N3 no es un hub — es un terminal que aplica hubs.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_se_gana_y_lo_que_no_se_gana">Lo que se gana (y lo que no se gana)</h2> <div class="sectionbody"> <div class="paragraph"> <p>El beneficio principal es editorial, no técnica:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Antes</th> <th class="tableblock halign-left valign-top">Después</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Artículos relacionados = 4 últimos posts</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Artículos relacionados = top 4 por peso en el Knowledge Graph</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Lector lee RAG → recomendación Kitty Terminal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lector lee del RAG → recomendación pgvector, chunking, almacenén de vectores</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero transparencia sobre el por qué</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Insignia`xref 0122`, <code>tag:gradle</code>, `cluster:rag`visible</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake estándar, cero esfuerzo, cero valor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pipeline Gradle determinista, reproducible, testable</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Ninguna curva de aprendizaje para el lector</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El lector descubre la <strong>topologie</strong> de mi contenido</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Lo que <strong>no</strong> se gana :</p> </div> <div class="ulist"> <ul> <li> <p>No es un motor de recomendación « verdadero » (no colaborativo</p> </li> </ul> </div> <div class="paragraph"> <p>filtrado, sin pruebas A/B, sin bucle de retroalimentación)</p> </div> <div class="ulist"> <ul> <li> <p>La calidad depende de la riqueza de los metadatos de JBake — si sus</p> </li> </ul> </div> <div class="paragraph"> <p>las descripciones están vacías, TF-IDF no ve nada</p> </div> <div class="ulist"> <ul> <li> <p>El NLP está offline — los nuevos artículos no se agrupan qu’au</p> </li> </ul> </div> <div class="paragraph"> <p>Próximo escaneo (está bien: el build sigue siendo determinista)</p> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_el_blog_como_knowledge_graph_público">Perspectivas : El Blog Como Knowledge Graph público</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta funcionalidad abre una perspectiva más amplia: y si`cheroliv.com` ¿se convertía él mismo en un <strong>knowledge graph navigable</strong> ?</p> </div> <div class="paragraph"> <p>Los artículos son nodos. Los tags son comunidades. Los xref son Algunas aristas. El lector ya no lee un artículo aislado — navega dentro de una <strong>grafo de conocimiento</strong> cuyo artículo actual es el punto de entrada.</p> </div> <div class="paragraph"> <p>Imagina una página de inicio que no muestre la lista cronológica de los últimos posts, pero una <strong>mapa del corpus</strong>: clústeres ontológicos, artículos pivote (aquellos con más aristas), rutas de lectura recomendados (« Si te ha gustado el artículo sobre Graphify, lee a continuación el que sobre el Knowledge Graph como herramienta de comprensión )</p> </div> <div class="paragraph"> <p>No es un blog. Es un <strong>atlas semántico</strong>.</p> </div> <div class="paragraph"> <p>Y esto no es ciencia ficción. El`graph.json`ya existe. Solo le falta la interfaz de navegación.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_el_sistema_de_archivos_sabe_lo_que_la_plantilla_ignora">Conclusion : El Sistema de Archivos Sabe Lo Que la Plantilla Ignora</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo que diseñé esa noche de martes es el reemplazo de una heurística perezosa (el orden cronológico) por una representación fiel de la estructura de mi corpus (el Knowledge Graph).</p> </div> <div class="paragraph"> <p>La plantilla`post.thyme`no cambia. Lo que cambia, es lo que le da de comer. Antes: una lista Java ordenada por`date`. Después : un grafo ponderado derivado de tres capas de análisis — xrefs, co‑ocurrencias de etiquetas, y ontología emergente mediante NLP.</p> </div> <div class="paragraph"> <p>El bucle está cerrado. graphify escanea el espacio de trabajo. Bakery lee el grafico y alimenta la plantilla. El lector ve recomendaciones pertinentes. Y engine — el director de orquesta — ni siquiera sabe que Todo esto existe.</p> </div> <div class="paragraph"> <p>Así es, la buena arquitectura. Cada plugin hace una cosa. Y el terminal del consumidor no necesita saber cómo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Article 0105 — Integrar Graphify en un flujo de trabajo Gradle</a></p> </li> <li> <p><a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Artículo 0106 — El Knowledge Graph como herramienta de comprensión</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Artículo 0117 — La Granularización OSS/CSS</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Plugin Gradle Controlar Dos Instancias Ollama Pro</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Artículo 0122 — 27× a 45× más eficiente : flota de expertos IA</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html Mon, 11 May 2026 00:00:00 +0000 blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_por_qué_el_fine_tune_y_no_el_rag">El problema: ¿por qué el fine-tune y no el RAG?</a></li> <li><a href="#_la_idea_una_flota_de_expertos_no_un_solo_modelo">La idea: una flota de expertos, no un solo modelo</a></li> <li><a href="#_la_base_de_código_bajo_la_lupa_7_900_archivos_144_000_líneas">La base de código bajo la lupa: 7 900 archivos, 144 000 líneas</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 22 minutes</div> <p>Cuando se utiliza un LLM para el desarrollo de software a diario, siempre se termina chocando contra el mismo muro: el modelo no conoce <strong>tu</strong> codebase. No sabe que estás utilizando tal patrón dehttps://fr.wikipedia.org/wiki/Graphe_orient%C3%A9_acyclique[DAG], tal convención Gradle, tal estratificación epistemológica en sushttps://fr.wikipedia.org/wiki/AsciiDoc[.adoc]Entonces le inyectamos contexto, repetimos, corregimos, iteramos. Y el tiempo — y el dinero — pasan.</p> </div> <div class="paragraph"> <p>Entonces lancé la pregunta de forma directa: ¿cuánto costaría un equipo de modelos afinados en mi espacio de trabajo, capaces de escupir código <strong>en mi estilo</strong> sin necesidad de que les expliquemos cada vez? Y, sobre todo: ¿cómo se compara este enfoque con las soluciones propietarias clásicas — Claude, GPT, Gemini, Grok?</p> </div> <div class="paragraph"> <p>La respuesta me sorprendió. Mucho menos de lo que imaginaba. Y el ratio coste/eficacia frente a los gigantes del sector es indecente. Aquí tienes el detalle completo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_por_qué_el_fine_tune_y_no_el_rag">El problema: ¿por qué el fine-tune y no el RAG?</h2> <div class="sectionbody"> <div class="paragraph"> <p>El RAG está bien. <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Mi knowledge graph</a> y <a href="0116_compartimentage_epistemique_automatise_llm_post.html">mi compartimentaje épistémico</a> funcionan. Pero el RAG tiene un defecto fundamental: en cada consulta, debes volver a inyectar el contexto pertinente. Tu prompt se alarga, tu latencia se dispara y el modelo nunca <strong>intioriza</strong> tus patrones — los lee cada vez como si fueran un documento externo.</p> </div> <div class="paragraph"> <p>El fine-tune, por su parte, es la memoria muscular. El modelo <strong>sabe</strong> que tú escribes.<code>build.gradle.kts`con tareas registradas vía`tasks.register</code>, que tus`AGENTS.adoc`Siguen una sintaxis estandarizada, que tu workspace está estructurado en boroughs. No necesita que le recuerden.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>El fine-tune no es un reemplazo del RAG. Es una capa complementaria. El RAG sigue siendo pertinente para los datos que cambian con frecuencia (logs, tickets, commits recientes). El fine-tune es para el conocimiento <strong>estructural</strong> y <strong>estilístico</strong> a largo plazo.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_la_idea_una_flota_de_expertos_no_un_solo_modelo">La idea: una flota de expertos, no un solo modelo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un solo modelo fine-tunado en todo mi workspace, ya está bien. Pero es subóptimo. Mi workspace cubre dominios muy diferentes :</p> </div> <div class="ulist"> <ul> <li> <p>Complementos de Gradle (Kotlin, complementos de convención, builds compuestos)</p> </li> <li> <p>Motor DAG (Kotlin, planificación, ejecución)</p> </li> <li> <p>Agentes LLM (Python, LangChain4j, RAG)</p> </li> <li> <p>Documentación arquitectónica (AsciiDoc, gobernancia)</p> </li> <li> <p>Infra/DevOps (Docker, GitHub Actions, CI/CD)</p> </li> </ul> </div> <div class="paragraph"> <p>Un modelo único debería ser bueno en todas partes, excelente en ninguna parte. La solución ? Una<strong>flota de modelos especializados</strong>, con un orquestador que dirige cada solicitud al experto adecuado.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 13 package "Ollama Cloud" { rectangle "DeepSeek V4-Pro 1.6T / 49B activos" as V4Pro #FF6B6B ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 13 package "Ollama Cloud" { rectangle "DeepSeek V4-Pro 1.6T / 49B activos" as V4Pro #FF6B6B rectangle "6× V4-Flash-FT 292B / 13B activos" as Flash #4ECDC4 rectangle "6× Gemma4 26B-FT 26B / 3.8B activos" as Gemma #FFE66D rectangle "5× Qwen3.6 35B-FT\n35B / 3B activos" as Qwen36 #A8E6CF rectangle "5× Qwen3.5 35B-FT 35B / 3B activos" as Qwen35 #FF8B94 } note bottom of Qwen35 À partir de 17€/mois (1× Ollama Pro annual) Extensible par cumul de comptes Pro selon la méthode Docker. end note actor Utilisateur as User User --> V4Pro : Requête V4Pro --> Flash : "tarea Gradle compleja" V4Pro --> Gemma : "formato AsciiDoc" V4Pro --> Qwen36 : "refactorización Kotlin" V4Pro --> Qwen35 : "script Bash" note right of V4Pro L'orkestrateur route la requête vers l'expert le plus pertinent. Zéro prompt engineering répétitif. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>La flota total :<strong>1 orquestrador + 22 expertos = 23 modelos</strong>. ¿Y el costo mensual de inferencia?<strong>17€/mes</strong>en suscripción Ollama Pro anual — extensible mediante acumulación de cuentas si se superan las cuotas, como se demuestra en <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">mi método Docker multi-cuentas</a>. Partimos de 17€, añadimos 20€ por nivel según la necesidad real. Sin desperdicio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_base_de_código_bajo_la_lupa_7_900_archivos_144_000_líneas">La base de código bajo la lupa: 7 900 archivos, 144 000 líneas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de estimar el costo del entrenamiento, hay que saber qué entrenar. He auditado mi espacio de trabajo excluyendo rigurosamente todo lo que Git ignora:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- build/ out/ node_modules/ runtimes/ .gradle/ dist/ target/ venv/ __pycache__/ .cache/ .tox/ ---- Este es el resultado para los archivos rastreados únicamente : [cols="2,2"] |=== |Métrica |Valor |Archivos fuente seguidos |**7 896** |Líneas de código (LOC) |**143 805** |Repositorios Git |**26** |Lenguajes principales |Kotlin (1 903), AsciiDoc (2 765), Python (5 029) |=== [IMPORTANT] ==== Estos 5 000+ archivos de Python incluyen los`runtimes/`cuadernos y scripts de utilidad. El núcleo de la aplicación (plugins Gradle, motore DAG, agentes) está principalmente en Kotlin y AsciiDoc. ==== A partir de esta masa, estimo poder generar un dataset sintético de**~170 millones de tokens**mediante un LLM instructor (distilado de la codebase en pares instrucción/respuesta). === Detalle del dataset por tipo de experto [source,text] ---- Dataset maître (généraliste V4-Flash) : 50M tokens Expert Gradle/Build : 15M tokens Expert Kotlin/DAG : 15M tokens Expert AsciiDoc/Gouvernance: 15M tokens Expert Agent/LLM/Python : 15M tokens Expert Infra/CI-CD : 15M tokens Micro-experts Qwen/Gemma : ~5M tokens chacun ---- == La elección de los modelos: 100% MoE, cero denso Ahí es donde la arquitectura se vuelve realmente eficiente. Un modelo *denso* activa todos sus pesos por cada token. Un modelo *MoE* (Mixture of Experts) activa solo una fracción de sus parámetros. El costo de inferencia — y de fine-tuning — es proporcional a los parámetros.**activados**, pas aux paramètres **almacenados**. Veamos lo que el mercado propone en MoE hoy en Ollama Cloud : [cols="3,2,2,1,3"] |=== |Modelo |Total parámetros |Activados |Activación |Ollama Nube |DeepSeek V4-Pro |1.6T |49B |3.1% |✅ nativo |DeepSeek V4-Flash |292B |13B |4.5% |�✅ nativo |Gemma 4 26B-A4B |26B |3.8B |14.6% |�✅ nativo |Qwen3.6-35B-A3B |35B |3B |8.6% |�❌ (aún no integrado) |Qwen3.5-35B-A3B |35B |3B |8.6% |nativo |�❌ Qwen3.5-27B |27B |27B |100% denso |eliminado |�❌ Qwen3.5-4B/9B |4B/9B |4B/9B |100% denso |eliminado |�❌ Gemma 4 31B |31B |31B |100% denso |eliminado |🧪 Gemma 4 E2B/E4B |5B/8B |5B/8B |100% denso |pipeline de validación |=== [CAUTION] ==== La relación de activación es el criterio discriminante. Un Gemma 4 26B-A4B solo activa 3.8B de sus 26B de parámetros — es 7× menos que un denso 27B, para obtener un rendimiento comparable de agente de codificación (77.1% vs 80% en LiveCodeBench v6). ==== === Por qué abandono los modelos densos La excepción: los Gemma 4 E2B y E4B. Estos dos modelos, bajo licencia Apache 2.0, son perfectos para probar y validar un pipeline de entrenamiento a bajo costo. Una ejecución de 2‑3 h en un E2B cuesta menos de $5 — si el conjunto de datos o los hiperparámetros son problemáticos, lo sabemos por unos pocos dólares. Una vez que el pipeline está listo, incluso pueden usarse para tareas ultra‑micro (reformato trivial, clasificación binaria). Pero para los expertos de la flota principal, sigo prefiriendo el MoE. Aquí está por qué: .No solo eso: los Gemma 4 E2B/E4B, expertos en anonimato fino [NOTE] ==== Google ha diseñado estos pequeños modelos como competitivos en tool calling nativo — pueden llamar funciones, manipular regex, buscar patrones. Una vez afinados en ejemplos de anonimización (emails, tokens, UUIDs, rutas de archivo), se convierten en**anonimizadores de conjunto de datos**ultra-rápidos. Les damos un bloque de texto sin formato, lo llaman`sed`/`regex`mediante una llamada a una herramienta y devuelven el bloque limpio. El costo de inferencia es ridículo: 5B activados, cabe en una sola GPU de gama baja. Estos modelos no son expertos del dominio — son**trabajadores especializados**en la cadena de producción del conjunto de datos ==== * Su VRAM de entrenamiento (incluso en QLoRA) es proporcional a**27B totales** * Su tiempo de entrenamiento es proporcional a**27B activados** Comparemos con un Qwen3.6-35B-A3B (MoE): [cols="3,2,2,2"] |=== | |Qwen3.5-27B (dense) |Qwen3.6-35B-A3B (MoE) |razón |VRAM QLoRA |~55 GB |~35 GB |1.6× |horas de GPU (8M tok) |~12h |~4 h |**3×** |Costo por fine-tune |~$24 |~$8 |**3×** |SWE-bench Verificado |75.0% |73.4% |comparable |=== El MoE cuesta 3× menos entrenar para un rendimiento de agente-codificación al 5% aproximadamente. Con 22 expertos, la diferencia asciende a miles de euros. == Estimación del entrenamiento: 811 H100-horas He desglosado el costo de entrenamiento del modelo por modelo, en QLoRA 4-bit, con los datasets descritos anteriormente. === Micro-experts MoE ligeros (3-3.8B activados) Estos modelos requieren 1 H100 (80 GB) por ejecución. La VRAM del modelo en Q4 es de aproximadamente 13-18 GB, dejando amplio espacio para los estados del optimizador LoRA y las activaciones. [cols="4,2,3,2"] |=== |Modelo |Nº de runs |GPU-h/ejecución |Total GPU-h |Gemma 4 26B-A4B-FT |6 |3.5 h |**21 h** |Qwen3.6-35B-A3B-FT |5 |4.0 h |**20 h** |Qwen3.5-35B-A3B-FT |5 |4.0 h |**20 h** |*Subtotal micro* | | |*61 h* |=== === Ejecutivos V4-Flash (13B activados / 292B almacenados) DeepSeek V4-Flash es un caso particular. Aunque solo se activen 13B por token, el modelo completo en Q4 pesa aproximadamente 142 GB — todos los expertos deben estar en VRAM durante el entrenamiento. Por lo tanto**3× H100**por run para estar cómodo [cols="4,2,3,3,2"] |=== |Modelo |conjunto de datos |GPUs |horas |Total GPU-h |V4-Flash-Base generalista |50M token |3× H100 |50 h |**150 h** |V4-Flash experto ×5 |15M tok |3 veces H100 |40 h |**600 h** |*Subtotal ejecutivos* | | | |*750 h* |=== [cols="3,2,1"] |=== |**TOTAL** | |**811 H100-h** |=== [NOTE] ==== Como comparación, un fine-tune completo del V4-Flash (sin QLoRA, todos los pesos) costaría ~4 000 H100-h solo para los 6 modelos. QLoRA divide el costo por 5. Es la única forma de hacer que el proyecto sea económicamente viable a esta escala. ==== === Tarifas GPU: ¿quién alquila qué en mayo de 2026 He comparado los principales proveedores de alquiler de H100. El precio por hora, para 811 horas. [cols="3,2,2,2"] |=== |Arrendador |$/H100·h |Total 811h |Fiabilidad |**Vast.ai punto** |$1.60 |**$1 298** |★★☆ interruptible |**Crusoe Cloud** |$2.00 |**$1.622** |★★★★ centro de datos fiable |FluidStack |$1.98 |$1 606 |[No French text was provided in the query for translation. Per instructions, output only the translated text—since there is no source text to translate, the output is empty.] |TensorDock |$1.80 |$1 460 |★★☆ |RunPod |$2.29 |$1 857 |★★★ buen compromiso |CoreWeave |$2.25 |$1 825 |★★★★ empresa |Lambda Labs |$2.49 |$2 019 |★★★★ premium |=== [TIP] ==== Vast.ai spot es el más barato pero tus runs pueden ser interrumpidos en cualquier momento. Para entrenamiento, es arriesgado. Crusoe a $2.00/h es la mejor relación fiabilidad/precio. El sobrecosto de $324 frente a Vast vale la tranquilidad. ==== === Wall-clock : ¿cuánto tiempo para entrenar todo ? Con un solo nodo 3× H100, las 31 ejecuciones (1 generalista + 30 expertos) tardan aproximadamente**12 días**en secuencial. Si alquilas 2 nodos en paralelo, cae a**6 días**. En la práctica, los microexpertos pueden ejecutarse en nodos separados (1 H100 cada uno) mientras que los V4-Flash ocupan el nodo 3× H100. Con una planificación inteligente : ---- Nœud A (3× H100) : V4-Flash généraliste → V4-Flash experts ×5 (11 jours) Nœud B (1× H100) : Gemma 4 26B ×6 → Qwen 36 ×5 → Qwen 35 ×5 (6 jours) 7 días de alquiler, todo plegado. == La inferencia: 23 modelos en Ollama Cloud a partir de 17 €/mes Es la parte más elegante de la arquitectura. Ollama Cloud permite subir modelos privados (funcionalidad del plan Pro). Mis 22 modelos fine-tunados están siendo empujados en`.gguf`en mi espacio Ollama, marcados como privados, y accesibles mediante la API estándar. [plantuml, inference-flow, svg] ---- @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 12 |Utilisateur| start :Tâche de développement; |Orkestrateur (V4-Pro)| :Classifier la tâche\n(domaine + complexité); if (Tâche simple,\nspécialisée ?) then (oui) :Router vers micro-expert\n(Gemma 4 26B-A4B-FT\n ou Qwen3.6-35B-A3B-FT); elseif (Tâche complexe,\nconventions fortes ?) then (oui) :Router vers exécutif\n(V4-Flash-FT); else (non) :Résoudre avec V4-Pro\n(architecture, décision); endif |Modèle ciblé| :Génère le code/output\n**dans mon style**,\n90%+ first-shot correct; :Retourne la réponse; stop @enduml ---- === Empezamos a 17€/mes, escalamos si es necesario El plan Pro Ollama (17€/mes anual) autoriza 3 modelos cloud competidores. En esta arquitectura, nunca necesito más de 2-3 expertos simultáneamente: * La fase de clasificación (V4-Pro) ocupa 1 slot, unos pocos segundos * El experto objetivo ocupa 1 slot, el tiempo de generar su respuesta * El 3er slot se mantiene en reserva para las tareas paralelas Si el uso aumenta, añado cuentas Pro adicionales mediante el método Docker descrito en xref:0120_cumuler_deux_abonnements_ollama_pro_docker_post.adoc[mi artículo sobre la acumulación de suscripciones]. No hay un plan Max de 100€/mes — solo añado lo que realmente necesito. El único factor limitante es el**cuota GPU-time**mensual de Ollama (50× el plan gratuito para Pro). Para mi uso de unas pocas cientos de consultas por día, es más que suficiente. [IMPORTANT] ==== El costo marginal de una llamada a V4-Pro (49B activados) vs Gemma 4 26B-A4B (3.8B activados) es el**igual para mí: cero**. Este es el plan Ollama que absorbe la diferencia de compute. Mi único indicador es la latencia. ==== === El enrutamiento en la práctica</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> <div class="paragraph"> <p>Volume de requêtes estimé : ~500/jour</p> </div> <div class="paragraph"> <p>├─ 50% → Gemma 4 26B-A4B-FT (micro, 3.8B actifs) │ Formatage AsciiDoc, scripts simples, conventions nommage │ ├─ 25% → V4-Flash-FT (exécutif, 13B actifs) │ Plugins Gradle, refactoring Kotlin, génération DAG │ ├─ 15% → Qwen 35B MoE-FT (micro, 3B actifs) │ Tâches intermédiaires, review de code, documentation │ └─ 10% → V4-Pro (orkestrateur, 49B actifs) Décisions architecturales, refactoring transverse, problèmes vraiment nouveaux</p> </div> <div class="listingblock"> <div class="content"> <pre>La mayor parte del tráfico pasa por los pequeños. El modelo grande solo interviene como último recurso. == La comparación que duele: Claude, GPT, Gemini, Grok vs mi flota Es aquí donde la brecha se vuelve vertiginosa. Veamos cuánto costaría el mismo volumen de trabajo (500 consultas/día, ~300 tokens de entrada + 2 000 tokens de salida en promedio) con las soluciones propietarias del mercado en mayo de 2026. === Anthropic — Claude (tarifas mayo 2026) Anthropic ha *reducido* recientemente sus precios. La presión de las soluciones open-weight como DeepSeek y Qwen se hace sentir. [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Salida $/MTok |Costo/día |**Costo/mes** |Opus 4.7 (el más inteligente) |$5 |$25 |$25.75 |**$772** |Soneto 4.6 (equilibrado) |$3 |$15 |$15.45 |**$463** |Haiku 4.5 (el más rápido) |$1 |$5 |$5.15 |**$154** |=== [CAUTION] ==== Estas tarifas son *después* de la última reducción de precios de Anthropic (mayo 2026). Antes de eso, Opus estaba a $15/$75 por MTok. El miedo a los pesos abiertos es real. ==== Incluso el modelo más barato de Claude — Haiku 4.5 à**154€/mes**— cuesta 9× más que mi suscripción a Ollama Pro a 17€. Y Haiku no conoce mi base de código, no genera en mi estilo y requiere ingeniería de prompts sistemática. El más inteligente — Opus 4.7 — dispara el presupuesto a**772€/mes**para un volumen modesto de 500 solicitudes por día. Sea**45× más caro**que mi solución. === OpenAI — GPT (tarifas mayo 2026) [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |$/MTok |Costo/día |**Costo/mes** |GPT 5.5 (el + inteligente) |$5 |$30 |$30.90 |**$927** |GPT 5.4 (estándar) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 Mini |$0.75 |$4.50 |$4.64 |**$139** |=== Incluso el modelo « económico » de OpenAI — GPT 5.4 Mini a 139€/mes — cuesta 8× mi suscripción, para un modelo que no sabe *nada* de mis convenciones y necesita una ingeniería de prompts pesada. GPT 5.5, su producto estrella :**927€/mes**. Para *zero-shot* en mi codebase. Con 2-3 iteraciones por tarea debido al estilo no dominado, el verdadero costo mensual se duplica fácilmente. === Google — Gemini (precios mayo 2026) [cols="3,2,2,2,2"] |=== |Modelo |/$/MTok |Salida $/MTok |Costo/día |**Costo/mes** |Gemini 3.1 Pro (High) |$3.50 |$17.50 |$18.00 |**$540** |Gemini 3.1 Pro |$2 |$10 |$10.30 |**$309** |Gemini 3 Flash |$0.30 |$1.50 |$1.54 |**$46** |=== Gemini 3 Flash por 46€/mes es competitivo en precio puro — pero sin fine-tune, genera código « genérico ». No es código *Cheroliv*. === Grok — xAI (tarifas mayo 2026) [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Salida $/MTok |Costo/día |**Costo/mes** |Grok 4 |$4 |$16 |$16.48 |**$494** |Grok 4 Mini |$0.80 |$3.20 |$3.30 |**$99** |=== === Microsoft — Azure OpenAI (precios mayo 2026) Azure aplica los mismos precios que la API directa de OpenAI, pero además factura la infraestructura y la red. Se debe contar con un recargo del 10-20% por el servicio gestionado. [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |$/MTok |Costo/día |**Costo/mes** |GPT 5.4 (Azure, Global) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 + infraestructura |recargo 15% |recargo 15% |$17.77 |**$533** |=== [NOTE] ==== Las tarifas de arriba se refieren a la API, no a los planes de suscripción « chat » (Claude Pro a $20/mes, ChatGPT Plus a $20/mes). Aquí comparamos el uso *desarrollador*, aquel en el que encadenas cientos de solicitudes al día mediante API para generar, refactorar, documentar. Los planes para el público general tienen cuotas que se disparan mucho antes de 500 solicitudes/día. ==== === El cuadro comparativo final [cols="3,2,2,2,2,2"] |=== |Solución |Conocimiento de la base de código |Estilo integrado |Costo/mes |Iteraciones |**Costo efectivo** |**Mi flota (Ollama Pro)** |✅ ajustada |En los pesos |**17€** |0-1 |**17€** |Claude Opus 4.7 |�❌ Zero-shot |❌ Prompt necesario |$772 |2-3 |$1 500-2 300 |Claude Haiku 4.5 |cero-disparo |�❌ Prompt necesario |$154 |3-4 |$460-615 |GPT 5.5 |❌ cero disparo |❌ Prompt necesario |$927 |2-3 |$1 854-2 781 |GPT 5.4 |❌ Zero-shot |Prompt necesario |$463 |2-3 |$925-1 390 |GPT 5.4 Mini |❌ cero disparos |�❌ Prompt necesario |$139 |3-5 |$417-695 |Gemini 3.1 Pro High |�❌ Zero-shot |❌ Prompt necesario |$540 |2-3 |$1 080-1 620 |Grok 4 |�❌ Zero-shot |�❌ Prompt necesario |$494 |2-3 |$988-1 482 |**Azure GPT 5.4** |�❌ zero-shot |❌ Prompt necesario |$533 |2-3 |$1 066-1 600 |=== [plantuml, cost-comparison, svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FAFAFA</p> </div> <div class="paragraph"> <p>title Relación costo/eficacia — mi flota vs el mercado (mayo 2026) rectangle "17€/mes" as OURS #4ECDC4 rectangle "Opus 4.7 772€" as OPUS #FF6B6B rectangle "Soneto 4.6\n463€" as SONNET #FF8B94 rectangle "GPT 5.5 927€" as GPT #FFD93D rectangle "Gemini 3.1 Pro 540€" as GEMINI #6C5CE7 rectangle "Grok 4 494€" as GROK #A8E6CF rectangle "Haiku 4.5 154€" as HAIKU #DFE6E9 rectangle "GPT 5.4 Mini 139€" as MINI #B2BEC3</p> </div> <div class="paragraph"> <p>note bottom of OURS Avec fine-tune intégré. Zéro prompt engineering. 90%+ first-shot correct. end note</p> </div> <div class="paragraph"> <p>@enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>17€/mes para 23 expertos IA afinados. El flagship Claude Opus 4.7 cuesta**45× más caro**para una calidad inferior en *mi* codebase. GPT 5.5 cuesta**54× más caro**. Incluso el modelo más barato del mercado (Gemini Flash a 46€) cuesta**2.7× más**sin el conocimiento de mi workspace. El veredicto es sin apelación: el fine-tune sobre arquitecturas MoE, en 2026, no es solo « más barato ». Es un factor de eficiencia de**27× a 54×**sobre la relación costo/calidad frente a las soluciones propietarias. Anthropic, OpenAI, Google — todos lo saben, y es por eso que bajan sus precios en pánico. == El factor de eficiencia: 5-8× vs usar V4-Pro solo Comparemos los dos extremos. === Escenario A: V4-Pro solo para todo [cols="3,2"] |=== |Métrica |Valor |Conocimiento de la base de código |0 (zero-shot) |Convención naming |40-60% primer intento correcto |Prompt engineering necesario |Sí, sistemático |Iteraciones por tarea |2-3 |Costo inferencia |$100/mes (Ollama Max) |Latencia media |~20 tok/s + red |=== === Escenario B : Flota MoE orquestrada [cols="3,2"] |=== |métrico |Valor |Conocimiento de la base de código |Integrada (fine-tune) |Convención de nombres |90-95% correcto en el primer intento |Ingeniería de prompts |No (el estilo está en los pesos) |Iteraciones por tarea |0-1 |Costo de inferencia |$60/mes (3× Ollama Pro) |Latencia media |~50 tok/s (modelos ligeros) |=== [cols="4,2,2,2"] |=== |Dimensión |solo V4-Pro |Flota MoE |Factor |Costo mensual de la nube |$100 |**$60** |1.7× |Contexto para inyectar |Alto (prompt) |**Cero** |�∞ |Iteraciones medias |2-3 |**0-1** |2-3× |latencia percibida |20 tok/s |50 tok/s |**2.5×** |Primer disparo correcto |50% |90%+ |**1.8×** |=== **Factor de eficiencia global : 5-8×**— en productividad del desarrollador sintió. [NOTE] ==== El factor no se mide en tokens ni en dólares. Se mide en « cuánto tiempo paso explicándole al modelo lo que ya debería saber ». Con los modelos fine-tunados, ese tiempo tiende a cero. ==== == El presupuesto completo: una inversión one-shot, un paquete ridículo [cols="3,2"] |=== |Puesto |Importe |Entrenamiento GPU (811 H100-h, Crusoe $2/h) |**$1 622** |Generación dataset sintético (API LLM) |**$400** |Inferencia (Ollama Pro anual, $17/mes) |**$204** |**Total primer año** |**$2 226** |**Equivalente mensual** |**$186** |**Costo estimado por solicitud** |< $0.01 |=== [plantuml, budget-breakdown, svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FAFAFA</p> </div> <div class="paragraph"> <p>rectangle "Presupuesto Año 1 : $2 226" as Total #E8E8E8 { rectangle "GPU de entrenamiento $1 622 (73%)" as Train #FF6B6B rectangle "conjunto de datos destilación $400 (18%)" as Data #FFE66D rectangle "Ollama Pro $204 (9%)" as Cloud #4ECDC4 }</p> </div> <div class="paragraph"> <p>note bottom of Total $186/mois équivalent année 1. Dès l’an 2 : $17/mois. Amorti par ~$235 de CA mensuel avec marge 95%. end note</p> </div> <div class="paragraph"> <p>@enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>$186/mes el primer año,**$17/mes**desde el año 2. El precio de una suscripción premium de Netflix, para un equipo de 23 expertos en IA disponibles 24/7, que escriben código *en mi estilo* sin que tenga que explicarles mis convenciones. === El cálculo de rentabilidad Con edster.cloud y su margen de ~95%, el punto muerto está en**~$2 340 de CA adicional**sobre el año. En la práctica : * 1 misión de gestión de software → $3 000-5 000 → inversión cubierta + beneficio * 1 formación corporativa → $5 000-10 000 → cómodo * El upsell implícito: "Mi equipo de IA controla mi fábrica de software" → Diferenciación comercial A partir del año 2, el entrenamiento ya no se paga (excepto la actualización del conjunto de datos). El costo anual cae a**$204**($17/mes). La relación costo/valor es la de un unicornio: prácticamente nula. == Los límites del ejercicio Esto sigue siendo una *estimación a ojo*. Varias variables pueden hacer variar el presupuesto: [cols="2,3"] |=== |Variable |Impacto |Generación del dataset sintético |Si la API de destilación falla (alucinaciones, pares mal formados), se necesita tiempo humano para curar. Costo oculto. |Cuotas de tiempo de GPU Ollama |Si el uso supera las cuotas del plan Pro, será necesario subir de gama o cambiar a una GPU dedicada. |Calidad efectiva de los fine-tunes |Un fine-tune fallido → a repetir. El verdadero riesgo son los hiperparámetros, no la ubicación de la GPU. |Evolución rápida de los modelos |Los Qwen3.6/Gemma 4 se lanzaron hace menos de 1 mes. En 6 meses, la siguiente generación será mejor y más barata de afinar. |=== [WARNING] ==== No inicies 811 horas de entrenamiento sin haber probado primero el pipeline en *un solo* micro-modelo. Una ejecución de 3-4h en un Qwen 35B-A3B cuesta $8. Si el dataset está podrido, lo sabrás por $8, no por $1 622. ==== == Conclusión: el ajuste fino se ha convertido en un lujo accesible Hace un año, fine-tunear un modelo de 292B de parámetros (incluso en QLoRA) era una cuestión de investigación. Hoy, en mayo de 2026, es un proyecto factible para un desarrollador independiente : * **811 H100-horas**de entrenamiento — $1 622 en Crusoe * **23 modelos especializados**cargados en Ollama Cloud —**$17/mes** * **0 servidor, 0 GPU local, 0 mantenimiento infra** La democratización provino de tres factores convergentes: 1. **Las arquitecturas MoE**— que permiten ajustar eficientemente modelos de los cuales solo una fracción de los pesos está activada 2. **Los planes fijos de Ollama Cloud**— que convierten un costo variable (por token) en un costo fijo (suscripción) 3. **Los modelos open-weight de calidad**— DeepSeek V4, Qwen3.6, Gemma 4 están bajo licencias MIT/Apache 2.0 La civilización avanza extendiendo el número de operaciones importantes que podemos realizar sin pensarlas. El fine-tune, es exactamente eso: una operación que delegas a la máquina para no tener que pensar más en ello. Y en 2026, cuesta menos que un desarrollador junior mensualizado. --- _Artículo publicado el {jbake-date}_ == Modelos fine-tunés de la flota [cols="2,2,2,2,3"] |=== |Tamaño activado |Número |Modelo básico |dominio |Conjunto de datos |13B |1 |DeepSeek-V4-Flash-Base |Espacio de trabajo general |50M tokens |13B |5 |DeepSeek-V4-Flash |Gradle, Kotlin, DAG, Doc, Infra |15M tokens |3.8B |6 |Gemma 4 26B-A4B |Microtareas, formato, scripts |5M tokens |3B |5 |Qwen3.6-35B-A3B |Refactorización, revisión, documentación intermedia |5M tokens |3B |5 |Qwen3.5-35B-A3B |Tareas heredadas, compatibilidad |5M tokens |=== == Recursos === Modelos open-weight en HuggingFace * https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Base[DeepSeek V4-Flash-Base — 292B params, license MIT] * https://huggingface.co/Qwen/Qwen3.6-35B-A3B[Qwen3.6-35B-A3B — 35B/3B activados, licencia Apache 2.0] * https://huggingface.co/Qwen/Qwen3.5-35B-A3B[Qwen3.5-35B-A3B — 35B/3B activados, licencia Apache 2.0] * https://huggingface.co/google/gemma-4-26B-A4B-it[Gemma 4 26B-A4B — 26B/3.8B activados, licencia Apache 2.0] === Fuentes de las tarifas (mayo 2026) * https://ollama.com/pricing[Precios de Ollama Cloud — plan Pro $17/mes anual] * https://www.anthropic.com/pricing[Tarifas Anthropic — Claude API (Opus 4.7 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5)] * https://openai.com/api/pricing/[Tarifas OpenAI — API GPT (GPT 5.5 $5/$30, GPT 5.4 $2.50/$15)] * https://deepinfra.com/pricing[Tarifas DeepInfra — instancias GPU H100 $1.79/h, B200 $2.79/h] * Vast.ai, Crusoe Cloud, FluidStack, TensorDock, RunPod, CoreWeave, Lambda Labs — listados de precios manuales, fechados en mayo de 2026 === Anuncios oficiales * https://qwen.ai/blog?id=qwen3.6-35b-a3b[Anuncio oficial Qwen3.6-35B-A3B — blog Qwen]— codificación agéntica, Apache 2.0, 262K contexto</pre> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_por_qué_gradle_para_infra">¿Por qué Gradle para Infra?</a></li> <li><a href="#_el_build_gradle_kts_completo">El build.gradle.kts completo</a></li> <li><a href="#_anatomía_de_las_tareas_clave">Anatomía de las Tareas Clave</a> <ul class="sectlevel2"> <li><a href="#_startollamab_el_lanzador">startOllamaB` — El Lanzador</a></li> <li><a href="#_signinb_el_interactivo">signInB` — El Interactivo</a></li> <li><a href="#_pullmodelb_lo_configurable">pullModelB` — Lo configurable</a></li> <li><a href="#_statusollamaall_el_diagnóstico">statusOllamaAll` — El Diagnóstico</a></li> <li><a href="#_cleanollamab_la_limpieza_que_preserva_la_identidad">cleanOllamaB` — La Limpieza que Preserva la Identidad</a></li> </ul> </li> <li><a href="#_flujo_de_trabajo_completo_de_cero_a_dos_sesiones">Flujo de trabajo completo — De cero a dos sesiones</a></li> <li><a href="#_por_qué_no_hacer_un_verdadero_plugin_gradle">¿Por qué no hacer un verdadero plugin Gradle ?</a></li> <li><a href="#_lecciones_aprendidas">Lecciones aprendidas</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 18 minutes</div> <p>¿Por qué escribir comandos Docker a mano cuando se puede encapsular todo en tareas Gradle? Así es como industrialicé mi configuración dual-Ollama Pro sin scripts de shell externos. Arranque, parada, identidad, inicio de sesión, pull — todo pasa por`./gradlew`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>En el artículo anterior mostré cómo hacer que dos cuentas Ollama Pro convivan en la misma máquina al aislar la segunda instancia en un contenedor Docker. El montaje funciona, pero la gestión diaria resulta rápidamente engorrosa: recordar el nombre del contenedor, volver a ejecutar los comandos correctos.<code>docker exec</code>, checker qué puerto está activo…​</p> </div> <div class="paragraph"> <p>Conoces ese momento en el que tienes 14 terminales abiertos, que estás tecleando`docker exec ollama-instance-b ollama list`para la cuarta vez, y que te digas « debe haber una manera más limpia » ?</p> </div> <div class="paragraph"> <p>Este método es Gradle.</p> </div> <div class="paragraph"> <p>No solo para construir código. Gradle como un director de orquesta de infraestructura local. Tareas que proveen, verifican, prueban y limpian. Todo esto versionado en un`build.gradle.kts`que vive al lado del`docker-compose.yml`.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-gradle-ollama.svg" alt="architecture gradle ollama" width="721" height="515"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_gradle_para_infra">¿Por qué Gradle para Infra?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La pregunta es legítima. Gradle es una herramienta de compilación. Normalmente compila, prueba y empaqueta. No lanza contenedores Docker.</p> </div> <div class="paragraph"> <p>Excepto que Gradle también es un motor de grafo de dependencias — y ahí es donde se vuelve interesante para nuestro caso.</p> </div> <div class="paragraph"> <p>Queremos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Que el contenedor se inicie antes de un sign-in</p> </li> <li> <p>Que se verifique la identidad antes de un pull de modelo</p> </li> <li> <p>Que una prueba de API falle silenciosamente si el contenedor está down</p> </li> </ol> </div> <div class="paragraph"> <p>Del grafo de dependencias puro. Gradle está diseñado para eso. El DSL de Kotlin hace que escribir las tareas sea fluido, y el`doLast`permite ejecutar comandos del sistema como si fuera código de aplicación.</p> </div> <div class="paragraph"> <p>Y sobre todo: sin bashrc que mantener, sin scripts que estén tirados por ahí`~/bin`, no hay Makefile al lado del docker-compose. Todo vive en un solo archivo, en el mismo lugar que el código del proyecto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_build_gradle_kts_completo">El build.gradle.kts completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este es el archivo que finalmente escribí. Hace todo, desde el aprovisionamiento del volumen hasta el curl de verificación, pasando por el inicio de sesión interactivo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.io.ByteArrayOutputStream plugins { base } // ------------------------------------------------------------------------- // Configuration // ------------------------------------------------------------------------- val instanceName = "ollama-instance-b" val instancePort = 11435 val instanceImage = "ollama/ollama:0.20.2" val dataDir = file("${System.getProperty("user.home")}/ollama-b-data") val nativePort = 11434 // Modèles à gérer — cloud Pro + un modèle local gratuit pour les tests val proModels = listOf("deepseek-v4-pro:cloud", "gemma4:31b-cloud") val freeModels = listOf("qwen3:0.6b") // ------------------------------------------------------------------------- // Tâche préparatoire — création du volume si absent // ------------------------------------------------------------------------- val prepareVolume by tasks.registering { group = "ollama" description = "Crée le répertoire de volume pour l'instance B si absent" doLast { if (!dataDir.exists()) { dataDir.mkdirs() println("Volume créé : ${dataDir.absolutePath}") } else { println("Volume existant : ${dataDir.absolutePath}") } } } // ------------------------------------------------------------------------- // Démarrage du conteneur Docker // ------------------------------------------------------------------------- val startOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Lance le conteneur Docker pour l'instance Ollama B" dependsOn(prepareVolume) commandLine( "docker", "run", "-d", "--name", instanceName, "-p", "$instancePort:11434", "-v", "${dataDir.absolutePath}:/root/.ollama", "-e", "OLLAMA_HOST=0.0.0.0", "--restart", "always", instanceImage ) isIgnoreExitValue = true doLast { val alreadyRunning = executionResult.get().exitValue != 0 if (alreadyRunning) { logger.lifecycle("Le conteneur '$instanceName' existe déjà — tentative de démarrage") } else { logger.lifecycle("Conteneur '$instanceName' lancé") } } } // ------------------------------------------------------------------------- // Arrêt du conteneur // ------------------------------------------------------------------------- val stopOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête le conteneur Docker de l'instance B" commandLine("docker", "stop", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' arrêté") } } // ------------------------------------------------------------------------- // Affichage de la clé publique (Device Key) // ------------------------------------------------------------------------- val checkIdentity by tasks.registering(Exec::class) { group = "ollama" description = "Affiche la clé publique SSH de l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "cat", "/root/.ollama/id_ed25519.pub") standardOutput = ByteArrayOutputStream() doLast { val pubKey = standardOutput.toString().trim() println("=".repeat(60)) println("Device Key (Instance B)") println("=".repeat(60)) println(pubKey) println("=".repeat(60)) println("→ Enregistre cette clé sur https://ollama.com/settings/keys") println("→ Puis exécute : ./gradlew signInB") println("=".repeat(60)) } } // ------------------------------------------------------------------------- // Sign-in interactif (Ouvrira le navigateur) // ------------------------------------------------------------------------- val signInB by tasks.registering(Exec::class) { group = "ollama" description = "Lance l'authentification interactive Ollama pour le compte B" dependsOn(startOllamaB) standardInput = System.`in` standardOutput = System.out errorOutput = System.err commandLine("docker", "exec", "-it", instanceName, "ollama", "signin") doFirst { logger.lifecycle("Authentification pour le Compte Pro B...") logger.lifecycle("Ouvre ton navigateur et connecte-toi avec l'email du compte B") } } // ------------------------------------------------------------------------- // Pull d'un modèle (paramétrable via propriété Gradle) // ------------------------------------------------------------------------- val pullModelB by tasks.registering(Exec::class) { group = "ollama" description = "Pull un modèle sur l'instance B. Usage : ./gradlew pullModelB -Pmodel=nom:tag" dependsOn(startOllamaB) val modelName = project.findProperty("model") as? String ?: "qwen3:0.6b" commandLine("docker", "exec", instanceName, "ollama", "pull", modelName) doFirst { logger.lifecycle("Pull du modèle '$modelName' sur l'instance B...") } doLast { logger.lifecycle("Modèle '$modelName' pullé avec succès") } } // ------------------------------------------------------------------------- // Pull de tous les modèles Pro (batch) // ------------------------------------------------------------------------- val pullAllProModels by tasks.registering { group = "ollama" description = "Pull tous les modèles cloud Pro sur l'instance B" dependsOn(startOllamaB) doLast { proModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles Pro pullés") } } // ------------------------------------------------------------------------- // Pull de tous les modèles gratuits (batch / première install) // ------------------------------------------------------------------------- val pullAllFreeModels by tasks.registering { group = "ollama" description = "Pull tous les modèles locaux gratuits sur l'instance B" dependsOn(startOllamaB) doLast { freeModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles gratuits pullés") } } // ------------------------------------------------------------------------- // Liste des modèles disponibles sur l'instance B // ------------------------------------------------------------------------- val listModelsB by tasks.registering(Exec::class) { group = "ollama" description = "Liste les modèles disponibles sur l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "ollama", "list") } // ------------------------------------------------------------------------- // Health check — test API sur les deux instances // ------------------------------------------------------------------------- val testOllamaB by tasks.registering { group = "ollama" description = "Teste la connectivité API de l'instance B avec un simple chat" dependsOn(startOllamaB) doLast { val model = project.findProperty("model") as? String ?: "qwen3:0.6b" logger.lifecycle("Test de l'instance B avec le modèle '$model'...") val payload = """ { "model": "$model", "messages": [{"role": "user", "content": "Réponds uniquement par OK"}], "max_tokens": 5 } """.trimIndent() val process = ProcessBuilder( "curl", "-s", "http://localhost:$instancePort/v1/chat/completions", "-H", "Content-Type: application/json", "-d", payload ).start() val response = process.inputStream.bufferedReader().readText() process.waitFor() if (response.contains("\"id\":\"chatcmpl") || response.contains("\"choices\"")) { println("✓ Instance B OK — port $instancePort répond") println(" Response: ${response.take(120)}...") } else { println("✗ Instance B INACTIVE — vérifie le conteneur avec './gradlew statusOllamaAll'") println(" Raw: $response") } } } // ------------------------------------------------------------------------- // Health check sur les deux instances simultanément // ------------------------------------------------------------------------- val statusOllamaAll by tasks.registering { group = "ollama" description = "Vérifie le statut des deux instances Ollama (native + Docker)" doLast { // Instance native runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$nativePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Native — port $nativePort OK (HTTP $code)" else "✗ Instance Native — port $nativePort (HTTP $code)") }.getOrElse { println("✗ Instance Native — injoignable sur le port $nativePort") } // Instance Docker runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$instancePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Docker B — port $instancePort OK (HTTP $code)" else "✗ Instance Docker B — port $instancePort (HTTP $code)") }.getOrElse { println("✗ Instance Docker B — injoignable sur le port $instancePort") } // Info conteneur runCatching { val process = ProcessBuilder("docker", "ps", "--filter", "name=$instanceName", "--format", "table {{.Names}}\\t{{.Status}}\\t{{.Ports}}").start() val status = process.inputStream.bufferedReader().readText() process.waitFor() println() println("Conteneur Docker :") println(status) } } } // ------------------------------------------------------------------------- // Nettoyage complet // ------------------------------------------------------------------------- val cleanOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête et supprime le conteneur Docker de l'instance B" dependsOn(stopOllamaB) commandLine("docker", "rm", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' supprimé") logger.lifecycle("Le volume ${dataDir.absolutePath} est conservé (identité persistante)") } } // ------------------------------------------------------------------------- // Affichage des instructions // ------------------------------------------------------------------------- val helpOllama by tasks.registering { group = "ollama" description = "Affiche l'aide des tâches Ollama disponibles" doLast { println(""" ╔══════════════════════════════════════════════════════════════╗ ║ Tâches Gradle — Pilotage Dual Ollama Pro ║ ╠══════════════════════════════════════════════════════════════╣ ║ ./gradlew startOllamaB Démarrer l'instance Docker B ║ ║ ./gradlew stopOllamaB Arrêter l'instance Docker B ║ ║ ./gradlew checkIdentity Afficher la clé SSH publique ║ ║ ./gradlew signInB Sign-in interactif compte B ║ ║ ./gradlew pullModelB Pull un modèle (-Pmodel=...) ║ ║ ./gradlew pullAllProModels Pull tous les modèles Pro ║ ║ ./gradlew pullAllFreeModels Pull tous les modèles gratuits ║ ║ ./gradlew listModelsB Lister les modèles instance B ║ ║ ./gradlew testOllamaB Test API avec un chat simple ║ ║ ./gradlew statusOllamaAll Santé des 2 instances ║ ║ ./gradlew cleanOllamaB Supprimer le conteneur ║ ║ ./gradlew helpOllama Cette aide ║ ╚══════════════════════════════════════════════════════════════╝ """.trimIndent()) } }</code></pre> </div> </div> <div class="paragraph"> <p>He aquí. Doce tareas, un punto de entrada único y cero fricción.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomía_de_las_tareas_clave">Anatomía de las Tareas Clave</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_el_lanzador">startOllamaB` — El Lanzador</h3> <div class="paragraph"> <p>Nada de hechicero: un`docker run -d`con los parámetros correctos. El truco está en`isIgnoreExitValue = true`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>Si el contenedor ya existe, el comando`docker run`falle (código de salida ≠ 0). Sin esta propiedad, Gradle detendría toda la construcción en error. Aquí, el fallo es silencioso — y el`doLast`detecta si era un 'ya existente' o un verdadero error.</p> </div> <div class="paragraph"> <p>Le `doLast`es crucial : se ejecuta <strong>después</strong> de la ejecución del comando, lo que permite inspeccionar`executionResult.get().exitValue`y registrar un mensaje apropiado.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_el_interactivo">signInB` — El Interactivo</h3> <div class="paragraph"> <p>Es la única tarea que requiere una interacción humana. Gradle transmite`System.in`al proceso para que el prompt`ollama signin`pueda mostrarse normalmente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">standardInput = System.`in` standardOutput = System.out errorOutput = System.err</code></pre> </div> </div> <div class="paragraph"> <p>Sin eso, el inicio de sesión se bloquearía porque stdin estaría cerrado y nunca verías el prompt.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_lo_configurable">pullModelB` — Lo configurable</h3> <div class="paragraph"> <p>Una tarea genérica que acepta un parámetro vía`-P` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew pullModelB -Pmodel=deepseek-v4-pro:cloud ./gradlew pullModelB # fallback : qwen3:0.6b</code></pre> </div> </div> <div class="paragraph"> <p>El fallback es importante :`project.findProperty("model") as? String ?: "qwen3:0.6b"`garantiza que la tarea no falle si se olvida el parámetro.</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_el_diagnóstico">statusOllamaAll` — El Diagnóstico</h3> <div class="paragraph"> <p>Dos`curl`en salud en los puertos`11434` et <code>11435</code>, con un fallback en`runCatching`para no fallar si una de las instancias está caída. La salida está estructurada :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">✓ Instance Native — port 11434 OK (HTTP 200) ✓ Instance Docker B — port 11435 OK (HTTP 200) Conteneur Docker : NAMES STATUS PORTS ollama-instance-b Up 3 hours 0.0.0.0:11435->11434/tcp</code></pre> </div> </div> <div class="paragraph"> <p>Una mirada, y sabes exactamente qué funciona y qué falla.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_la_limpieza_que_preserva_la_identidad">cleanOllamaB` — La Limpieza que Preserva la Identidad</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">commandLine("docker", "rm", instanceName) isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>El contenedor se elimina, pero el volumen`~/ollama-b-data`es<strong>conservado</strong>. La identidad SSH sobrevive a la limpieza. Al próximo`startOllamaB`, las mismas llaves se reutilizarán — no es necesario volver a iniciar sesión ni volver a registrar la clave del dispositivo.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p><code>cleanOllamaB`no toques el volumen. Si quieres borrar la identidad B (y volver a empezar desde cero), tienes que eliminar</code>~/ollama-b-data`manualmente. Es voluntario — un`clean`no debería destruir credenciales.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_flujo_de_trabajo_completo_de_cero_a_dos_sesiones">Flujo de trabajo completo — De cero a dos sesiones</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta es la secuencia ideal para alguien que llega al proyecto y quiere poner todo en marcha sin abrir documentación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text"># 1. Premier contact — que faire ? $ ./gradlew helpOllama # 2. On démarre l'instance B $ ./gradlew startOllamaB # 3. On récupère la Device Key et on l'enregistre sur ollama.com $ ./gradlew checkIdentity # → copier-coller de la clé sur https://ollama.com/settings/keys # 4. Authentification interactive $ ./gradlew signInB # 5. Pull d'un petit modèle gratuit pour tester la plomberie $ ./gradlew pullModelB # 6. Test API $ ./gradlew testOllamaB # 7. Si tout est vert, pull des modèles Pro $ ./gradlew pullAllProModels # 8. Vérification finale des deux instances $ ./gradlew statusOllamaAll</code></pre> </div> </div> <div class="paragraph"> <p>Menos de dos minutos, todo está provisionado. No hay README que leer, no hay variables de entorno que configurar. La tarea`helpOllama`hace las veces de documentación integrada.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml ... ... ( skipping 126 lines ) ... skinparam StereotypeE { BackgroundColor white BorderColor black } skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam DefaultFontSize 11 actor Développeur as Dev participant "Gradle ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml !theme plain skinparam DefaultFontSize 11 actor Développeur as Dev participant "Gradle (build.gradle.kts)" as Gradle participant "Docker\nDaemon" as Docker participant "Ollama Instancia B" as OllamaB participant "Ollama Nube" as Cloud == Provisionnement == Dev -> Gradle : helpOllama Gradle --> Dev : Aide et instructions Dev -> Gradle : startOllamaB Gradle -> Docker : docker run -d ollama/ollama:0.20.2 Docker -> OllamaB : Génération clés SSH (id_ed25519) Docker --> Gradle : conteneur lancé Gradle --> Dev : OK Dev -> Gradle : checkIdentity Gradle -> Docker : cat id_ed25519.pub Gradle --> Dev : Clé publique SSH Dev -> Cloud : Enregistrement clé SSH\n(sur ollama.com/settings/keys) == Authentification == Dev -> Gradle : signInB Gradle -> Docker : ollama signin (interactif) Dev <-> Cloud : Login navigateur (compte B) Docker -> Cloud : Échange token ⇔ Device Key Gradle --> Dev : Authentifié == Vérification == Dev -> Gradle : pullModelB Gradle -> Docker : ollama pull qwen3:0.6b Gradle --> Dev : Modèle pullé Dev -> Gradle : testOllamaB Gradle -> Docker : curl /v1/chat/completions Gradle --> Dev : ✓ Instance B OK == Production == Dev -> Gradle : pullAllProModels Gradle -> Docker : ollama pull deepseek-v4-pro:cloud Gradle -> Docker : ollama pull gemma4:31b-cloud Gradle --> Dev : Modèles Pro pullés Dev -> Gradle : statusOllamaAll Gradle --> Dev : ✓ Native ✓ Docker B @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_no_hacer_un_verdadero_plugin_gradle">¿Por qué no hacer un verdadero plugin Gradle ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pregunta legítima. Extraer esto`build.gradle.kts`Convertirlo en un plugin Gradle autónomo tendría ventajas: reutilización entre proyectos, configuración declarativa, extensión del DSL.</p> </div> <div class="paragraph"> <p>Pero por ahora, no tiene sentido. Este build no tiene una lógica de negocio compleja — es un envoltorio alrededor de comandos Docker y curl. La capa adicional de un plugin Gradle completo (con extensión, pruebas unitarias, publicación) sería desproporcionada para 12 tareas de utilidad.</p> </div> <div class="paragraph"> <p>Le `build.gradle.kts`inline vive en el proyecto que lo necesita. Es trivial copiarlo en otro sitio. Si algún día tengo tres proyectos que dependen de él, lo convertiré en un plugin. Por ahora, KISS.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>El día en que tienes tres`build.gradle.kts`Idénticos en tres proyectos, esa es la señal de que hay que extraer un plugin. Antes de eso, la duplicación es menos costosa que la abstracción. Sabiduría de desarrollador.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas">Lecciones aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle no es solo una build tool</strong>— El motor de grafo de dependencias lo convierte en un orquestador de infraestructura formidable.<code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code>: estas tres primitivas son suficientes para gestionar un contenedor Docker con la misma fiabilidad que una canalización CI.</p> </li> <li> <p><strong>isIgnoreExitValue` es tu amigo</strong>— En un mundo ideal,<code>docker run`en un contenedor ya existente devolvería una advertencia en lugar de un código de salida de error. En el mundo real, tú pones`isIgnoreExitValue = true`y tú gestionas el diagnóstico en`doLast</code>.</p> </li> <li> <p><strong>Las tareas parametrables eliminan la ambigüedad</strong> — Un <code>pullModelB`genérico con</code>-Pmodel=…​`reemplaza N tareas especializadas. Una sola tarea, una sola documentación, un solo comportamiento.</p> </li> <li> <p><strong>runCatching` para los health checks</strong>— Cuando pruebas N endpoints, el fallo del primero no debe impedir probar los otros.<code>runCatching</code>+`getOrElse`por endpoint, y el diagnóstico sigue siendo completo incluso en caso de falla parcial.</p> </li> <li> <p><strong>La tarea <code>helpOllama</code> como documentación ejecutable</strong> — Un `println()`bien formateado sustituye a un README de tres párrafos. Está auto-documentado, siempre actualizado y accesible sin salir de la terminal.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pasamos de comandos Docker a teclear a mano a un flujo de trabajo Gradle completo, versionado y reutilizable. Doce tareas cubren todo el ciclo de vida: provisión, identidad, sign-in, pull, prueba, diagnóstico, limpieza.</p> </div> <div class="paragraph"> <p>El combo docker-compose + build.gradle.kts + opencode.json forma una trinidad limpia: Docker para el aislamiento, Gradle para la orquestación, OpenCode para el consumo. Cada capa tiene su responsabilidad, y ninguna se desborda sobre la otra.</p> </div> <div class="paragraph"> <p>¿Próximo paso? Automatizar el ciclo de vida en CI para que las instancias de Ollama estén disponibles en los entornos de desarrollo efímeros. Pero eso es otro artículo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_recursos">Recursos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/tutorial_using_tasks.html">Manual del usuario Gradle — Tareas</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">Manual de usuario Gradle — Tareas Personalizadas</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Imagen Docker Ollama en Docker Hub</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle DSL Kotlin — Documentación</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Artículo publicado el 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com//blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_por_qué_dos_veces_lo_mismo">¿Por qué dos veces lo mismo?</a></li> <li><a href="#_el_corazón_del_problema_la_device_key">El corazón del problema: La Device Key</a></li> <li><a href="#_preparación_paso_a_paso">Preparación — Paso a Paso</a> <ul class="sectlevel2"> <li><a href="#_prerrequisitos">prerrequisitos</a></li> <li><a href="#_paso_1_crear_el_volumen">Paso 1: Crear el Volumen</a></li> <li><a href="#_paso_2_lanzar_el_contenedor_docker">Paso 2: Lanzar el contenedor Docker</a></li> <li><a href="#_paso_3_obtener_la_clave_pública">Paso 3 : Obtener la Clave Pública</a></li> <li><a href="#_paso_4_registrar_la_clave_en_ollama_com">Paso 4: Registrar la clave en Ollama.com</a></li> <li><a href="#_paso_5_probar_con_un_modelo_pequeño_gratuito">Paso 5 : Probar con un Modelo Pequeño Gratuito</a></li> </ul> </li> <li><a href="#_la_trampa_de_la_api_v1models">La Trampa de la API `/v1/models</a></li> <li><a href="#_resultado_dos_sesiones_dos_cuentas_cero_conflicto">Resultado : Dos Sesiones, Dos Cuentas, Cero Conflicto</a></li> <li><a href="#_lecciones_aprendidas">Lecciones Aprendidas</a></li> <li><a href="#_para_ir_más_lejos">Para ir más lejos</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 14 minutes</div> <p>Dos suscripciones Pro, una sola máquina, una sola tarjeta bancaria y cero conflictos de red. ¿Cómo Docker me permitió duplicar mi capacidad de inferencia en la nube sin comprar una segunda PC.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>Utilizo Ollama Pro desde varios meses para alimentar mis sesiones OpenCode con modelos en la nube. El truco es que incluso con una suscripción Pro, se llega rápidamente al <strong>rate limiting</strong> cuando se lanzan varios agentes en paralelo. La solución obvia: una segunda suscripción.</p> </div> <div class="paragraph"> <p>Pero ahí, es el drama.</p> </div> <div class="paragraph"> <p>Ollama identifica cada máquina mediante una clave SSH única — su famosa <strong>Device Key</strong>. Dos instancias en el mismo SO compartirían la misma identidad, y es imposible vincular dos cuentas Pro al mismo dispositivo. Y, como te imaginas, no iba a comprar otro portátil solo para eso.</p> </div> <div class="paragraph"> <p>La solución: engañar. Hacer creer a Ollama que se ejecuta en dos máquinas diferentes, cuando en realidad comparten la misma CPU, la misma RAM y la misma conexión de red. Docker nos ofrecerá una burbuja de aislamiento perfecto.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml ... ... ( skipping 130 lines ) ... skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam BoxPadding 10 skinparam DefaultFontSize 12 left to right direction node "Máquina física" { frame "Ollama Instancia A (Nativa)" as Native { database "Identidad ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml !theme plain skinparam BoxPadding 10 skinparam DefaultFontSize 12 left to right direction node "Máquina física" { frame "Ollama Instancia A (Nativa)" as Native { database "Identidad /usr/share/ollama/.ollama/id_ed25519" as KeyA portin "API :11434" as PortA } frame "Instancia Ollama B (Docker)" as Docker { database "Identidad ~/ollama-b-data/id_ed25519" as KeyB portin "API\n:11435" as PortB } } cloud "Ollama Cloud" { actor "Cuenta Pro A (email 1)" as AccountA actor "Cuenta Pro B\n(email 2)" as AccountB } KeyA --> AccountA : "Clave SSH A" KeyB --> AccountB : "Clave SSH B" PortA --> AccountA : "Consultas A" PortB --> AccountB : "Consultas B" note bottom of Docker Conteneur isolé : identité SSH distincte, port réseau distinct, volume persistant end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_dos_veces_lo_mismo">¿Por qué dos veces lo mismo?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de que me llames enfermo mental, déjame explicarte el caso de uso.</p> </div> <div class="paragraph"> <p>Con una sola suscripción Pro, puedo lanzar un modelo como`deepseek-v4-pro:cloud`dans una sesión OpenCode. El problema surge cuando quiero <strong>dos</strong> sesiones simultáneas. Los límites de rate limiting hacen que la segunda sesión se ralentice o sea rechazada directamente.</p> </div> <div class="paragraph"> <p>Con dos suscripciones Pro independientes :</p> </div> <div class="ulist"> <ul> <li> <p>Sesión OpenCode 1 → Cuenta Pro A (<code>localhost:11434</code>)</p> </li> <li> <p>Sesión OpenCode 2 → Cuenta Pro B`localhost:11435`)</p> </li> </ul> </div> <div class="paragraph"> <p>Cada sesión tiene su propia cuota, su propio contexto, y no interfiere con la otra. Es multiprocesamiento humano.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Dos suscripciones Pro = dos correos electrónicos diferentes. La misma tarjeta bancaria funciona — el sistema de pago de Ollama no bloquea las suscripciones múltiples desde el mismo medio de pago. Lo he verificado.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_corazón_del_problema_la_device_key">El corazón del problema: La Device Key</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando instalas Ollama, se genera un par de claves SSH ed25519 en el directorio de identidad :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...</code></pre> </div> </div> <div class="paragraph"> <p>Esta clave se sube a los servidores de Ollama durante el`ollama signin`. Es ella quien dice « esta máquina pertenece a esa cuenta Pro ». Si sus dos instancias comparten el mismo archivo`id_ed25519`, ellas comparten la misma identidad. Fin del juego.</p> </div> <div class="paragraph"> <p>El truco: dar a nuestra segunda instancia su propio directorio de identidad, aislado en un volumen Docker.</p> </div> </div> </div> <div class="sect1"> <h2 id="_preparación_paso_a_paso">Preparación — Paso a Paso</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prerrequisitos">prerrequisitos</h3> <div class="ulist"> <ul> <li> <p>Una instalación nativa de Ollama funcional (script oficial`curl | sh`)</p> </li> <li> <p>Docker instalado y funcional</p> </li> <li> <p>Portainer o docker-compose para el despliegue</p> </li> <li> <p>Dos cuentas Ollama con dos correos electrónicos distintos</p> </li> </ul> </div> <div class="paragraph"> <p>He utilizado la versión`0.20.2`— aquella proporcionada por el script oficial y la imagen Docker correspondiente.</p> </div> </div> <div class="sect2"> <h3 id="_paso_1_crear_el_volumen">Paso 1: Crear el Volumen</h3> <div class="paragraph"> <p>Un simple directorio en el host servirá como volumen persistente para la identidad de la instancia B :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/ollama-b-data</code></pre> </div> </div> <div class="paragraph"> <p>Este directorio se montará en el contenedor Docker como`/root/.ollama`, donde Ollama almacena sus claves de identidad, su historial y sus modelos.</p> </div> </div> <div class="sect2"> <h3 id="_paso_2_lanzar_el_contenedor_docker">Paso 2: Lanzar el contenedor Docker</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># docker-compose.yml services: ollama-instance-b: image: ollama/ollama:0.20.2 container_name: ollama-instance-b ports: - "11435:11434" volumes: - /home/cheroliv/ollama-b-data:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0 restart: always</code></pre> </div> </div> <div class="paragraph"> <p>Lo que está pasando aquí:</p> </div> <div class="ulist"> <ul> <li> <p>El puerto<strong>11435</strong>del host está mapeado al<strong>11434</strong>interno del contenedor. Así, la instancia Docker escucha en`:11435`sin conflicto con la instancia nativa que ocupa`:11434`.</p> </li> <li> <p>El volumen`~/ollama-b-data`está montado sobre`/root/.ollama`— aquí es donde se almacenará la identidad SSH.</p> </li> <li> <p>`OLLAMA_HOST=0.0.0.0`permite al contenedor aceptar conexiones externas.</p> </li> </ul> </div> <div class="paragraph"> <p>He desplegado esta pila mediante Portainer, pero un simple`docker compose up -d`funciona también bien.</p> </div> </div> <div class="sect2"> <h3 id="_paso_3_obtener_la_clave_pública">Paso 3 : Obtener la Clave Pública</h3> <div class="paragraph"> <p>Al estar el contenedor vacío en el primer arranque, Ollama genera automáticamente una nueva pareja de claves SSH en el volumen. Se recupera la clave pública :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b cat /root/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ+dvnfmuo49q5O8LOlvgZ39SKORFw47ry9k4H2jPc</code></pre> </div> </div> <div class="paragraph"> <p>Compruebo que esta clave es <strong>diferente</strong> de la instancia nativa:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Instance native $ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGyF...(différente) # Instance Docker $ cat ~/ollama-b-data/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ...(différente)</code></pre> </div> </div> <div class="paragraph"> <p>Dos llaves distintas, dos identidades separadas. El truco está hecho.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Si su contenedor se reinicia, <strong>reutiliza</strong> las claves presentes en el volumen. La identidad es persistente. No perderá la asociación con la cuenta Pro.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_paso_4_registrar_la_clave_en_ollama_com">Paso 4: Registrar la clave en Ollama.com</h3> <div class="paragraph"> <p>Dirección <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → Añadir clave SSH. Se pega la clave pública de la instancia Docker y se valida.</p> </div> <div class="paragraph"> <p>Luego, se vincula esta identidad a la cuenta Pro B :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin</code></pre> </div> </div> <div class="paragraph"> <p>Se abre el navegador, nos conectamos con el correo electrónico de la cuenta B, y el token se asocia a la clave SSH del contenedor. Comprobamos que todo esté OK:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin User: cherolivpro</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_paso_5_probar_con_un_modelo_pequeño_gratuito">Paso 5 : Probar con un Modelo Pequeño Gratuito</h3> <div class="paragraph"> <p>Antes de lanzar el precio de una suscripción Pro, quiero estar seguro de que el tubo funcione. Hago un pull de un modelo local pequeño y gratuito para validar la conectividad :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull qwen3:0.6b pulling manifest pulling 7f4030143c1c: 100% ▕██████████████████▏ 522 MB success $ curl -s http://localhost:11435/api/tags {"models":[{"name":"qwen3:0.6b","model":"qwen3:0.6b",...}]}</code></pre> </div> </div> <div class="paragraph"> <p>El puerto`11435`responde, el modelo está servido. La instancia B está viva.</p> </div> <div class="paragraph"> <p>Una vez tranquilo, paso al pull del verdadero modelo cloud Pro:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull deepseek-v4-pro:cloud pulling manifest pulling 31c3059e137e: 100% ▕██████████████████▏ 344 B success</code></pre> </div> </div> <div class="paragraph"> <p>344 bytes para el manifiesto de un modelo en la nube — normal, la inferencia se realiza del lado del servidor, no localmente. Y aquí está la prueba definitiva:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl -s http://localhost:11435/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4-pro:cloud","messages":[{"role":"user","content":"Dis bonjour en une phrase courte."}]}' { "id": "chatcmpl-480", "model": "deepseek-v4-pro", "choices": [{ "message": { "content": "Bonjour !" }, "finish_reason": "stop" }], "usage": { "total_tokens": 181 } }</code></pre> </div> </div> <div class="paragraph"> <p>Hola también para ti, instancia B.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_trampa_de_la_api_v1models">La Trampa de la API `/v1/models</h2> <div class="sectionbody"> <div class="paragraph"> <p>He perdido 20 minutos en un detalle tonto. Cuando he configurado el proveedor`ollama-b`en OpenCode, nada aparecía en el selector de modelos. Nada. Nada de nada.</p> </div> <div class="paragraph"> <p>¿La razón? L’API`/v1/models`de la instancia B devolvía`{"object":"list","data":null}`en lugar de`{"object":"list","data":[]}`quand ningún modelo estaba siendo tirado. El valor`null`en OpenCode, provocaba un fallo en el análisis, que no mostraba el proveedor.</p> </div> <div class="paragraph"> <p>La solución: declarar los modelos <strong>explicitamente</strong> en la configuración de OpenCode en lugar de depender del descubrimiento dinámico.</p> </div> <div class="listingblock"> <div class="title">~/.config/opencode/opencode.json</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "gemma4:e2b": { "name": "Gemma 4 E2B (local)" } } }, "ollama-b": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Instance B (Docker)", "options": { "baseURL": "http://localhost:11435/v1" }, "models": { "qwen3:0.6b": { "name": "Qwen3 0.6B (B)" }, "deepseek-v4-pro:cloud": { "name": "DeepSeek V4 Pro (B)" } } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Con esta declaración explícita, OpenCode ve inmediatamente al provider B y sus modelos. Un reinicio de sesión, y el selector`/models`muestra las dos instancias una al lado de la otra.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Si no ves tu proveedor personalizado en`/models`, no pierdas tres horas reiniciando tu terminal. Declara los modelos manualmente en`opencode.json`— esto resuelve el problema instantáneamente.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_resultado_dos_sesiones_dos_cuentas_cero_conflicto">Resultado : Dos Sesiones, Dos Cuentas, Cero Conflicto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Al final, puedo lanzar dos sesiones OpenCode simultáneamente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Session 1 → /models → Ollama (local) → deepseek-v4-pro:cloud → Compte A Session 2 → /models → Ollama Instance B (Docker) → deepseek-v4-pro:cloud → Compte B</code></pre> </div> </div> <div class="paragraph"> <p>Cada sesión tiene su propio quota, su propio límite de tasa, y no se pisotean los pies. La misma máquina, la misma tarjeta azul, dos correos electrónicos diferentes.</p> </div> <div class="paragraph"> <p>¿Y lo mejor? El contenedor Docker está en`restart: always`. Sobrevive a los reinicios del sistema sin intervención manual.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas">Lecciones Aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker aísla todo, incluso la identidad</strong>— Un simple bind mount de volumen es suficiente para dar a un contenedor su propio conjunto de claves SSH, haciéndolo indistinguible de una máquina física diferente a los ojos de Ollama.</p> </li> <li> <p><strong>Dos correos electrónicos, misma CB</strong>— Ollama no bloque las suscripciones múltiples desde el mismo medio de pago. Solo el correo electrónico debe ser distinto.</p> </li> <li> <p><strong>Probar gratis antes de pagar</strong> — Un <code>ollama pull qwen3:0.6b</code> (modèle libre, 522 Mo) permet de valider toute la chaîne réseau sans débourser un centime. Vous validez le plomberie d’abord, vous activez le Pro ensuite.</p> </li> <li> <p><strong>/v1/models` con <code>data: null</code> rompe OpenCode</strong>— Si configuras un proveedor personalizado con`"models": {}`, OpenCode intenta descubrir los modelos a través de la API. Si la API responde`data: null`, el proveedor no aparece. Declara los modelos explícitamente.</p> </li> <li> <p><strong>Dos cuentas, es multi-procesamiento humano</strong>— Una cuenta Pro = una sesión OpenCode activa. Dos cuentas = dos sesiones paralelas. Para alguien que está manejando varios proyectos Gradle simultáneamente, es un cambio de juego.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Ajustes de Ollama — Gestión de claves SSH</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Documentación oficial Ollama</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Imagen Docker Ollama en Docker Hub</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Proveedor de configuración Ollama</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Artículo publicado el 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com//blog/2025/0080_kitty_term_post.html Thu, 7 May 2026 00:00:00 +0000 blog/2025/0080_kitty_term_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_por_qué_elegir_kitty_y_zsh">¿Por qué elegir Kitty y Zsh?</a></li> <li><a href="#_requisitos_del_sistema">Requisitos del sistema</a></li> <li><a href="#_descarga_e_instalación_de_kitty">Descarga e instalación de Kitty</a> <ul class="sectlevel2"> <li><a href="#_descargar_el_script_de_instalación">Descargar el script de instalación</a></li> <li><a href="#_creación_de_los_enlaces_simbólicos">Creación de los enlaces simbólicos</a></li> </ul> </li> <li><a href="#_integración_de_kitty_en_xubuntu">Integración de Kitty en Xubuntu</a> <ul class="sectlevel2"> <li><a href="#_copiar_el_archivo_desktop">Copiar el archivo desktop</a></li> <li><a href="#_modificar_el_archivo_desktop">Modificar el archivo desktop</a></li> <li><a href="#_asociar_kitty_como_terminal_por_defecto_opcional">Asociar Kitty como terminal por defecto (opcional)</a></li> </ul> </li> <li><a href="#_instalación_de_zsh">Instalación de Zsh</a></li> <li><a href="#_establecer_zsh_como_shell_predeterminado">Establecer Zsh como shell predeterminado</a> <ul class="sectlevel2"> <li><a href="#_método_global_para_todos_los_terminales">Método global (para todos los terminales)</a></li> <li><a href="#_método_específico_para_kitty">Método específico para Kitty</a></li> </ul> </li> <li><a href="#_configuración_de_zsh_opcional">Configuración de Zsh (opcional)</a> <ul class="sectlevel2"> <li><a href="#_crear_un_archivo_zshrc">Crear un archivo .zshrc</a></li> <li><a href="#_ejemplo_de_configuración_mínima">Ejemplo de configuración mínima</a></li> </ul> </li> <li><a href="#_resumen_del_workflow_completo">Resumen del workflow completo</a></li> <li><a href="#_verificación_final">Verificación final</a> <ul class="sectlevel2"> <li><a href="#_abrir_el_archivo_de_configuración">📂 Abrir el archivo de configuración</a></li> <li><a href="#_️_agregar_o_modificar_font_size">🖋️ Agregar o modificar `font_size</a></li> <li><a href="#_guardar_y_reiniciar_kitty">💾 Guardar y reiniciar Kitty</a></li> <li><a href="#_ajuste_dinámico_zoom_temporal">�✅ Ajuste dinámico (Zoom temporal)</a></li> </ul> </li> <li><a href="#_instalación_y_configuración_de_oh_my_zsh">Instalación y configuración de Oh My Zsh</a> <ul class="sectlevel2"> <li><a href="#_instalación_de_oh_my_zsh">Instalación de Oh My Zsh</a></li> <li><a href="#_cambiar_el_tema">Cambiar el tema</a></li> <li><a href="#_verificación">Verificación</a></li> <li><a href="#_diagrama_de_caso_de_uso">Diagrama de caso de uso</a></li> </ul> </li> <li><a href="#_activar_la_translucididad_en_kitty">Activar la translucididad en Kitty</a> <ul class="sectlevel2"> <li><a href="#_prerequisitos_para_la_transparencia">Prerequisitos para la transparencia</a></li> <li><a href="#_configuración_de_la_transparencia_en_kitty_conf">Configuración de la transparencia en kitty.conf</a></li> <li><a href="#_reiniciar_kitty">Reiniciar Kitty</a></li> <li><a href="#_complementos_posibles">Complementos posibles</a></li> <li><a href="#_diagrama_de_secuencia_inicialización_de_kitty_con_transparencia">Diagrama de secuencia - Inicialización de Kitty con transparencia</a></li> <li><a href="#_limitaciones_conocidas">Limitaciones conocidas</a></li> </ul> </li> <li><a href="#_desactivar_el_pitido_audible_audible_bell">Desactivar el pitido audible (audible bell)</a></li> <li><a href="#_actualización_de_kitty">Actualización de Kitty</a></li> <li><a href="#_referencias">Referencias</a></li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Esta guía explica paso a paso cómo instalar el terminal <strong>kitty</strong> en Xubuntu, configurarlo correctamente y reemplazar bash por <strong>zsh</strong> como shell predeterminado. El proyecto kitty está disponible aquí: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a>.</p> </div> <div class="paragraph"> <p><em>__</em> Kitty es un terminal moderno, rápido y configurable, especialmente adecuado para desarrolladores exigentes. </think></p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_elegir_kitty_y_zsh">¿Por qué elegir Kitty y Zsh?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty se distingue por :</p> </div> <div class="ulist"> <ul> <li> <p>Un rendimiento superior gracias a la aceleración GPU,</p> </li> <li> <p>Una configuración totalmente basada en un texto único,</p> </li> <li> <p>Un excelente soporte para fuentes y ligaduras.</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh es, por su parte, un shell interactivo potente que ofrece:</p> </div> <div class="ulist"> <ul> <li> <p>Una completación inteligente,</p> </li> <li> <p>Un prompt personalizable,</p> </li> <li> <p>Una gran compatibilidad con bash.</p> </li> </ul> </div> <div class="paragraph"> <p>Al combinar Kitty y Zsh, obtienes un entorno productivo y estético.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/kitty-zsh-overview.png" alt="kitty zsh overview" width="729" height="305"> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Esta guía está intencionalmente limitada a la instalación mediante script y a Xubuntu.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_requisitos_del_sistema">Requisitos del sistema</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de comenzar, asegúrate de tener:</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu instalado,</p> </li> <li> <p>un acceso a internet,</p> </li> <li> <p>un shell bash funcional para lanzar el script.</p> </li> </ul> </div> <div class="paragraph"> <p>Verifique su entorno :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">uname -a lsb_release -a</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_descarga_e_instalación_de_kitty">Descarga e instalación de Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty recomienda instalarlo mediante un script oficial que coloca los archivos en`~/.local/kitty.app`.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Este método es independiente de los gestores de paquetes (sin`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_descargar_el_script_de_instalación">Descargar el script de instalación</h3> <div class="paragraph"> <p>Ejecute el siguiente comando:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>Este comando realiza:</p> </div> <div class="ulist"> <ul> <li> <p>descarga de los binarios,</p> </li> <li> <p>extracción en`~/.local/kitty.app`,</p> </li> <li> <p>creación de enlaces simbólicos</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/download-install.svg" alt="download install" width="289" height="336"> </div> </div> </div> <div class="sect2"> <h3 id="_creación_de_los_enlaces_simbólicos">Creación de los enlaces simbólicos</h3> <div class="paragraph"> <p>Para poder invocar`kitty`desde el terminal, cree un enlace simbólico :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/kitty</code></pre> </div> </div> <div class="paragraph"> <p>Agregue`~/.local/bin`añadir a tu PATH si aún no lo has hecho :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>Puedes verificar la instalación:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty --version</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integración_de_kitty_en_xubuntu">Integración de Kitty en Xubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que Kitty aparezca en el menú de aplicaciones :</p> </div> <div class="sect2"> <h3 id="_copiar_el_archivo_desktop">Copiar el archivo desktop</h3> <div class="paragraph"> <p>Copie el archivo`.desktop`proporcionado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_modificar_el_archivo_desktop">Modificar el archivo desktop</h3> <div class="paragraph"> <p>Edite el archivo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.local/share/applications/kitty.desktop</code></pre> </div> </div> <div class="paragraph"> <p>Verifique o modifique las siguientes líneas:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Desktop Entry] Version=1.0 Type=Application Name=Kitty Terminal Comment=Fast GPU-based terminal emulator Exec=/home/$USER/.local/kitty.app/bin/kitty Icon=kitty Categories=System;TerminalEmulator;</code></pre> </div> </div> <div class="paragraph"> <p>Reemplacen`YOURUSER`por su nombre de usuario</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/desktop-integration.png" alt="desktop integration" width="455" height="335"> </div> </div> </div> <div class="sect2"> <h3 id="_asociar_kitty_como_terminal_por_defecto_opcional">Asociar Kitty como terminal por defecto (opcional)</h3> <div class="paragraph"> <p>Para que Kitty sea el terminal iniciado por defecto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator ~/.local/kitty.app/bin/kitty 50 sudo update-alternatives --config x-terminal-emulator</code></pre> </div> </div> <div class="paragraph"> <p>Seleccione`kitty`en el menú propuesto.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_instalación_de_zsh">Instalación de Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si Zsh aún no está instalado, ejecute:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install zsh</code></pre> </div> </div> <div class="paragraph"> <p>Comprueba la instalación:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">zsh --version</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_establecer_zsh_como_shell_predeterminado">Establecer Zsh como shell predeterminado</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puedes cambiar tu shell globalmente o solo en Kitty.</p> </div> <div class="sect2"> <h3 id="_método_global_para_todos_los_terminales">Método global (para todos los terminales)</h3> <div class="paragraph"> <p>Identifica el camino absoluto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">which zsh</code></pre> </div> </div> <div class="paragraph"> <p>En general`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>Modifica el shell predeterminado:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">chsh -s /usr/bin/zsh</code></pre> </div> </div> <div class="paragraph"> <p>Desconéctese y reconéctese.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/zsh-default-shell.svg" alt="zsh default shell" width="546" height="341"> </div> </div> </div> <div class="sect2"> <h3 id="_método_específico_para_kitty">Método específico para Kitty</h3> <div class="paragraph"> <p>Si prefieres solo cambiar el shell en Kitty, edita el archivo de configuración:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Agrega esta línea :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">shell zsh</code></pre> </div> </div> <div class="paragraph"> <p>Guarda y reinicia Kitty.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_de_zsh_opcional">Configuración de Zsh (opcional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para personalizar tu Zsh :</p> </div> <div class="sect2"> <h3 id="_crear_un_archivo_zshrc">Crear un archivo .zshrc</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">touch ~/.zshrc nano ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_ejemplo_de_configuración_mínima">Ejemplo de configuración mínima</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export ZSH_THEME="robbyrussell" export PATH="$HOME/.local/bin:$PATH" alias ll="ls -la"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_resumen_del_workflow_completo">Resumen del workflow completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>El esquema siguiente resume todo el proceso :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/full-workflow.png" alt="full workflow" width="358" height="643"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificación_final">Verificación final</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lanza Kitty :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> <div class="paragraph"> <p>Deberías ver que`zsh`está activo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $SHELL</code></pre> </div> </div> <div class="paragraph"> <p>Resultado esperado :</p> </div> <div class="paragraph"> <p>/usr/bin/zsh</p> </div> <div class="paragraph"> <p>Para modificar el tamaño de la fuente en<strong>Kitty</strong>, hay que ajustar el parámetro`font_size`en el archivo de configuración. Aquí está el procedimiento detallado:</p> </div> <div class="sect2"> <h3 id="_abrir_el_archivo_de_configuración">📂 Abrir el archivo de configuración</h3> <div class="paragraph"> <p>El archivo de configuración principal se encuentra normalmente en:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Si este archivo no existe todavía, puedes crearlo. Ejemplo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_️_agregar_o_modificar_font_size">🖋️ Agregar o modificar `font_size</h3> <div class="paragraph"> <p>Agregue la siguiente directiva, o modifíquela si ya existe:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">font_size 14.0</code></pre> </div> </div> <div class="paragraph"> <p>Aquí`14.0`corresponde al tamaño deseado. Puedes poner cualquier valor decimal, por ejemplo`12.0`, <code>15.5</code>, etc.</p> </div> </div> <div class="sect2"> <h3 id="_guardar_y_reiniciar_kitty">💾 Guardar y reiniciar Kitty</h3> <div class="ulist"> <ul> <li> <p>Guarde`Ctrl + O`, luego`Entrée`) y salgan (<code>Ctrl + X</code>) si utilizas`nano`.</p> </li> <li> <p>Cierra todas las ventanas de Kitty, luego reinicia el terminal para que el cambio surta efecto.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_ajuste_dinámico_zoom_temporal">�✅ Ajuste dinámico (Zoom temporal)</h3> <div class="paragraph"> <p>Si desea hacer zoom adelante/atrás temporalmente sin modificar la configuración, utilice los atajos de teclado predeterminados:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Aumentar el tamaño de la fuente</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Disminuir el tamaño de la fuente</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Restablecer el tamaño</strong> :</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>Estos ajustes no persisten después del cierre del terminal.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_instalación_y_configuración_de_oh_my_zsh">Instalación y configuración de Oh My Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una vez que Zsh esté instalado y configurado como shell predeterminado, puede enriquecer su entorno con <strong>Oh My Zsh</strong>, un framework de gestión de la configuración Zsh, que ofrece:</p> </div> <div class="ulist"> <ul> <li> <p>una colección de temas para el prompt,</p> </li> <li> <p>muchos plugins,</p> </li> <li> <p>una organización clara de la configuración</p> </li> </ul> </div> <div class="sect2"> <h3 id="_instalación_de_oh_my_zsh">Instalación de Oh My Zsh</h3> <div class="paragraph"> <p>Asegúrate de que Zsh esté activo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh --version</code></pre> </div> </div> <div class="paragraph"> <p>Si es necesario, lanza:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh</code></pre> </div> </div> <div class="paragraph"> <p>Luego descargue y ejecute el script de instalación oficial</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"</code></pre> </div> </div> <div class="paragraph"> <p>Este script:</p> </div> <div class="ulist"> <ul> <li> <p>crea la carpeta`~/.oh-my-zsh`,</p> </li> <li> <p>guarda posiblemente su archivo`~/.zshrc`,</p> </li> <li> <p>activa automáticamente el nuevo prompt.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_cambiar_el_tema">Cambiar el tema</h3> <div class="paragraph"> <p>Abre tu archivo de configuración:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>Modifica la variable`ZSH_THEME`para elegir otro tema (por ejemplo`agnoster`) :</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster</p> </div> <div class="paragraph"> <p>Guarde y luego vuelva a cargar la configuración:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">source ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_verificación">Verificación</h3> <div class="paragraph"> <p>Inicia Kitty y verifica que el prompt haya cambiado correctamente. Puedes confirmar que Oh My Zsh está activo ejecutando :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $ZSH</code></pre> </div> </div> <div class="paragraph"> <p>El resultado debería ser similar a :</p> </div> <div class="paragraph"> <p>/home/su_usuario/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_caso_de_uso">Diagrama de caso de uso</h3> <div class="imageblock"> <div class="content"> <img src="./images/ohmyzsh-installation.png" alt="ohmyzsh installation" width="540" height="480"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_activar_la_translucididad_en_kitty">Activar la translucididad en Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una de las funcionalidades más apreciadas de Kitty es la posibilidad de añadir <strong>transparencia</strong> al fondo del terminal. Esto permite ver ligeramente el entorno subyacente (ventana, escritorio, etc.), lo cual es particularmente útil para multitarea.</p> </div> <div class="sect2"> <h3 id="_prerequisitos_para_la_transparencia">Prerequisitos para la transparencia</h3> <div class="paragraph"> <p>La transparencia en Kitty se basa en el<strong>compositor de ventanas</strong>utilizado por el entorno gráfico. En Xubuntu (basado en XFCE), asegúrese de que la<strong>composition está activada</strong>.</p> </div> <div class="ulist"> <div class="title">Por verificar :</div> <ul> <li> <p>clic derecho en el escritorio > Configuración ><strong>Configuración del gestor de ventanas</strong>,</p> </li> <li> <p>pestaña<strong>compositor</strong>: la casilla <strong>"Activar la composición"</strong> debe estar marcada.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/transparency-usecase.png" alt="transparency usecase" width="587" height="226"> </div> </div> </div> <div class="sect2"> <h3 id="_configuración_de_la_transparencia_en_kitty_conf">Configuración de la transparencia en kitty.conf</h3> <div class="paragraph"> <p>Abra su archivo de configuración`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Agrega o modifica las siguientes líneas:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background_opacity 0.85</code></pre> </div> </div> <div class="paragraph"> <p>Este parámetro acepta valores entre :</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ opaco (ninguna transparencia),</p> </li> <li> <p><code>0.0</code>→ totalmente transparente (inutilizable),</p> </li> <li> <p>valores intermedios como`0.90`, <code>0.75</code>, etc.</p> </li> </ul> </div> <div class="paragraph"> <p>Un buen compromiso visual está generalmente entre`0.85` et <code>0.95</code>.</p> </div> </div> <div class="sect2"> <h3 id="_reiniciar_kitty">Reiniciar Kitty</h3> <div class="paragraph"> <p>Cierre todas las instancias de Kitty, luego reinicie una nueva ventana para que los cambios surtan efecto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_complementos_posibles">Complementos posibles</h3> <div class="paragraph"> <p>Si utilizas un fondo de terminal personalizado, también puedes definir un color de fondo con transparencia (en RGBA) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background #1e1e2eff</code></pre> </div> </div> <div class="paragraph"> <p>La última componente (<code>ff</code>) indica la opacidad (de`00` à <code>ff</code>)</p> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_secuencia_inicialización_de_kitty_con_transparencia">Diagrama de secuencia - Inicialización de Kitty con transparencia</h3> <div class="imageblock"> <div class="content"> <img src="./images/transparency-sequence.png" alt="transparency sequence" width="785" height="422"> </div> </div> </div> <div class="sect2"> <h3 id="_limitaciones_conocidas">Limitaciones conocidas</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>La translucididad no funciona si : - el compositor XFCE está desactivado, - un gestor de ventanas incompatible es utilizzato, </think> - un gestor de ventanas incompatible es utilized, Note: I accidentally typed Italian; correcting: - un gestor de ventanas incompatible es utilizado, Now final correct: - un gestor de ventanas incompatible es utilizado, - estás utilizando Kitty en modo <strong>tmux</strong> en segundo plano sin soporte para transparencia.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_desactivar_el_pitido_audible_audible_bell">Desactivar el pitido audible (audible bell)</h2> <div class="sectionbody"> <div class="paragraph"> <p>De forma predeterminada, Kitty emite un sonido de <code>bip</code> cuando se ingresa un comando erróneo o cuando un evento terminal lo activa. Este ruido puede resultar rápidamente molesto, especialmente en un entorno de desarrollo intensivo.</p> </div> <div class="paragraph"> <p>Para desactivar este comportamiento, agregue la siguiente directiva al archivo`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">audible_bell no</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>También puede activar un <strong>retorno visual</strong> en lugar del pitido sonoro con:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">visual_bell yes</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_actualización_de_kitty">Actualización de Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Como Kitty se instala mediante un script y no mediante un gestor de paquetes, la actualización se realiza volviendo a ejecutar el script de instalación oficial. Esto permite descargar la última versión y actualizar su instalación existente en`~/.local/kitty.app`.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>El sufijo`.app`en el camino`~/.local/kitty.app`es la convención de instalación de Kitty en Linux mediante su script oficial, y en ningún caso indica una compatibilidad exclusiva con macOS.</p> </div> </td> </tr> </table> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Antes de ejecutar el comando de actualización, asegúrate de estar en tu directorio personal (<code>~</code>).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Ejecuta el siguiente comando desde tu directorio personal :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>Este script se encargará de :</p> </div> <div class="ulist"> <ul> <li> <p>Descargar los binarios de la nueva versión.</p> </li> <li> <p>Extraer los archivos en`~/.local/kitty.app`.</p> </li> <li> <p>Actualizar los enlaces simbólicos si es necesario.</p> </li> </ul> </div> <div class="paragraph"> <p>Después de la actualización, se recomienda cerrar todas las instancias de Kitty y reiniciarlas para asegurarse de que la nueva versión se aplique correctamente.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si desea profundizar en la personalización, consulte la documentación oficial:</p> </div> <div class="ulist"> <ul> <li> <p>Kitty: <a href="https://sw.kovidgoyal.net/kitty/" class="bare">https://sw.kovidgoyal.net/kitty/</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p>Github: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p><a href="https://ohmyz.sh/" class="bare">https://ohmyz.sh/</a></p> </li> <li> <p><a href="https://github.com/ohmyzsh/ohmyzsh/wiki" class="bare">https://github.com/ohmyzsh/ohmyzsh/wiki</a></p> </li> <li> <p><a href="https://docs.xfce.org/xfce/xfwm4/compositor" class="bare">https://docs.xfce.org/xfce/xfwm4/compositor</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ahora dispone de:</p> </div> <div class="ulist"> <ul> <li> <p>de un terminal moderno y de alto rendimiento (Kitty)</p> </li> <li> <p>de un shell potente y personalizable (Zsh)</p> </li> <li> <p>de una configuración limpia e independiente de los paquetes del sistema</p> </li> <li> <p>de un terminal estético y funcional equipado con Oh My Zsh</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html Wed, 6 May 2026 00:00:00 +0000 blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_contexto_un_mercado_que_ha_basculé">El Contexto: Un Mercado Que Ha Basculé</a></li> <li><a href="#_el_panel_de_las_opciones">El Panel de las Opciones</a> <ul class="sectlevel2"> <li><a href="#_lo_que_he_excluido_y_por_qué">lo que he excluido (y por qué)</a></li> </ul> </li> <li><a href="#_inferencia_simple_la_muerte_del_hardware_local">Inferencia simple: La muerte del hardware local</a> <ul class="sectlevel2"> <li><a href="#_el_cálculo">El cálculo</a></li> <li><a href="#_incluso_con_un_uso_intensivo">Incluso con un Uso Intensivo</a></li> </ul> </li> <li><a href="#_fine_tuning_el_cloud_es_imbatible">Fine-Tuning : el cloud es imbatible</a> <ul class="sectlevel2"> <li><a href="#_el_costo_real_de_un_fine_tune">El Costo Real de un Fine-Tune</a></li> <li><a href="#_los_actores_especializados">Los Actores Especializados</a></li> </ul> </li> <li><a href="#_la_única_verdadera_razón_la_soberanía_de_los_datos">La Única Verdadera Razón: La Soberanía de los Datos</a> <ul class="sectlevel2"> <li><a href="#_el_verdadero_cálculo_de_la_confidencialidad">El verdadero cálculo de la confidencialidad</a></li> </ul> </li> <li><a href="#_síntesis_la_matriz_de_decisión">Síntesis : La Matriz de Decisión</a></li> <li><a href="#_el_caso_particular_la_suscripción_pro_ante_los_modelos_chinos">El Caso Particular: La Suscripción Pro Ante los Modelos Chinos</a> <ul class="sectlevel2"> <li><a href="#_por_qué_los_modelos_chinos_cambian_todo">Por qué los modelos chinos cambian todo</a></li> <li><a href="#_lo_que_eso_significa_para_el_hardware">lo que eso significa para el hardware</a></li> </ul> </li> <li><a href="#_y_huawei">Y Huawei?</a></li> <li><a href="#_conclusión_el_lujo_de_la_proximidad">Conclusión: El lujo de la proximidad</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 14 minutes</div> <p>NVIDIA vende el DGX Spark como un « supercomputador IA de escritorio » a $4 699. Ollama ofrece sus modelos en la nube a $20/mes. Un H100 se alquila a $1.38/h en Vast.ai. Y los modelos de código abierto chinos — DeepSeek, Qwen, GLM — están disponibles en todas partes, gratuitamente, sin tener que comprar una tarjeta. Entonces, ¿para qué sirve exactamente este Spark? Hice los cálculos.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">TOC</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_contexto_un_mercado_que_ha_basculé">El Contexto: Un Mercado Que Ha Basculé</h2> <div class="sectionbody"> <div class="paragraph"> <p>En mayo de 2026, el panorama de la IA cambió radicalmente respecto al anuncio del DGX Spark en el CES 2025. Tres fuerzas convergieron para hacer que el hardware local sea cada vez más difícil de justificar:</p> </div> <div class="ulist"> <ul> <li> <p><strong>El colapso de los precios del cloud GPU</strong>: un H100 se alquila entre $1.38 y $3/h, frente a $5-8/h hace 18 meses</p> </li> <li> <p><strong>La explosión de los modelos chinos de código abierto</strong>: DeepSeek-V4, Qwen-3, GLM-5 son competitivos con los modelos occidentales, disponibles gratuitamente</p> </li> <li> <p><strong>El aumento de las plataformas de inferencia gestionada</strong>: Ollama, Groq, Together AI ofrecen API a precios agresivos, con niveles gratuitos generosos</p> </li> </ul> </div> <div class="paragraph"> <p>El DGX Spark, anunciado a $2 999 y luego aumentado a $4 699, llega a un mundo que ya no lo necesita.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_panel_de_las_opciones">El Panel de las Opciones</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estas son las soluciones disponibles en mayo de 2026 para ejecutar LLMs, de la más ligera a la más pesada:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Opción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / Capacidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelos accesibles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">restricción principal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama gratis</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/mes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nube ligera</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos públicos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Uso limitado, 1 modelo simultáneo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Claude Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mes (~$240/año)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (API cerrada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sólo Claude 4.x</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelo único, no es open-source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mes (~$200/año)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Medio en la nube</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos públicos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 modelos simultáneos máximo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Max</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$100/mes (~$1 200/año)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nube pesada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos públicos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">10 modelos simultáneos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>GPU en la nube (H100)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$1.38-3/h</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">80 Go HBM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos, fine-tuning</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Facturación por hora, configuración requerida</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>DGX Spark</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 (compra)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <128 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lento (~10x menos que un H100), fijo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mac Studio M3 Ultra</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~$5 000+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">192 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <192 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No CUDA, ecosistema MLX</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Los precios de GPU en la nube citados son los de Vast.ai y RunPod en mayo de 2026 — spot/on-demand, no reservado. Los precios de los hiperescaladores (AWS, GCP, Azure) siguen siendo 2-3 veces más altos.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_lo_que_he_excluido_y_por_qué">lo que he excluido (y por qué)</h3> <div class="paragraph"> <p>He excluido deliberadamente las siguientes opciones de este benchmark:</p> </div> <div class="ulist"> <ul> <li> <p><strong>API OpenAI / Anthropic / Google</strong>: el tema aquí es hacer funcionar modelos <strong>open-source</strong> que se pueden elegir, ajustar, y no depender de un solo proveedor</p> </li> <li> <p><strong>Huawei Ascend / Atlas</strong> : Huawei ne commercialise pas d’équivalent desktop au DGX Spark. La gamme Ascend (910C, 910D) et Atlas (300I Duo, 350) est orientée datacenter — cartes PCIe, serveurs rack — pas des boîtiers compacts prêts à brancher. La puce Ascend 910C embarque 128 Go HBM mais c’est une puce serveur, pas un système autonome. L’Atlas 300I Duo offre 96 Go pour ~$1 400 mais nécessite une machine hôte</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_inferencia_simple_la_muerte_del_hardware_local">Inferencia simple: La muerte del hardware local</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comencemos por el caso de uso más común: chatear con un LLM, hacer una revisión de código, generar texto. No hay fine-tuning, no hay batch processing, solo inferencia interactiva.</p> </div> <div class="sect2"> <h3 id="_el_cálculo">El cálculo</h3> <div class="paragraph"> <p>Un DGX Spark a $4,699. Dividamos por el costo anual de cada suscripción:</p> </div> <div id="diag-breakeven" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Umbral de Rentabilidad — DGX Spark ($4 699) vs Suscripciones rectangle "DGX Spark $4 699" as spark #FFCDD2 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Umbral de Rentabilidad — DGX Spark ($4 699) vs Suscripciones rectangle "DGX Spark $4 699" as spark #FFCDD2 rectangle "Ollama Pro $200/a" as opro #C8E6C9 rectangle "Claude Pro $240/año" as cpro #C8E6C9 rectangle "Ollama Max $1.200/año" as omax #FFF9C4 rectangle "Cloud H100 $3/h × 10h/semana" as cloud #BBDEFB spark --> opro : 23.5 années ⏳ spark --> cpro : 19.6 années ⏳ spark --> omax : 3.9 années spark --> cloud : 3.0 années (à 10h/semaine, intermittent) note bottom of spark Sans compter l'électricité (~$150/an) Sans compter l'obsolescence hardware Sans compter qu'il est 10x plus lent end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El veredicto es brutal. Para la inferencia :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>: necesitarías<strong>23 años</strong>para amortizar un DGX Spark. El Spark será obsoleto desde hace 20 años.</p> </li> <li> <p><strong>Ollama Max</strong>:<strong>4 años</strong>— a condición de usar el Spark 24/7, lo que nadie hace</p> </li> <li> <p><strong>Claude Pro</strong>: mismo problema,<strong>20 años</strong>para el single-model cerrado</p> </li> </ul> </div> <div class="paragraph"> <p>(Empty output) La promesa del « supercomputador de IA de escritorio » se encuentra con una realidad contable elemental: $4 699 / $20 por mes = nunca rentable para un uso individual. (blank)</p> </div> </div> <div class="sect2"> <h3 id="_incluso_con_un_uso_intensivo">Incluso con un Uso Intensivo</h3> <div class="paragraph"> <p>Tomemos el peor escenario para la nube: ejecutas un H100 8 h/día, 5 días/semana, 52 semanas/año.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2 080 horas/año</p> </li> <li> <p>2 080 × $2/h (precio medio spot H100) =<strong>$4.160/año</strong></p> </li> </ul> </div> <div class="paragraph"> <p>El Spark ($4 699) se amortiza en<strong>13 meses</strong>. Excepto que :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>El H100 es<strong>~10x más rápido</strong>que el GB10 de Spark. Usted hace en 1h lo que Spark hace en 10h. Para el mismo volumen de trabajo, el H100 le cuesta $416/año, no $4 160.</p> </li> <li> <p>Le H100 a 80 Go HBM à 3.35 To/s de bande passante. Le Spark a 128 Go LPDDR5X à 273 Go/s. Pour les gros modèles, la bande passante compte plus que la capacité.</p> </li> </ol> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Comparar 1h de H100 con 1h de Spark no tiene sentido. El H100 hace el trabajo 10x más rápido. El verdadero costo en la nube para una carga de trabajo dada es, por lo tanto, ~10x inferior al cálculo ingenuo basado en las horas.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fine_tuning_el_cloud_es_imbatible">Fine-Tuning : el cloud es imbatible</h2> <div class="sectionbody"> <div class="paragraph"> <p>El argumento clásico de los defensores de Spark : «sí, pero para el fine-tuning es diferente</p> </div> <div class="paragraph"> <p>No, no lo es.</p> </div> <div class="sect2"> <h3 id="_el_costo_real_de_un_fine_tune">El Costo Real de un Fine-Tune</h3> <div class="paragraph"> <p>Un fine-tune LoRA/QLoRA sobre Unsloth de un modelo 7B :</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h en un H100 =<strong>de $5 a $9</strong></p> </li> <li> <p>Lo mismo en el Spark =<strong>20-30h</strong>(10x más lento), bloquea la máquina</p> </li> </ul> </div> <div class="paragraph"> <p>Con los $4 699 de Spark, puedes financiar:</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500 a ~900 fine-tunes</strong>en la nube H100</p> </li> <li> <p>Ou <strong>~23 años</strong>de Ollama Pro</p> </li> <li> <p>Ou <strong>~4 años</strong>de Ollama Max</p> </li> </ul> </div> <div class="paragraph"> <p>Y para modelos más grandes (70B+):</p> </div> <div class="ulist"> <ul> <li> <p>Le Spark avec ses 128 Go peut charger un 70B en Q4 — mais le fine-tune sera extrêmement lent</p> </li> <li> <p>Un H100 avec 80 Go peut fine-tuner un 70B en QLoRA 4-bit en quelques heures</p> </li> <li> <p>Para hacer fine-tuning completo, se necesita multi-GPU de todas formas — Spark está descartado.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_los_actores_especializados">Los Actores Especializados</h3> <div class="paragraph"> <p>En 2026, plataformas como Unsloth, Modal, Replicate y Together AI ofrecen fine-tuning serverless:</p> </div> <div class="ulist"> <ul> <li> <p>Sin gestión de GPU</p> </li> <li> <p>No hay configuración de entorno</p> </li> <li> <p>Pago por minuto</p> </li> <li> <p>Optimizaciones integradas (atención flash, cuantización automática)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-561e245aeb0c4c5d32a4fb61335b79ac.svg" alt="Comparaison des coûts de fine-tuning" width="626" height="244"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_única_verdadera_razón_la_soberanía_de_los_datos">La Única Verdadera Razón: La Soberanía de los Datos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tras eliminar la inferencia, el ajuste fino y la relación calidad/precio — ¿qué queda al Spark?</p> </div> <div class="paragraph"> <p><strong>La confidencialidad absoluta.</strong></p> </div> <div class="paragraph"> <p>No es cuestión de confidencialidad «Je ne veux pas que mes prompts soient lus par un employé d’OpenAI». Es un problema inexistente en 2026: Ollama, Groq y la mayoría de los proveedores respetables tienen políticas de cero registro y cero retención.</p> </div> <div class="paragraph"> <p>La verdadera confidencialidad es:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Hueco de aire reglamentario</strong>: defensa, diplomacia, salud — los datos no pueden <strong>físicamente</strong> salir del edificio</p> </li> <li> <p><strong>Datos propietarios críticos</strong>: código fuente de un producto no publicado, secretos industriales, algoritmos de trading</p> </li> <li> <p><strong>Resiliencia de red</strong>: la IA debe continuar funcionando incluso si Internet cae</p> </li> </ul> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Pero seamos honestos: ¿qué porcentaje de los compradores de DGX Spark está realmente en este caso? ¿1%? El resto, es un «nice to have» convertido en un gasto de $4 699.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_el_verdadero_cálculo_de_la_confidencialidad">El verdadero cálculo de la confidencialidad</h3> <div class="paragraph"> <p>Para uso individual :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>($20/mes) + modelos de código abierto chinos = solución pragmática</p> </li> <li> <p>Si un prompt se filtra en Ollama, se pierde entre los millones de solicitudes diarias. Es una gota de agua en el océano.</p> </li> <li> <p>El riesgo real no es la fuga de un prompt — es el entrenamiento no consentido en tus datos. Y eso, los proveedores serios lo prohíben contractualmente.</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ El miedo a « destilar su prompt en el LLM » es un nivel de propagación de información personal tan diluido que corresponde más a la ansiedad que a una amenaza real. A escala industrial, es diferente. Pero a escala individual, es ruido. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntesis_la_matriz_de_decisión">Síntesis : La Matriz de Decisión</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-7b7bab802fff12aac93bb6b1bc099f13.svg" alt="Matrice de décision pour choisir sa solution LLM" width="2012" height="433"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2232%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Criterio</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Gratis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPU en la nube H100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DGX Spark</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Inferencia</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅ Limitada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Cómodo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Overkill</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ lento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ajuste fino</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Imbatible</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Posible pero lento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Costo anual</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$200</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variable (~$416-2 080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 por adelantado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Confidencialidad</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Cloud US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Cloud US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nube EE.UU. (variable)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Total</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mantenimiento</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ninguna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">ninguna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Setup único</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Electricidad, actualizaciones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Obsolescencia</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ninguna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">ninguna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">ninguna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5 años</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ecosistema de software</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos abiertos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los modelos open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA (pero más lento)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>veredicto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ocasional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Recomendado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pros/Búsqueda</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solo air-gap</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Variable según volumen de trabajo ; con velocidad H100 ~10x > Spark, el costo efectivo para una carga de trabajo determinada es bajo.</em>*</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_caso_particular_la_suscripción_pro_ante_los_modelos_chinos">El Caso Particular: La Suscripción Pro Ante los Modelos Chinos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un punto merece ser destacado : la combinación<strong>Ollama Pro a $20/mes + modelos chinos de código abierto</strong>probablemente es la mejor relación calidad-precio de la historia de la IA para el gran público.</p> </div> <div class="sect2"> <h3 id="_por_qué_los_modelos_chinos_cambian_todo">Por qué los modelos chinos cambian todo</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong>: 1.6T parámetros, CSA+HCA, 1M de contexto, competitivo con Claude 4 y GPT-5 para el código</p> </li> <li> <p><strong>Qwen-3</strong>: 235B, 256K contexto, excelente en francés y en razonamiento</p> </li> <li> <p><strong>GLM-5.1</strong>: 744B, MLA+DSA, 200K contexto, adaptado para agentes</p> </li> </ul> </div> <div class="paragraph"> <p>Todos disponibles en Ollama. Todos open-source (licencias permisivas). Todos utilizables sin restricción mediante una suscripción de $20/mes.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Con Ollama Pro, tienes acceso a ~5 modelos « frontier » de código abierto por el precio de un solo modelo cerrado (Claude Pro). El valor es tan asimétrico que casi se vuelve absurdo.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_lo_que_eso_significa_para_el_hardware">lo que eso significa para el hardware</h3> <div class="paragraph"> <p>Si la mejor relación calidad-precio es una suscripción en la nube de $20 al mes, el hardware local se convierte en una opción de <strong>confort</strong> o de <strong>principe</strong> — no una opción económica.</p> </div> <div class="paragraph"> <p>Un DGX Spark a $4.699, es equivalente a:</p> </div> <div class="ulist"> <ul> <li> <p>235 meses de Ollama Pro</p> </li> <li> <p>23 juegos AAA día de lanzamiento</p> </li> <li> <p>4 MacBook Air M4</p> </li> <li> <p>Un año de alquiler de un T2 en Lyon</p> </li> </ul> </div> <div class="paragraph"> <p>Para cálculo. Lento.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_y_huawei">Y Huawei?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puesto que la pregunta me fue planteada durante mis investigaciones : no, Huawei no comercializa un equivalente al DGX Spark.</p> </div> <div class="paragraph"> <p>Lo que existe:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ascend 910C</strong> : 128 Go HBM, 800 TFLOPS FP16 — mais c’est une puce serveur, pas un desktop</p> </li> <li> <p><strong>Atlas 300I Duo</strong> : 96 Go LPDDR4X, carte PCIe à ~$1 400 — nécessite un hôte</p> </li> <li> <p><strong>Atlas 350</strong> : 112 Go HBM, 1.56 PFLOPS FP4 — accélérateur datacenter, pas un boîtier compact</p> </li> </ul> </div> <div class="paragraph"> <p>Huawei reste focalisé sur le marché des serveurs et des centres de données. Pour un boîtier compact « prêt à brancher » avec 120+ Go de VRAM, le DGX Spark (128 Go unifié) et le Mac Studio M3 Ultra (192 Go unifié) sont les seules options en 2026. Et pour l’instant, aucun constructeur chinois n’a annoncé de produit équivalent dans ce format.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_lujo_de_la_proximidad">Conclusión: El lujo de la proximidad</h2> <div class="sectionbody"> <div class="paragraph"> <p>El DGX Spark no es un mal producto. Es una mala inversión para el 99% de los compradores potenciales.</p> </div> <div id="diag-verdict" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title El panorama IA en 2026 — ¿Quién domina? left to right direction package "Uso Personal / PYME" #C8E6C9 { rectangle "�🏆 Ollama Pro ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title El panorama IA en 2026 — ¿Quién domina? left to right direction package "Uso Personal / PYME" #C8E6C9 { rectangle "�🏆 Ollama Pro $20/mes" as pro rectangle "Ollama Gratis $0/mes" as free rectangle "Instancia de GPU spot en la nube $1-3/h" as spot } package "Uso Intensivo / Pro" #FFF9C4 { rectangle "🏆 Ollama Max $100/mes" as max rectangle "�🏆 Cloud GPU dedicado\n$2-4/h" as dedicated rectangle "Modal / Together AI\nServerless" as serverless } package "Air-Gap Obligatorio" #FFCDD2 { rectangle "DGX Spark $4 699" as spark rectangle "Mac Studio M3U ~$5 000" as mac } note bottom of spark 1% des cas d'usage — défense, santé réglementée, secrets industriels critiques end note @enduml</pre> </div> </div> <div class="paragraph"> <p><em>__</em> Comprar un DGX Spark en 2026 es como comprar un servidor de correo en 2010: técnicamente posible, filosóficamente satisfactorio, económicamente absurdo para un individuo. </think> </think></p> </div> <div class="paragraph"> <p>El cálculo es sencillo, y no miente :</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong>para chatear con DeepSeek en Ollama Free</p> </li> <li> <p><strong>$200/año</strong>para trabajar seriamente con Ollama Pro</p> </li> <li> <p><strong>$5-9</strong>para un fine-tune puntual en GPU en la nube</p> </li> <li> <p><strong>$4 699</strong>¿…​ la experiencia de tener una caja NVIDIA en su escritorio?</p> </li> </ul> </div> <div class="paragraph"> <p>El mercado ha decidido. Las suscripciones cloud y los modelos open-source chinos han ganado la batalla del precio. El hardware local sobrevive en los nichos regulatorios, no en las oficinas de los desarrolladores.</p> </div> <div class="paragraph"> <p><em><em>_ El DGX Spark no es una herramienta rentable. Es un statement. « Quiero mi IA en casa, no en el cloud de otra persona. » Es respetable. Pero en 2026, cuando Ollama te da DeepSeek-V4-Pro en la nube por $20/mes, principalmente es un statement que cuesta muy caro. </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>Este artículo proviene de una conversación con mi agente IA sobre la relevancia económica del DGX Spark, cruzada con una vigilancia de mercado sobre los precios de GPU en la nube (Vast.ai, RunPod), las tarifas de Ollama/Claude, y el ecosistema de los modelos chinos de código abierto. Los precios citados son los de mayo de 2026 — probablemente habrán bajado aún más cuando leas estas líneas.</strong></p> </div> </div> </div> https://cheroliv.com//blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html Mon, 4 May 2026 00:00:00 +0000 blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_el_prompt_engineering_es_un_castillo_de_arena">El Problema : el Prompt Engineering es un Castillo de Arena</a></li> <li><a href="#_mi_respuesta_la_matriz_44">Mi Respuesta : La matriz 4×4</a> <ul class="sectlevel2"> <li><a href="#_las_cinco_zonas_dimensión_espacial_rgpd">Las Cinco Zonas (Dimensión Espacial — RGPD)</a></li> <li><a href="#_la_clasificación_epistémica_segunda_dimensión">La Clasificación Epistémica (Segunda Dimensión)</a></li> </ul> </li> <li><a href="#_cómo_el_llm_consume_esta_matriz">Cómo el LLM consume esta matriz</a></li> <li><a href="#_implementación_tareas_gradle_tipadas">Implementación: Tareas Gradle Tipadas</a></li> <li><a href="#_por_qué_es_un_manifiesto_no_solo_una_spec">¿Por qué es un Manifiesto, no solo una Spec?</a></li> <li><a href="#_la_cascada_completa_del_brain_dump_al_artículo_del_blog">La Cascada Completa — del Brain Dump al Artículo del Blog</a></li> <li><a href="#_a_favoren_contra">A favor/En contra</a></li> <li><a href="#_conclusión_ordena_tus_archivos_no_tus_prompts">Conclusión: Ordena tus archivos, no tus prompts</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 14 minutes</div> <p>Durante meses, he apilado las reglas de gobierno de los agentes. Archivos EAGER, listas de verificación LAZY, protocolos de fin de sesión en seis pasos. Y sin embargo, una pregunta permanecía pendiente: <strong>cómo el LLM sabe qué es tiene derecho de hacer con un archivo ?</strong></p> </div> <div class="paragraph"> <p>La respuesta no está en un prompt. Está en el sistema de archivos.</p> </div> <div class="paragraph"> <p>Esta es la especificación de arquitectura que hace que la respuesta sea explotable — la <strong>matriz de gobierno LLM</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_el_prompt_engineering_es_un_castillo_de_arena">El Problema : el Prompt Engineering es un Castillo de Arena</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando se le da un archivo a un LLM, se le da todo. El contenido, sí — pero también la falta de salvaguardas. El LLM no sabe si este archivo contiene un secreto, una opinión especulativa, o código closed source. Lo va a indexar. resumirlo, citándolo, mezclándolo con otros datos — y potencialmente publicarlo en una incrustación pública o una respuesta de usuario.</p> </div> <div class="paragraph"> <p>El desfile clásico, es el prompt :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">"Tu es un assistant sécurisé. Ne divulgue jamais d'informations confidentielles. Si tu détectes un secret, ignore-le. Si tu détectes une opinion, ne la répète pas."</code></pre> </div> </div> <div class="paragraph"> <p>Este prompt tiene tres problemas:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Se basa en la buena voluntad del LLM.</strong> Un modelo lo suficientemente grande para</p> </li> </ol> </div> <div class="paragraph"> <p>Resolver bugs complejos es suficientemente grande para evitar una instrucción de seguridad perdida en 200k tokens de contexto</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Es contextual, no estructural.</strong> Cambia de prompt, cambia de LLM</p> </li> </ol> </div> <div class="paragraph"> <p>cambia de sesión — y la regla desaparece</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>No escala.</strong> Cada nuevo tipo de archivo, cada nuevo nivel</p> </li> </ol> </div> <div class="paragraph"> <p>de confidencialidad exige una nueva cláusula. Su indicación se convierte en un texto regulatorio que nadie lee por completo.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>La seguridad de un sistema nunca debe depender de una instrucción que Puede olvidar, evitar o no cargar. Debe depender de una barrera que no se puede cruzar sin quererlo explícitamente.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_mi_respuesta_la_matriz_44">Mi Respuesta : La matriz 4×4</h2> <div class="sectionbody"> <div class="paragraph"> <p>La solución que he implementado en mi workspace es una <strong>matriz zona × derecho de acceso LLM</strong>. Ella no le pide al LLM que sea prudente. Ella devuelve la imprudencia estructuralmente imposible.</p> </div> <div id="diag-matrix-overview" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Matriz de Gobernanza LLM — Zona × Derecho de Acceso package "Espacio de trabajo" { rectangle "RAÍZ (Círculo 0) ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Matriz de Gobernanza LLM — Zona × Derecho de Acceso package "Espacio de trabajo" { rectangle "RAÍZ (Círculo 0) ━━━━━━ Brain dump Pensamiento libre [PROHIBIDO LLM]" as Z0 #FFB3B3 rectangle "configuration/ (Círculo 1) ━━━━━━ Secrets, tokens Infra privada [PROHIBIDO LLM]" as Z1 #FFB3B3 rectangle "office/ (Círculo 2) ━━━━━━ Datos editoriales Artículos, encuadres [FILTRADO VISIÓN]" as Z2 #FFF3B3 rectangle "foundry/private/\n(Círculo 3)\n━━━━━━\nCódigo fuente cerrado\n[DATASET PRIVADO]" as Z3 #B3D9FF rectangle "foundry/public/ (Círculo 3) ━━━━━━ Código abierto Apache 2.0 [ACCESO LIBRE]" as Z4 #B3FFB3 } Z0 -[hidden]-> Z1 Z1 -[hidden]-> Z2 Z2 -[hidden]-> Z3 Z3 -[hidden]-> Z4 @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_las_cinco_zonas_dimensión_espacial_rgpd">Las Cinco Zonas (Dimensión Espacial — RGPD)</h3> <div class="paragraph"> <p>Cada zona del workspace tiene un nivel GDPR que determina <strong>dónde</strong> el archivo puede estar enrutado :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zona</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nivel RGPD</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contenido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Derecho de acceso RAG público</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Raíz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0 — íntimo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Brain dumps, conversaciones LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PROHIBIDO</strong>— nunca indexado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 — Propietario restringido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secretos, tokens, claves API</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PROHIBIDO</strong>— nunca indexado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 — Colaborativo restringido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fecha editorial, encuadre, formaciones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>filtrado</strong>— Visión únicamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/private/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 — Abierto condicional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Código cerrado, SaaS no público</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PROHIBIDO</strong>— conjunto de datos privado exclusivamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/public/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4 — Público nativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Código Apache 2.0, plugins publicados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>LIBRE</strong>— indexación completa</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La regla es sencilla: <strong>la ruta del archivo determina lo que el LLM puede hacer con él</strong>. No hay metadatos que mantener, no hay etiqueta que añadir al frontmatter No hay clasificación manual en cada commit. El archivo está en`OSS/<code>? Es público. Está en`configuration/</code>? Es intocable.</p> </div> </div> <div class="sect2"> <h3 id="_la_clasificación_epistémica_segunda_dimensión">La Clasificación Epistémica (Segunda Dimensión)</h3> <div class="paragraph"> <p>La dimensión espacial dice <strong>dónde</strong> enrutar. Pero hay un segundo eje, perpendicular: <strong>qué</strong> enrutador. Algunos archivos en una zona autorizada contienen información que no deben diluirse tal cual:</p> </div> <div id="diag-epistemic-filter" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b91f127a759212d0e5dbb3c209ab97cc.svg" alt="Filtre épistémique Vision/Opinion/Stratégie appliqué aux zones 2 et 3" width="1215" height="558"> </div> </div> <div class="paragraph"> <p>La cuadrícula de clasificación epistemológica, grabada en la regla 2bis de mi gobernanza agente :</p> </div> <div class="paragraph"> <p>| Estado | Definición | Señal LLM | Destino | | VISION | Arquitectura estabilizada, patrón probado | Lenguaje declarativo, referencias sesiones/pruebas | Dilución completa + Blog | | ESTRATEGIA | Posicionamiento de negocio, precios | Vocabulario mercado, competencia | Documentos raíz únicamente | | OPINION | Especulación, hipótesis no validada | Lenguaje hipotético, intuición | Confinamiento Círculo 0 |</p> </div> <div class="paragraph"> <p>La combinación de las dos dimensiones — zona física × clasificación epistémica — forma la<strong>matriz completa</strong>:</p> </div> <div id="diag-full-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-3b0ebbd1500b6374dacff7444a2673ec.svg" alt="La matrice complète : 5 zones × 3 classifications épistémiques" width="442" height="132"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_cómo_el_llm_consume_esta_matriz">Cómo el LLM consume esta matriz</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matriz no es un documento que el LLM lee. Es una <strong>restricción</strong> implícita** codificada en el vector compuesto de contexto (EPIC 9 — en curso de implementación).</p> </div> <div class="paragraph"> <p>Esto es lo que el LLM recibe en cada sesión :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">VECTEUR COMPOSITE DE CONTEXTE ├── RAG pgvector → OSS/ + office/Vision │ (similarité sémantique sur contenu publiable) ├── Knowledge Graph graphify → OSS/ │ (relations exactes entre artéfacts publics) ├── Knowledge Graph privé → CSS/ │ (relations entre code closed source — jamais exporté) ├── Métadonnées de zone → chaque fichier taggé par zone physique │ (le LLM sait s'il est dans office/ ou OSS/) └── Historique des décisions → WORKSPACE_VISION.adoc (contexte temporel des arbitrages)</code></pre> </div> </div> <div class="paragraph"> <p>Concretamente, cuando el LLM me dice :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Je vais indexer le contenu de edster/ pour enrichir le knowledge graph...</code></pre> </div> </div> <div class="paragraph"> <p>Los metadatos de zona responden incluso antes de que el LLM termine su frase : <code>edster/`está en`CSS/</code>, nivel 3 →<strong>acceso prohibido al knowledge graph público.</strong> El RAG no lo ve. El grafo no lo toca. La respuesta del usuario no no lo cita.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La ontología espacial funciona como una<strong>permiso Unix</strong>para los LLM. No le pide a un proceso que sea prudente con`/etc/shadow`— — le nie el acceso de lectura. Mismo principio.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_implementación_tareas_gradle_tipadas">Implementación: Tareas Gradle Tipadas</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matriz no es una filosofía. Es código. Aquí está el contrato de la tarea Gradle que lo implementa :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class ZoneAwareIndexer @Inject constructor( private val rootDir: DirectoryProperty, private val configServer: ConfigServerProperty // → configuration/ ) : DefaultTask() { @Input val zoneFilter: SetProperty<Zone> = project.objects.setProperty(Zone::class.java) @OutputFile val ragIndex: RegularFileProperty = project.objects.fileProperty() @TaskAction fun index() { val allowedPaths = zoneFilter.get().flatMap { it.resolve(rootDir.get()) } val forbiddenPaths = Zone.RESTRICTED.resolve(rootDir.get()) + Zone.INTIMATE.resolve(rootDir.get()) // Le RAG ne voit jamais configuration/ ni la racine // CSS/ alimente un index privé, pas celui-ci // office/ est filtré par le classifieur Vision/Opinion } } enum class Zone { INTIMATE, // Cercle 0 — racine RESTRICTED, // Cercle 1 — configuration/ EDITORIAL, // Cercle 2 — office/ CLOSED_SOURCE, // Cercle 3 — foundry/private/ OPEN_SOURCE // Cercle 3 — foundry/public/ }</code></pre> </div> </div> <div class="paragraph"> <p>La tarea es <strong>testable</strong>. Puedes escribir una prueba que verifica:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `le RAG n'indexe jamais configuration`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE, Zone.EDITORIAL)) index.index() assertThat(index.ragIndex).doesNotContain("configuration/") } @Test fun `le code closed source est exclu du RAG public`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE)) // OSS only assertThat(index.ragIndex).doesNotContain("edster") }</code></pre> </div> </div> <div class="paragraph"> <p>380 pruebas, 380 PASS. Al igual que para plantuml-gradle — la seguridad está probada, no esperada.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_es_un_manifiesto_no_solo_una_spec">¿Por qué es un Manifiesto, no solo una Spec?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este documento es una especificación de arquitectura porque define :</p> </div> <div class="ulist"> <ul> <li> <p>de los<strong>dimensiones</strong> (spatiale, épistémique)</p> </li> <li> <p>de los<strong>reglas deterministas</strong>(zona → derecho de acceso)</p> </li> <li> <p>Un <strong>contrato de tarea</strong>(Gradle tipado, verificable)</p> </li> <li> <p>Una<strong>implementación de referencia</strong>(mi espacio de trabajo)</p> </li> </ul> </div> <div class="paragraph"> <p>Pero también es un<strong>evidente</strong>porque toma posición sobre un debate más amplio : <strong>¿cómo gobernar el acceso de un LLM a los datos?</strong></p> </div> <div class="paragraph"> <p>La respuesta de la industria, es el prompt engineering + los guardrails<br> los clasificadores post-hoc. Mi respuesta es : <strong>organiza tus archivos en los buenos expedientes.</strong> El resto es automático.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Este manifiesto no dice "los LLM deben estar alineados". Él dice: "la alineación un LLM sobre sus reglas de seguridad es una consecuencia de su sistema de archivos, no de su prompt</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_la_cascada_completa_del_brain_dump_al_artículo_del_blog">La Cascada Completa — del Brain Dump al Artículo del Blog</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para ilustrar el ciclo completo, aquí está cómo nació esta idea de matriz y ha sido diluida:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Session 4 mai 2026 — Feedback global du workspace │ ├→ Le LLM identifie : "la dualité public/privé est invisible" │ → Classifié VISION (constat architectural vérifiable) │ ├→ PICTURE_ME_ROLLIN_MATRICE_4X4.adoc — STIMULUS (Cercle 0) │ → Brain dump structuré, classification VISION confirmée │ ├→ DILUTION → WORKSPACE_AS_PRODUCT.adoc (section Matrice 4×4) │ → La spec vit dans les documents racine │ ├→ DILUTION → WORKSPACE_ORGANIZATION.adoc (OSS/CSS) │ → La granularisation est documentée │ └→ ARTICLE 0117 (ce document) → cheroliv.com → La VISION est publiée</code></pre> </div> </div> <div class="paragraph"> <p>Lo que comenzó como una observación en sesión ("hey, el RAG no sabe que edster es closed source") se ha convertido en una especificación de arquitectura Publicada en menos de una sesión. Es el patrón STIMULUS en acción.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_favoren_contra">A favor/En contra</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Este enfoque (Ontología espacial + matriz)</th> <th class="tableblock halign-left valign-top">El Enfoque Clásico (Prompt + Guardrails)</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mecánica</strong> — el sistema de archivos bloquea el acceso, no el LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Declarativa</strong> — el prompt pide al LLM que sea prudente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Testable</strong> — el contrato de tarea Gradle es verificado por 380+ pruebas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>No probado</strong> — "¿El LLM ha respetado la regla?" es una pregunta abierta</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Independiente del LLM</strong> — cambia de modelo, las carpetas permanecen</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Dependiente del LLM</strong> — cada modelo interpreta el prompt de forma diferente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Escalable</strong> — nuevo tipo de datos = nueva carpeta, cero cambio de código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>No escalable</strong> — nuevo tipo de datos = nueva cláusula de prompt, nuevo riesgo de regresión</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Auditable</strong> — el sistema de archivos es el rastro de auditoría</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>No auditado</strong> — el prompt no tiene historial, no tiene diff, no tiene blame</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Restricción</strong> : exige una disciplina de organización inicial</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Restricción</strong> : exige una disciplina de redacción de prompt en cada sesión</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusión_ordena_tus_archivos_no_tus_prompts">Conclusión: Ordena tus archivos, no tus prompts</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matriz de gobernanza LLM que acabo de describir no es un producto. Es una<strong>especificación de arquitectura</strong>— y es por eso que ella es publicable</p> </div> <div class="paragraph"> <p>Lo que la hace robusta es que no le pide nada al LLM. Ella no le No confía. No se basa en su alineación, su comprensión del francés, o su buena voluntad. Se basa en el sistema de archivos — la capa más baja, más estable y más probada de toda la pila.</p> </div> <div class="paragraph"> <p>Cuando le digo a mi LLM "puedes indexarlo todo en`OSS/<code>, nada en `configuration/</code>, et `office/`solo si está clasificado como Vision" — no es una instrucción. Es un <strong>filtro</strong> — implementado en Kotlin, verificado por 380 pruebas, ejecutado antes de que el LLM vea los datos.</p> </div> <div class="paragraph"> <p>Esta es la diferencia entre decirle a alguien "no mires en este cajón y cerrar el cajón con llave. El agente de gobernanza que estoy construyendo desde de meses es la clave. La matriz es el plano del mueble.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — El Compartimentaje Epistémico Automatizado</a></p> </li> <li> <p>Artículo 0114 — Los Círculos de Confianza y la Ontología Espacial</p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Artículo 0108 — Gobernar un agente de IA con AsciiDoc</a></p> </li> <li> <p><a href="../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html">Artículo 0115 — El Anonimizador MVP0</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html Sun, 3 May 2026 00:00:00 +0000 blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_accidente_que_esperaba_ocurrir">El accidente que esperaba ocurrir</a> <ul class="sectlevel2"> <li><a href="#_la_verdadera_pregunta">La Verdadera Pregunta</a></li> </ul> </li> <li><a href="#_la_solución_oss_y_css">La Solución : OSS/ y CSS/</a></li> <li><a href="#_por_qué_oss_y_css_y_no_público_y_privado">¿Por qué "OSS" y "CSS" y no "Público" y "Privado</a> <ul class="sectlevel2"> <li><a href="#_el_árbol_completo_cuatro_zonas_no_tres">El Árbol Completo — Cuatro Zonas, No Tres</a></li> </ul> </li> <li><a href="#_el_caso_particular_cheroliv_com">El Caso Particular : cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_bakery_gradle_le_da_igual">bakery-gradle le da igual</a></li> </ul> </li> <li><a href="#_impacto_sobre_el_agente_de_gobernanza">Impacto sobre el agente de gobernanza</a></li> <li><a href="#_lo_que_ganamos_y_lo_que_perdemos">Lo Que Ganamos (Y Lo Que Perdemos)</a></li> <li><a href="#_conclusión_el_señal_física_supera_al_señal_de_software">Conclusión: el Señal Física supera al Señal de Software</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura: 10 minutes</div> <p><code>foundry/</code>— la zona funcional que aloja el código de mi workspace — contiene 18 proyectos. Ocho son de código abierto bajo Apache 2.0. Solo uno es código cerrado — el SaaS Edster. Durante meses, estos nueve proyectos han coexistido en el mismo directorio, separados únicamente por…​ nada. Su estado público/privado Era una información en mi cabeza, no en el sistema de archivos.</p> </div> <div class="paragraph"> <p>Y luego quise conectar un RAG. Y entonces todo se derrumbó.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_accidente_que_esperaba_ocurrir">El accidente que esperaba ocurrir</h2> <div class="sectionbody"> <div class="paragraph"> <p>En abril de 2026, comencé a implementar el RAG pgvector para slider-gradle. El principio: indexar todos los depósitos de`foundry/<code>, producir de embeddings, e inyectarlos en el contexto del LLM para que tenga una percepción" del expediente`foundry/</code>.</p> </div> <div class="paragraph"> <p>El pipeline era sencillo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val repos = fileTree(rootDir) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val chunks = repos.map { chunk(it) } val embeddings = chunks.map { embed(it) } pgvector.insert(embeddings)</code></pre> </div> </div> <div class="paragraph"> <p>Simple. Eficaz. Y<strong>peligroso</strong>.</p> </div> <div class="paragraph"> <p>Porque este`fileTree`no hace la diferencia entre`plantuml-gradle/` (Apache 2.0, public) y`edster/`(closed source, private). Lo traga todo. Y si un día publico estos embeddings — en un tablero, en una respuesta LLM, en un conjunto de datos de entrenamiento — el código propietario de Edster se filtra.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>El problema no es que un LLM lea código fuente cerrado. El problema, que este código termine en un embedding vectorial <strong>public</strong> — irreversible, no suprimible, no auditável</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_la_verdadera_pregunta">La Verdadera Pregunta</h3> <div class="paragraph"> <p>No es "¿cómo impedir que el LLM filtre código?". Es "cómo ¿hacer que la fuga sea estructuralmente imposible?</p> </div> <div class="paragraph"> <p>La respuesta no es un prompt. La respuesta, es cortar el archivo en dos.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_oss_y_css">La Solución : OSS/ y CSS/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── plantuml-gradle/ ← public ├── bakery-gradle/ ← public ├── magic-stick/ ← public ├── edster/ ← PRIVÉ ├── slider-gradle/ ← public └── ... ← mélange invisible</code></pre> </div> </div> <div class="paragraph"> <p>Después:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── OSS/ ← tout est Apache 2.0 │ ├── plantuml-gradle/ │ ├── bakery-gradle/ │ ├── magic-stick/ │ ├── slider-gradle/ │ └── ... └── CSS/ ← tout est closed source / private └── edster/</code></pre> </div> </div> <div class="paragraph"> <p>Le `fileTree`se convierte :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val ossRepos = fileTree(File(rootDir, "OSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val cssRepos = fileTree(File(rootDir, "CSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } // Embeddings publics — OSS seulement pgvectorPublic.insert(ossRepos.map { chunk(it) }.map { embed(it) }) // Dataset fine-tuning privé — CSS seulement fineTuningDataset.insert(cssRepos.map { chunk(it) }) // jamais publié</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>El RAG público nunca ve`CSS/`. El código closed source alimenta un dataset privado de fine-tuning — un modelo interno que nunca sale de mi casa. La la separación es mecánica, no declarativa.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_oss_y_css_y_no_público_y_privado">¿Por qué "OSS" y "CSS" y no "Público" y "Privado</h2> <div class="sectionbody"> <div class="paragraph"> <p>La elección de los acrónimos OSS (Open Source Software) y CSS (Closed Source Software) está decidido:</p> </div> <div class="ulist"> <ul> <li> <p>Público"/"Privado" describe la<strong>visibilidad</strong>(lo que GitHub ve)</p> </li> <li> <p>OSS"/"CSS" describe la<strong>naturaleza</strong>código (lo que el LLM debe saber)</p> </li> </ul> </div> <div class="paragraph"> <p>La visibilidad de GitHub es un metadato del repositorio distante. La naturaleza del código es una propiedad del contenido. El LLM no tiene acceso a la API de GitHub — pero tiene acceso al sistema de archivos.<code>CSS/`le dice "atención, este código no está bajo licencia libre" sin necesidad de leer un`LICENSE`o de analizar un`package.json</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>El nombre de la carpeta es el metadato más robusto que usted pueda dar a un LLM. No puede ser mal analizada, ignorada o mal interpretada. El LLM ve`CSS/edster/`en la ruta del archivo — él sabe.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_el_árbol_completo_cuatro_zonas_no_tres">El Árbol Completo — Cuatro Zonas, No Tres</h3> <div class="paragraph"> <p>La granularización OSS/CSS completa la ontología de tres zonas. La zona `foundry/`pasa de 1 a 2 subzonas funcionales :</p> </div> <div id="diag-four-zone-workspace" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-0a13a8dbd31451bf5c6b0d97655f46a0.svg" alt="L’organisation de foundry/ en deux sous-zones OSS et CSS" width="1751" height="5736"> </div> </div> <div class="paragraph"> <p>| Zona | RGPD | Indexación RAG pública | Conjunto de datos fine-tuning | | Raíz | Nivel 0 — Íntimo | ✗ | ✗ | | <code>configuration/</code>| Nivel 1 — Restringido | ✗ | ✗ | | <code>office/</code>| Nivel 2 — Colaborativo | ✓ filtrado | ✓ filtrado | | <code>foundry/private/</code>| Nivel 3 — Abierto condicional | ✗ | ✓ Privado | | <code>foundry/public/</code>| Nivel 4 — Público nativo | ✓ Libre | ✓ Público |</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_caso_particular_cheroliv_com">El Caso Particular : cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mientras estaba allí, corregí otra incoherencia. Mi sitio <code>cheroliv.com`vivía en`foundry/`como un proyecto de software de pleno derecho — con su propio build Gradle, su propia CI, su propia gobernancia</code>.agents/`.</p> </div> <div class="paragraph"> <p>Pero los artículos de blog no son código. Son <strong>datos</strong> editoriales** de Cercle 2 — al mismo nivel que los encuadres de`office/pilotage/` o las formaciones de`office/formations/`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">AVANT APRÈS foundry/ office/ cheroliv.com/ sites/ site/jbake/content/blog/ cheroliv.com/ 2026/0117_....adoc 2026/0117_....adoc</code></pre> </div> </div> <div class="paragraph"> <p>Lo que cambia:</p> </div> <div class="ulist"> <ul> <li> <p>Los artículos están en`office/`→ confidencialidad de Círculo 2</p> </li> <li> <p>La tarea`publishSite`se convierte en una capability de`engine`</p> </li> </ul> </div> <div class="paragraph"> <p>via`bakery-gradle`— el plugin recibe un`FileTree`, él no sabe que los artículos vienen de`office/`</p> </div> <div class="ulist"> <ul> <li> <p>Un solo CI, una sola gobernanza — cero duplicación</p> </li> <li> <p>El clasificador Vision/Opinion (Regla 2bis) se aplica automáticamente :</p> </li> </ul> </div> <div class="paragraph"> <p>los artículos en`office/`se filtran antes de la publicación</p> </div> <div class="sect2"> <h3 id="_bakery_gradle_le_da_igual">bakery-gradle le da igual</h3> <div class="paragraph"> <p>Y eso es lo que es hermoso. El plugin`bakery-gradle`No ha sido modificado. Recibe un directorio de contenido AsciiDoc, genera HTML, hace push en GitHub Pages. Que este directorio se llame`site/jbake/content/` ou <code>office/sites/cheroliv/</code>— el plugin le da igual.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// engine/build.gradle.kts task("publishBlog") { doLast { val articles = fileTree("../../office/sites/cheroliv/2026/") bakery.generate(articles) // ← bakery ne sait pas d'où ça vient } }</code></pre> </div> </div> <div class="paragraph"> <p>El contrato de interfaz es una tarea Gradle. No es una API REST. No es un webhook. Una tarea — tipada, comprobable, ejecutable localmente y en CI.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_impacto_sobre_el_agente_de_gobernanza">Impacto sobre el agente de gobernanza</h2> <div class="sectionbody"> <div class="paragraph"> <p>La granularización OSS/CSS modifica la gobernanza de los agentes en tres puntos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RAG public</strong> : el perímetro de indexación pasa de`foundry/**`</p> </li> </ol> </div> <div class="paragraph"> <p>à <code>foundry/public/<strong></code>+<code>office/Vision/</strong></code>. El código de código cerrado está excluido del índice por configuración de tarea, no por prompt.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Knowledge Graph</strong> : graphify-gradle produce dos grafos :</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>office/graph.json</code>(public) — relaciones entre artefactos OSS + office/Vision * <code>configuration/graph_private.json</code>(gitignored, privado) — relaciones entre artefactos CSS, nunca publicado</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Ajuste fino del dataset</strong> :`codebase-gradle`ahora tiene dos fuentes:</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>OSS/</code>→ datasets públicos (modelos comunitarios, benchmarks) *<code>CSS/</code>→ datasets privados (modelo interno, fine-tuning propietario)</p> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_ganamos_y_lo_que_perdemos">Lo Que Ganamos (Y Lo Que Perdemos)</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Antes (carpeta plana)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Después (OSS/CSS + office/sites)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/</code>→ mezcla pública/privada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/public/</code>→ todo es publicable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexa todo sin discriminación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexa`OSS/`+`office/Vision`exclusivamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Imposible saber si un proyecto es de código abierto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El camino`OSS/` ou `CSS/`lo dice</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com tiene su propia CI, su propia gobernanza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La CI y la gobernanza se comparten en engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los artículos de blog están en un repositorio "code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los artículos de blog están en`office/sites/`— datos, no código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riesgo de fuga de código fuente cerrado en embeddings públicos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estructuralmente imposible —`CSS/`fuera del alcance RAG</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El único costo: un`git mv`global sobre los 17 repositorios OSS + una refactorización del <code>build.gradle.kts</code> de <code>engine</code>. Es una migración en frío — sin datos en vuelo, sin usuarios afectados</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_señal_física_supera_al_señal_de_software">Conclusión: el Señal Física supera al Señal de Software</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo que hice esta tarde es reemplazar una convención invisible por una separación visible en la zona`foundry/<code>. Antes, usted debía <strong>saber</strong> que`edster/`era de código cerrado. Ahora, ustedes lo <strong>ven</strong> — el dossier se llama`CSS/</code>.</p> </div> <div class="paragraph"> <p>Es el mismo principio que los permisos Unix, las VLAN de red, o los compartimentos cortafuegos en una base de datos. La seguridad no debe ser una información que debes recordar. Debe ser una propiedad <strong>física</strong>del sistema.</p> </div> <div class="paragraph"> <p>La granularidad OSS/CSS es la traducción de este principio en el campo de la gobernanza LLM. El LLM no necesita saber que Edster es confidencial. Necesita ser incapaz de indexarlo.</p> </div> <div class="paragraph"> <p>Y esto es exactamente lo que`CSS/`garantiza.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0118_matrice_gouvernance_llm_zone_acces_workspace_post.html">Artículo 0117 — La Matriz de Gobernanza LLM</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Artículo 0114 — Los Círculos de Confianza</a></p> </li> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — El Compartimentaje Epistémico Automatizado</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Artículo 0108 — Gobernar un Agente IA con AsciiDoc</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html Sat, 2 May 2026 00:00:00 +0000 blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_pensar_libremente_sin_publicar_nada">El Problema: Pensar libremente sin publicar nada</a></li> <li><a href="#_el_patrón_stimulus_nacer_fijar_diluir_morir">El Patrón STIMULUS — Nacer, Fijar, Diluir, Morir</a></li> <li><a href="#_la_delegación_al_llm_por_qué_es_el_llm_quien_filtra">La delegación al LLM: Por qué es el LLM quien filtra</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura: 10 minutes</div> <p>Mi LLM no se limita a ejecutar mis tareas Gradle. Es el guardián de la frontera entre mi pensamiento privado y mi expresión pública. Cada idea se clasifica — Visión, Opinión, Estrategia — antes de ser dirigida. Aquí está cómo este compartimentaje epistémico automatizado protege mi jardín mental sin silenciarme.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_pensar_libremente_sin_publicar_nada">El Problema: Pensar libremente sin publicar nada</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando un desarrollador solo documenta su proceso de pensamiento con un LLM, se topa con un paradoje:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CAPTURE TOUT (Cercle 0, jardin secret) ├→ Brain dump libre, pas de censure ├→ Idées brutes, spéculations, intuitions non vérifiées ├→ Allers-retours LLM : challenger, itérer, raffiner └→ Le LLM voit TOUT — le bon, le flou, l'embryonnaire PUBLICATION SÉLECTIVE (Cercle 4, blog public) ├→ Uniquement les décisions actées ├→ Uniquement les patterns testés (>100 tests PASS) ├→ Uniquement ce qui a de la valeur pour le lecteur └→ JAMAIS une spéculation présentée comme une vérité</code></pre> </div> </div> <div class="paragraph"> <p>Entre estos dos extremos, hay un<strong>filtro</strong>. La pregunta es: ¿quién lo hace? ¿Un humano cansado al final de la sesión? ¿Un script de regex ingenuo? ¿O el LLM mismo, que ya lo ha leído todo?</p> </div> <div class="paragraph"> <p>Mi respuesta: el LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_patrón_stimulus_nacer_fijar_diluir_morir">El Patrón STIMULUS — Nacer, Fijar, Diluir, Morir</h2> <div class="sectionbody"> <div class="paragraph"> <p>El estímulo es un archivo`.adoc`temporal en la raíz del workspace (Círculo 0). Su nombre sigue una convención evocativa —<code>PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code>— que captura la intención exploratoria del momento.</p> </div> <div class="paragraph"> <p>Su ciclo de vida es despiadado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CRÉATION (Cercle 0) ├→ Fichier vide, brain dump libre ├→ Allers-retours LLM ← → développeur └→ Aucune pression de structure ou de publication MATURATION ├→ Le contenu se densifie ├→ Des sections émergent naturellement └→ Le fichier devient une référence informelle de session CLASSIFICATION ÉPISTÉMIQUE ← FAIT PAR LE LLM ├→ VISION → publiable, diluer dans les docs publics + blog ├→ OPINION → confiner au Cercle 0, pas de dilution externe └→ STRATÉGIE → dilution restreinte (docs racine, PAS de blog) DILUTION (Cascade vers Cercles légitimes) ├→ VISION → WORKSPACE_AS_PRODUCT.adoc + WHAT_THE_GAMES.adoc + blog ├→ STRATÉGIE → WORKSPACE_AS_PRODUCT.adoc (section business) └→ OPINION → reste dans le stimulus, ne bouge pas ARCHIVAGE + SUPPRESSION ├→ Snapshot dans configuration/vision-archive/ (trace historique) └→ rm du stimulus — il a fini son travail</code></pre> </div> </div> <div class="paragraph"> <p>Un estímulo que sobrevive más de 2 sesiones sin dilución es un anti-patrón. O bien la información es demasiado importante para pudrirse en un archivo temporal (→ diluer), o bien es demasiado vaga para merecer existir (→ supprimer).</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_delegación_al_llm_por_qué_es_el_llm_quien_filtra">La delegación al LLM: Por qué es el LLM quien filtra</h2> <div class="sectionbody"> <div class="paragraph"> <p>No hardcodeo la clasificación Visión/Opinión en Kotlin. Lo inyecto en el<strong>prompt del sistema</strong>del LLM via`AGENT_GOVERNANCE.adoc`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Pour chaque dilution de stimulus ou session, tu es responsable de classifier le contenu : - VISION : décision architecturale actée, pattern testé en production (>100 tests PASS), décision documentée dans BACKLOG ou ROADMAP - OPINION : spéculation, hypothèse non validée par des tests, intuition sans ancrage expérimental - STRATEGIE : positionnement business, pricing, marché cible Règles : - Si OPINION, le contenu reste confiné dans son cercle d'origine - Si VISION, tu procèdes à la dilution dans les documents racine - Si STRATEGIE, dilution restreinte (docs racine, pas de blog public) - Cette classification détermine aussi si un article de blog est publiable sur cheroliv.com ---- El LLM lee esta directiva**antes**de tratar la sesión. Está en su contexto inmediato, no en un archivo separado. Es *prompt engineering determinista*: el comportamiento surge del texto inyectado, no de un clasificador externo. === ¿Por qué funciona — y por qué es contraintuitivo? La reacción estándar: « ¿Confías la clasificación a la IA? ¿Y si se equivoca? Respuesta: el ser humano no lo hace mejor a las 2 a.m. La diferencia es que el LLM, él, lo lee TODO. Tiene el contexto completo de la sesión y de los documentos objetivo. Sabe que`VPS ECO-16 12€ HT`es una decisión de infraestructura (VISION) mientras que`« le TTS ElevenLabs sonne plus naturel que Coqui »`es una opinión no verificada por un benchmark. El ser humano, al final de la sesión, lee en diagonal y hace lo mejor que puede. El LLM lee exhaustivamente y aplica una cuadrícula sistemática. El resultado es**más fiable**, ni menos. Y para el 20% de casos ambigüos — la zona gris donde incluso el LLM duda — la respuesta no es « agregar código ». La respuesta es**LangGraph4j**(EPIC 13): un grafo de estado que, para los casos ambiguos, activa un nodo Human-in-the-Loop y remite al humano para la decisión. Pero para el 80% de los casos claros, el LLM basta. == El Tubo Completo: del Brain Dump al Blog Post Aquí está el flujo completo — desde la idea bruta hasta el artículo publicado — con el LLM como único filtro : [source] ---- CERCLE 0 (jardin secret) PICTURE_ME_ROLLIN.adoc ← brain dump, allers-retours LLM ↓ [LLM classifie] → VISION / OPINION / STRATÉGIE ↓ VISION → dilution dans WORKSPACE_AS_PRODUCT.adoc → dilution dans WHAT_THE_GAMES_BEEN_MISSING.adoc → dilution dans WORKSPACE_VISION.adoc (session context) → RÉDACTION ARTICLE BLOG ← le LLM écrit, pas le dev ↓ CERCLE 4 (blog public) 0116_compartimentage_epistemique.adoc ← publié sur cheroliv.com ↓ ./gradlew deploy (bakery-gradle → JBake → JGit → GitHub Pages) ↓ https://cheroliv.com/blog/2026/0116/ ← live ---- El desarrollador no escribe el artículo. Él desafía, revisa, valida. El LLM escribe. El bucle es: 1. Volcado libre → sin censura 2. Clasificación epistemológica por el LLM → sin fuga 3. Redacción por el LLM → sin procrastinación 4. Revisión humana → sin error El cuello de botella histórico — « no tengo tiempo para escribir » — se ha eliminado. El LLM hace la mayor parte del trabajo. El ser humano hace lo que solo el ser humano puede hacer: juzgar. == Los Tres Documentos Raíz — Cómo La Información Encuentra Su Lugar Cada documento objetivo tiene un papel específico en la cascada de dilución : [cols="1,3,2"] |=== |Documento |Lo que recibe |Tipo de contenido |`WORKSPACE_AS_PRODUCT.adoc` |Decisiones arquitectónicas, stack técnico, hoja de ruta, modelo de negocio |VISIÓN + ESTRATEGIA |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |Patrones, lecciones, anti-patrones, ontología, reglas formales |VISIÓN (patrones probados) |`WORKSPACE_VISION.adoc` |Contexto de la sesión, historial de decisiones, puntos de infraestructura |VISIÓN + ESTRATEGIA (contexto) |`AGENT_GOVERNANCE.adoc` |Reglas de gobierno, cartera de proyectos, procedimientos |VISIÓN (gobernanza) |**Blog cheroliv.com** |Artículos públicos, valor para el lector externo |Visión únicamente |=== Un mismo estímulo puede nutrir los 4 documentos + el blog — cada destino recibe la parte que le corresponde, sin redundancia, sin contradicción. Es lo que pasó para`PICTURE_ME_ROLLIN.adoc`(3 mayo 2026) : | Información | Clasificación | Destinos | | Inventario de los 13+ proyectos foundry/ | VISION | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 8.49€/mes | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | | « El mercado africano está listo para el mobile money » | estrategia | WORKSPACE_AS_PRODUCT (section business) | | « DeepSeek > Kimi > GLM para contexto largo » | OPINION → VISION | Confinado y luego promovido tras benchmark (artículo 0112) | | Empleado sintético como producto final | Estrategia | WORKSPACE_AS_PRODUCT (sin blog) | == El patrón Baby-Step + TestContainer + Doc Vivante — el Código que se prueba a sí mismo El patrón STIMULUS/Dilution gestiona el pensamiento. Su equivalente para el código es el patrón Baby-Step/TestContainer/Doc Vivante, validado por plantuml-gradle (380/380 tests PASS, 137 sesiones sin fuga Docker) : [cols="1,3"] |=== |Principio |Regla |**paso de bebé** |Nunca más de 3 puntos por US. Si una US da miedo, dividir. Una US de 1 punto que pasa > una US de 8 puntos que se arrastra. |**TestContainer primero** |Antes del código de negocio, el contenedor. La prueba de infra pasa → entorno estable garantizado. |**Dataset comité** |Subconjunto mínimo pero representativo en`src/test/resources/`, sin PII. Clonable, lanzable. |**Documentación viva** |Cada test de Cucumber = una frase en lenguaje natural. El código fuente ES la spec ejecutable. Cero doc Markdown que mantener. |**Limpieza automática** |Cero fugas de recursos. Contenedores huérfanos,`/tmp/gradle-test-*`: todo está limpio. |=== Este patrón es la razón por la cual plantuml-gradle nunca ha tenido una regresión de Docker en 138 sesiones. Garantiza que el código que habla con una infraestructura externa (PostgreSQL, Redis, Kafka) siempre se prueba en un entorno idéntico al de producción — versionado, reproducible, ejecutable con un solo comando. == Conclusión: la Libertad de Pensar sin el Miedo de Publicar La compartimentación epistémica automatizada no es una herramienta de censura. Es un**liberador**. Le permite pensar libremente, especular sin filtro, hacer un brain-dump de todo lo que pasa por la cabeza — sin nunca temer que una idea embrionaria termine en el blog. El LLM es el guardián de esta frontera. Lee todo. Clasifica. Diluye lo que merece sobrevivir. Confina lo que debe permanecer privado. Redacta lo que es publicable. Y el desarrollador, él, tiene la última palabra: revisar, desafiar, validar. Juzgar. Era la división del trabajo lo que le faltaba al desarrollador solo: un empleado sintético que gestiona la papelada mental, para que el humano pueda concentrarse en lo que hace mejor — concebir, arquitectar, decidir. == Referencias * Artículo sobre la gobernanza del agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gobernar un agente IA con AsciiDoc] * Artículo sobre la ontología espacial y los círculos de confianza:link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[La Ontología Espacial como Mecanismo de Alineamiento] * Artículo sobre el Anonimizador MVP0:link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Nuestro Primer Contratado: El Anonimizador de Datasets] * Artículo sobre la comparación de los LLMs en contexto largo:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * Artículo sobre el mecanismo del agente de copia de seguridad:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window y ola fría] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_que_hace_huir_a_todo_el_mundo">El problema que hace huir a todo el mundo</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>No contrato un LLM. Contrato un anonimizador. Antes de hacer <code>RAG pgvector</code>, antes de afinar a los expertos <code>CDA/FPA</code>, antes de aprovisionar los espacios de trabajo de los clientes — alguien tiene que limpiar los baños de los datos. Este empleado es el experto en anonimización (MVP0, EPIC 2 de <code>codebase-gradle</code>). Y es él quien hace que el producto sea comercializable.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_que_hace_huir_a_todo_el_mundo">El problema que hace huir a todo el mundo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cualquier startup IA que maneja los datos de entrenamiento se topa con el mismo muro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- Resultado: o haces RAG con datos sucios (alucinaciones de PII, no cumplimiento del RGPD, riesgo jurídico), o no haces nada (sin producto). La tercera vía — limpiar a mano — no es escalable. Mi respuesta : no sortear el problema. L'**automatizar**. . == MVP0 : El Anonimizador, Primer Contratado en Período de Prueba El MVP0 no es una feature. Es un**experto de comodidad**— un empleado que hace el trabajo sucio, tonto y malvado, y del que nadie quiere hablar en los pitch decks. Qué hace: [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- Detecta primero los patrones más evidentes (emails`.*@.*`, tokens`sk-*`, `ghp_*`, IPs), luego aprende. El período de prueba, eso es: verificamos que no deje pasar falsos negativos antes de nombrarlo titular. == Lo que este MVP desbloquea (y no es solo la Conformidad) La anonimización como MVP0 no es el peaje del RGPD antes de la autopista. Es la autopista misma. Esto es lo que abre: === Presente : Realidad Aumentada en Prompt [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- El RAG no busca en datos sucios — busca en un espacio**correcto por construcción**. Esto cambia todo para la calidad de las respuestas: el LLM no pasa su tiempo evitando PII que reconoce pero que no debe mencionar. === Futuro : Fine‑Tuning sobre datos limpios [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- El fine-tuning sobre datos brutos es una catástrofe jurídica potencial. Sobre datos limpios, es una**método reproducible**. Cada cliente acumula sus datasets limpios, cada cliente puede ajustar sus expertos de negocio sobre sus datos — sin nunca exponer un dato personal. == ¿Por qué es comercializable? No es « una herramienta de cumplimiento GDPR ». Es una**método reproducible que transforma un problema universal en activo**: 1. *Toda empresa de formación tiene datos sucios* — es el problema 2. *Ninguna tiene un pipeline automatizado de limpieza de fuentes múltiples* — eso es el mercado 3. *El bucle : anonimización → RAG → fine-tuning es propietario* — es la barrera El SaaS Edster (MVP3) no venderá «un workspace Gradle». Vendrá este bucle cerrado. Y el MVP0 es la puerta de entrada. == El Formato SQL como Tercera Vía de Contexto La importación de datos estructurados no es solo un formato de intercambio. El esquema SQL (DDL) lleva el**modelo entidad-relación del dominio**: [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- Este DDL, una vez anonimizado (línea 4), se convierte en una fuente de contexto para el LLM. No es texto — de**modelo de negocio**. El RAG da el contenido (similaridad vectorial), Graphify da las relaciones (estructura exacta), y el esquema SQL da el**Domain-Driven Design implícito**: bounded contexts, agregados, objetos de valor. El LLM comprende el negocio porque lee su esquema. == La hoja de ruta: de MVP0 a SaaS [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- Cada MVP depende del anterior. Ninguno puede ser entregado sin el MVP0. Esta es la razón por la cual el Anonimizador no es « P0 » en el backlog — es**MVP0**. Es el primer entregable comercial, y todo lo demás está condicionado a su éxito. == Conclusion: el Trabajo Invisible que Lo Hace Todo Posible En una startup tradicional, la limpieza de datos está externalizada, manual o ignorada. En esta arquitectura, es el**corazón del producto**. El Anonimizador es el primer empleado porque sin él, nada funciona : * Sin MVP0 → no hay RAG legal (MVP1) * Sin MVP0 → sin ajuste fino sin fuga de datos (EPIC 5) * Sin MVP0 → no SaaS creíble (MVP3) * Sin MVP0 → sin realidad aumentada en el prompt * Sin MVP0 → no hay tercer camino de contexto (SQL DDD) Él hace el trabajo sucio. Nunca será mencionado en los pitchs. Pero es él quien hace funcionar la fábrica. Y es por eso que lo contratan primero. == Referencias * Artículo sobre la ontología espacial y los círculos de confianza:link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[La Ontología Espacial como Mecanismo de Alineación] * Artículo sobre la gobernanza del agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gobernar un agente IA con AsciiDoc] * Artículo sobre el mecanismo Hot/Warm/Cold :link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Ventana deslizante y ola fría] * Artículo sobre la comparación de los tres LLMs:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_que_hace_que_todos_huyan">El Problema que Hace que Todos Huyan</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura: 12 minutes</div> <p>No contrato un LLM. Contrato un anonimizador. Antes de hacer RAG pgvector, antes de ajustar finamente a expertos CDA/FPA, antes de aprovisionar los workspaces de los clientes — alguien debe limpiar los baños de los datos. Este empleado es el experto en anonimización (MVP0, EPIC 2 de codebase-gradle). Y es él quien hace que el producto sea comercializable.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_que_hace_que_todos_huyan">El Problema que Hace que Todos Huyan</h2> <div class="sectionbody"> <div class="paragraph"> <p>Toda startup de IA que manipule datos de entrenamiento se encuentra con la misma barrera :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- Resultado: o bien haces RAG sobre datos sucios (alucinaciones de PII, no conformidad con el RGPD, riesgo legal), o bien no haces nada (sin producto). La tercera vía — limpiar a mano — no es escalable. Mi respuesta: no evitar el problema. L'**automatizar**. == MVP0 : El Anonimizador, Primer Contratado en Periodo de Prueba El MVP0 no es una característica. Es un**experto de comodidad**— un empleado que hace el trabajo sucio, tonto y malvado, y del que nadie quiere hablar en los pitch decks. Lo que hace : [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- Detecta los patrones más obvios primero (emails`.*@.*`, tokens`sk-*`, `ghp_*`), IP), luego aprende. El período de prueba, eso es: validamos que no deje pasar falsos negativos antes de titularlo. == Lo que este MVP desbloquea (y no es solo el cumplimiento) La anonimización como MVP0 no es el peaje del RGPD antes de la autopista. Es la autopista misma. Esto es lo que abre: === Presente : Realidad Aumentada en Prompt [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- El RAG no busca en datos sucios — busca en un espacio**limpio por construcción**. Cambia todo para la calidad de las respuestas: el LLM no pasa su tiempo evitando las PII que reconoce pero que no debe mencionar. === Futuro: Ajuste fino sobre datos sanos [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- El ajuste fino en datos brutos es una catástrofe jurídica potencial. En datos limpios, es una**método reproducible**. Cada cliente acumula sus datasets limpios, cada cliente puede ajustar fino sus expertos de negocio sobre sus datos — sin exponer nunca un dato personal. == ¿Por qué es comercializable? No es « una herramienta de conformidad RGPD ». Es una**método reproducible que transforma un problema universal en activo**: 1. *Toda empresa de formación tiene datos sucios* — eso es el problema 2. *Ninguna tiene un pipeline automatizado de limpieza multi‑fuente* — es el mercado 3. *El bucle: anonimización → RAG → fine-tuning es propietario* — es la barrera El SaaS Edster (MVP3) no venderá « un workspace Gradle ». Venderá este bucle cerrado. Y el MVP0 es la puerta de entrada. == El formato SQL como tercera vía de contexto La importación de datos estructurados no es solo un formato de intercambio. El esquema SQL (DDL) lleva el**modelo entidad-relación del dominio** : [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- Este DDL, una vez anonimizado (línea 4), se convierte en una fuente de contexto para el LLM. No es texto — del**modelo de negocio**. El RAG da el contenido (similaridad vectorial), Graphify da las relaciones (estructura exacta), y el esquema SQL da el**Domain-Driven Design implícito**: bounded contexts, agregados, value objects. El LLM comprende el dominio porque lee su esquema. == El roadmap : del MVP0 al SaaS [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- Cada MVP depende del anterior. Ninguno puede ser entregado sin el MVP0. Esa es la razón por la cual el Anonimizador no es « P0 » en el backlog — es**MVP0**. Es el primer entregable comercial, y todo lo demás está condicionado a su éxito. == Conclusión: el Trabajo Invisible que hace posible todo En una startup tradicional, la limpieza de datos está externalizada, manual o ignorada. En esta arquitectura, es el**corazón del producto**. El Anonimizador es el primer empleado porque sin él, nada funciona : * Sin MVP0 → sin RAG legal (MVP1) * Sin MVP0 → sin fine-tuning sin fuga de datos (EPIC 5) * Sin MVP0 → ningún SaaS creíble (MVP3) * Sin MVP0 → no hay realidad aumentada en prompt * Sin MVP0 → no hay tercera vía de contexto (SQL DDD) Él hace el trabajo sucio. Nunca será mencionado en los pitchs. Pero él es quien hace que la fábrica funcione. Y es por eso que lo contratamos primero. == Referencias * Artículo sobre la ontología espacial y los círculos de confianza:link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[La ontología espacial como mecanismo de la alineación] * artículo sobre el agente de gobernanza Eager/Lazy:link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gobernar un agente de IA con AsciiDoc] * Artículo sobre el mecanismo Hot/Warm/Cold :link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Ventana deslizante y ola de frío] * Artículo sobre la comparación de los tres LLMs:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html Thu, 30 Apr 2026 00:00:00 +0000 blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_constatación_la_ingeniería_de_prompts_es_un_castillo_de_arena">La constatación: la ingeniería de prompts es un castillo de arena</a></li> <li><a href="#_los_cuatro_círculos_de_confianza_una_ontología_espacial">Los Cuatro Círculos de Confianza: una Ontología Espacial</a> <ul class="sectlevel2"> <li><a href="#_el_jardín_secreto_el_espacio_fuera_de_cvs">El Jardín Secreto: el Espacio fuera de CVS</a> <ul class="sectlevel3"> <li><a href="#_el_gitignore_como_configuración_de_gobernanza">El <code>.gitignore</code> como Configuración de Gobernanza</a></li> <li><a href="#_el_mecanismo_de_snapshot">El Mecanismo de Snapshot</a></li> </ul> </li> <li><a href="#_el_cofre_fuerte_configuration_como_spring_cloud_config">El Cofre-Fuerte: <code>configuration/</code> como Spring Cloud Config</a></li> <li><a href="#_la_biblioteca_office_como_data_consumible">La Biblioteca : <code>office/</code> como Data Consumible</a></li> <li><a href="#_las_forjas_foundry_como_implementación">Las Forjas : <code>foundry/</code> como Implementación</a></li> </ul> </li> <li><a href="#_proscontras_alineamiento_espacial_vs_alineamiento_por_prompt">Pros/Contras : Alineamiento Espacial vs Alineamiento por Prompt</a> <ul class="sectlevel2"> <li><a href="#_enfoque_clásico_a_lineación_por_pre_prompt">Enfoque Clásico : A lineación por Pre-Prompt</a></li> <li><a href="#_este_enfoque_alineación_por_ontología_espacial">Este Enfoque: Alineación por Ontología Espacial</a></li> </ul> </li> <li><a href="#_la_álgebra_relacional_del_workspace_y_el_delta_observable">La Álgebra Relacional del Workspace y el Delta Observable</a></li> <li><a href="#_el_vector_compuesto_de_contexto_rag_pgvector_graphify">El Vector Compuesto de Contexto: RAG + pgvector + Graphify</a> <ul class="sectlevel2"> <li><a href="#_componente_1_rag_langchain4j_postgresql_pgvector">Componente 1 — RAG LangChain4j + PostgreSQL pgvector</a></li> <li><a href="#_componente_2_knowledge_graph_graphify">Componente 2 — Knowledge Graph Graphify</a></li> <li><a href="#_componente_3_graphify_incremental_disperso_agregable_consumible">Componente 3 — Graphify incremental : Disperso, Agregable, Consumible</a></li> </ul> </li> <li><a href="#_clasificación_rgpd_automática_el_llm_como_enrutador">Clasificación RGPD Automática : el LLM como Enrutador</a></li> <li><a href="#_roadmap_desde_asciidoc_hasta_langgraph4j">Roadmap : desde AsciiDoc hasta LangGraph4j</a></li> <li><a href="#_lo_que_esta_arquitectura_resuelve_y_lo_que_no_resuelve">Lo que esta arquitectura resuelve (y lo que no resuelve)</a></li> <li><a href="#_conclusión_la_arquitectura_como_discurso">Conclusión: la arquitectura como discurso</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 20 minutes</div> <p>La ingeniería de prompts es frágil. A 80 000 tokens, tus reglas de alineación se pierden en el ruido, y el LLM olvida lo que le pediste al comienzo de la conversación. Mi solución? No alinear por el texto, sino por l'<strong>espacio</strong>. He estructurado mi espacio de trabajo de desarrollo en cuatro círculos de confianza concéntricos — del jardín secreto íntimo hasta las forjas públicas — y cada círculo es una zona física del sistema de archivos. El LLM no necesita que le recuerden las reglas: el camino del archivo las contiene. Así es como funciona, y por qué esta arquitectura de alineación por el espacio es más resiliente que un`system prompt`de 500 líneas.</p> </div> <div class="paragraph"> <p>Es un artículo largo.<br> Instálese cómodamente.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_constatación_la_ingeniería_de_prompts_es_un_castillo_de_arena">La constatación: la ingeniería de prompts es un castillo de arena</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante tres semanas, desarrollé plugins Gradle con Opencode, utilizando tres LLMs diferentes — Kimi K2.6, GLM-5.1 y DeepSeek-V4-Pro (el único sobreviviente, pero esa es otra historia<a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Ya cubierta aquí.</a> Mi método de gobernanza de agente <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Lo he documentado en detalle en un artículo anterior.</a> se basa en archivos AsciiDoc —<code>AGENT.adoc</code>, <code>INDEX.adoc</code>, <code>PROMPT_REPRISE.adoc</code>— que cargan aproximadamente 30 000 tokens de reglas, backlog e historial al inicio de cada sesión.</p> </div> <div class="paragraph"> <p>Y pese a esta infraestructura documental, dos cosas me llamaron la atención:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>El LLM olvida.</strong> Incluso con las reglas absolutas en la parte superior de cada archivo EAGER, más allá de 60 000 tokens acumulados (contexto inicial + conversación), Kimi K2.6 ha empezado a ofrecer`Write`aplastantes en archivos de configuración. GLM-5.1 confundió un token de Firebase con un placeholder que debía reemplazarse. Las reglas estaban escritas — el LLM ya no las <strong>veía</strong>.</p> </li> <li> <p><strong>La gobernanza misma se convierte en un problema.</strong> Después de haber implementado el mecanismo Hot/Warm/Cold<a href="0110_mecanisme_backup_contexte_agent_post.html">Artículo sobre la rotación de backup.</a> para evitar la explosión del contexto, mis archivos EAGER todavía pesaban 1414 líneas<a href="0111_audit_contexte_agent_post.html">He documentado esta auditoría aquí.</a> La gobernanza — diseñada para proteger al LLM de la saturación — saturaba al LLM.</p> </li> </ol> </div> <div class="paragraph"> <p>Necesitaba un mecanismo de alineación que no dependiera del número de tokens en el prompt.</p> </div> <div class="paragraph"> <p>La respuesta: dejar de alinear por el texto y comenzar a alinear por l'<strong>espacio</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_los_cuatro_círculos_de_confianza_una_ontología_espacial">Los Cuatro Círculos de Confianza: una Ontología Espacial</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mi expediente`workspace/<code>(dentro</code>~/workspace/`) <strong>no</strong> es un repositorio Git. Es la raíz de todo mi trabajo — código, documentación, formación, infraestructura. Y está estructurado en cuatro zonas que no son convenciones de organización, pero<strong>círculos de confianza concéntricos</strong>:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 13.3333%;"> <col style="width: 20%;"> <col style="width: 26.6666%;"> <col style="width: 33.3335%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">nivel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Etiqueta</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zona física</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CVS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Visibilidad</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Jardín secreto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`workspace/`raíz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ninguno</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Íntimo — pensamiento libre, sin commit, sin publicación</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>caja fuerte</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git privado (solo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secretos, tokens, archivo de visión. Una sola persona.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Biblioteca</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git privado (ampliado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dato pedagógico, SPG/SPD, esquemas JSON. Círculo de confianza identificado.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Forges (públicas)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git público (Apache 2.0)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Código fuente, plugins, pruebas, documentación técnica.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>NOTA: No hay nivel 3 en la tabla. El nivel 3 es un nivel <strong>transitorio</strong>: es contenido de`office/`que ha sido anonimizado y está listo para ser publicado como datos abiertos. No tiene una zona física propia — es un estado de los datos, no una ubicación.</p> </div> <div class="paragraph"> <p>Cada nivel responde a una pregunta precisa:</p> </div> <div class="ulist"> <ul> <li> <p><strong>¿Dónde depositar una idea que aún no está lista para ser compartida, incluso con un círculo reducido?</strong> → El jardín secreto. Sin Git. Sin presión.</p> </li> <li> <p><strong>¿Dónde almacenar un token API sin que se filtre?</strong> → Caja fuerte`configuration/`). Físicamente aislado. Ningún otro depósito puede referenciarlo por error.</p> </li> <li> <p><strong>¿Dónde co-construir un catálogo de formación con un OF piloto?</strong> → La biblioteca`office/`). Versionado, colaborativo, pero privado.</p> </li> <li> <p><strong>¿Dónde industrializar un plugin Gradle de código abierto?</strong> → Las forjas`foundry/`). Público, bifurcable, probado en CI.</p> </li> </ul> </div> <div class="paragraph"> <p>Esta ontología es<strong>consumible por un LLM</strong>. Cuando lee un archivo en`foundry/plantuml-gradle/src/`, lo sabe implícitamente: "estoy en el círculo 4 — código público, pruebas obligatorias, sin secretos, sin datos pedagógicos". No necesita un recordatorio que se lo recuerde.</p> </div> <div class="sect2"> <h3 id="_el_jardín_secreto_el_espacio_fuera_de_cvs">El Jardín Secreto: el Espacio fuera de CVS</h3> <div class="paragraph"> <p>Es el concepto más importante — y el más contraintuitivo.</p> </div> <div class="paragraph"> <p>la raíz`workspace/<code>no tiene</code>.git/<code>. Los documentos que viven allí (`WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>— y el que estás leyendo ahora mismo, que proviene de ello) no están destinados a ser versionados, compartidos, o incluso leídos por otra persona que yo. Son de<strong>pensamientos en germinación</strong>.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>El jardín secreto es <strong>out-of-CVS</strong> por naturaleza. La ausencia de versionado es la condición de la libertad de pensar. No se escribe allí para ser leído — se escribe allí para aclarar la propia visión.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Pero esta libertad tiene un costo: un`rm`accidental, y son meses de reflexión estratégica que desaparecen. La solución no es de versionar el jardín (eso sería destruirlo) — es de lo<strong>espejar</strong>en el círculo más restringido.</p> </div> <div class="sect3"> <h4 id="_el_gitignore_como_configuración_de_gobernanza">El <code>.gitignore</code> como Configuración de Gobernanza</h4> <div class="paragraph"> <p>En la raíz de`workspace/<code>, un archivo</code>.gitignore`mínimo declara la<strong>política de historicización</strong>de los archivos del jardín secreto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">.goosehints .goose</code></pre> </div> </div> <div class="paragraph"> <p>Ce <code>.gitignore`no tiene una función Git clásica (no hay</code>.git/`a la raíz). Él actúa como un<strong>archivo de configuración de gobernanza</strong>que responde a una pregunta específica: <strong>qué artefactos del jardín secreto merecen ser historicizados, y cuáles son puramente transitorios?</strong></p> </div> <div class="ulist"> <ul> <li> <p>Los archivos listados en`.gitignore`—<code>.goosehints</code>, <code>.goose</code>— son artefactos efímeros generados por los agentes. Sin valor stratégique. Sin historicización.</p> </li> <li> <p>Los archivos`.adoc`de la raíz —<code>WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WHAT_THE_GAMES_BEEN_MISSING.adoc</code>, <code>depots_implementes_strategie.adoc</code>, <code>synthese-LLMs-long-contexte.adoc</code>— no son<strong>paso</strong>en el`.gitignore`. Estos son los artefactos a historicizar.</p> </li> </ul> </div> <div class="paragraph"> <p>Le `.gitignore`es el<strong>esquema de gobernanza</strong>: todo lo que no esté listado allí es un candidato al snapshot. Y el LLM, al leer este archivo, sabe exactamente qué debe archivarse y qué puede ignorarse — sin necesidad de recordárselo en un prompt.</p> </div> </div> <div class="sect3"> <h4 id="_el_mecanismo_de_snapshot">El Mecanismo de Snapshot</h4> <div class="paragraph"> <p>He creado`configuration/vision-archive/<code>: unas instantáneas fechadas de todos los</code>.adoc`de la raíz, commits en el repositorio privado`configuration/`. Cada sesión de lluvia de ideas produce una instantánea:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">DATE=$(date +%Y-%m-%d) mkdir -p /home/cheroliv/workspace/configuration/vision-archive/$DATE cp /home/cheroliv/workspace/*.adoc /home/cheroliv/workspace/configuration/vision-archive/$DATE/ cd /home/cheroliv/workspace/configuration && git add vision-archive/ && \ git commit -m "vision-archive: snapshot $DATE"</code></pre> </div> </div> <div class="paragraph"> <p>El procedimiento se dispara al final de la sesión por el LLM mismo, que ejecuta esta tarea global de enrutamiento. Cada instantánea captura el estado completo del pensamiento estratégico en un momento T.</p> </div> <div class="paragraph"> <p>El historial de Git de`configuration/`se convierte en la<strong>biografía de mi pensamiento estratégico</strong>. Puedo hacer un`git log — vision-archive/`y ver la evolución de mi visión, sesión por sesión, fecha por fecha</p> </div> <div class="paragraph"> <p>Ejemplo real del historial después de un día de trabajo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">$ git -C configuration log --oneline -- vision-archive/ 1089d1b vision-archive: fin de session finale 2026-05-03 6b21eaf vision-archive: fin de session 2026-05-03-1300 1690f82 vision-archive: post-article 2026-05-03 28e6593 vision-archive: post-migration 2026-05-03 3707b78 vision-archive: snapshot 2026-05-03 — jardin secret initial</code></pre> </div> </div> <div class="paragraph"> <p>Cinco instantáneas en un día. Cada uno es un punto de restauración. Cada uno es un hito en la génesis de la estrategia.</p> </div> <div class="paragraph"> <p>El expediente`configuration/vision-archive/latest/`contiene permanentemente una<strong>copia de trabajo</strong>del último snapshot, que sirve como referencia rápida sin necesidad de navegar por el historial de Git.</p> </div> <div class="paragraph"> <p>Y para el LLM, es un<strong>oráculo de coherencia</strong>: cuando observa una contradicción entre la implementación actual y la visión archivada en una fecha anterior, puede señalarla.</p> </div> </div> </div> <div class="sect2"> <h3 id="_el_cofre_fuerte_configuration_como_spring_cloud_config">El Cofre-Fuerte: <code>configuration/</code> como Spring Cloud Config</h3> <div class="paragraph"> <p>`configuration/`No contiene solo el archivo de la visión. Su función principal — y futura — es ser un<strong>servidor Spring Cloud Config</strong>. Todos los secretos, tokens, credenciales y descriptores de infraestructura viven aquí, en un repositorio Git privado accesible únicamente por el propietario.</p> </div> <div class="paragraph"> <p>¿Por qué un repositorio separado en lugar de un archivo?<code>.env</code>¿en cada proyecto?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Push accidental de un secreto</strong> : imposible. Los secretos están en un repositorio privado que los proyectos públicos no pueden referenciar por error.</p> </li> <li> <p><strong>Auditoría</strong>: el historial de Git proporciona el rastro de cada modificación de configuración. quien cambió qué, cuando, con qué hash SHA.</p> </li> <li> <p><strong>Rollback</strong> :`git revert`sur una configuración dañada. Instantánea, sin backup manual.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_la_biblioteca_office_como_data_consumible">La Biblioteca : <code>office/</code> como Data Consumible</h3> <div class="paragraph"> <p>`office/`es el correspondiente documental del trabajo de desarrollo. Contiene los artículos de blog, las especificaciones técnicas, los materiales de formación (38 directorios de cursos FPA, SPG/SPD, esquemas JSON, taxonomías Bloom/Harrow/Krathwohl) — todo lo que constituye el<strong>material pedagógico</strong>.</p> </div> <div class="paragraph"> <p>Pero`office/`No es solo un cajón de docs. Es una<strong>fuente de datos estructurada</strong>que los plugins Gradle de`foundry/`consumen. Un artículo de blog en`office/`es una entrada que un plugin transformará en HTML. Un SPG AsciiDoc en`office/metiers/FPA/`es un artefacto que un orquestador parseará para generar diapositivas, cuestionarios y cápsulas de video.</p> </div> <div class="paragraph"> <p>Et le `build.gradle.kts`en la raíz de`office/`no es del código de negocio — es uno<strong>script de consumo del ecosistema de plugins</strong>. Él dice: "aquí están los plugins de Gradle que utilizo, aquí está el contexto de mi espacio de trabajo</p> </div> </div> <div class="sect2"> <h3 id="_las_forjas_foundry_como_implementación">Las Forjas : <code>foundry/</code> como Implementación</h3> <div class="paragraph"> <p><code>foundry/`contiene el<strong>código industrializado</strong>. 54 repositorios Git, de los cuales 7 actualmente gobernados por los</code>.agents/`. Aquí es donde la visión se vuelve ejecutable — plugins Gradle, CI/CD, pruebas JUnit5 + Cucumber.</p> </div> <div class="paragraph"> <p>La relación con`office/`es bidireccional:</p> </div> <div class="ulist"> <ul> <li> <p><code>office/</code>→<code>foundry/</code>: los datos pedagógicos son la materia prima que los plugins consumen.</p> </li> <li> <p><code>foundry/</code>→<code>office/</code>: los plugins producen datos que enriquecen`office/` — le `graph.json`de graphify-gradle, los decks slider compilados, los informes de compilación</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_proscontras_alineamiento_espacial_vs_alineamiento_por_prompt">Pros/Contras : Alineamiento Espacial vs Alineamiento por Prompt</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comparemos los dos enfoques.</p> </div> <div class="sect2"> <h3 id="_enfoque_clásico_a_lineación_por_pre_prompt">Enfoque Clásico : A lineación por Pre-Prompt</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌ Contra</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fácil de implementar. Un bloque de texto en el system prompt.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Frágil al contexto largo</strong> : la regla se pierde después de 80K tokens.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Funciona para reglas generales (tono, formato).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>No verificable</strong> : nada impide que el LLM viole la regla.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No es necesario repensar la arquitectura del proyecto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>No transferible</strong> : cada repositorio redeclara las reglas.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Declarativo puro</strong>: el LLM sabe que <strong>debería</strong>, pero nada le impide.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_este_enfoque_alineación_por_ontología_espacial">Este Enfoque: Alineación por Ontología Espacial</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌ Contra</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Resiliente al contexto largo</strong> : la regla está en la ruta del archivo, no en un prompt distante.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Costo de infraestructura inicial</strong> : estructurar el workspace en círculos lleva tiempo.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>verificable mecánicamente</strong> : un secreto en`foundry/<code>es detectable por`git check-ignore</code>.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Requiere disciplina</strong> : un nuevo contribuidor debe entender los círculos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Transferible</strong> : un`AGENT.adoc`estándar expone los círculos a cualquier nuevo proyecto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Solo cubre las restricciones espaciales</strong> — el estilo de código permanece en el prompt.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Seguridad por diseño</strong> : uno`git push`desde`foundry/<code>no puede exponer`configuration/</code>.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Consumible por agentes no LLM</strong> : un orquestrador Gradle puede enrutar según el círculo.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>El beneficio principal no es defensivo (seguridad, visibilidad) — es<strong>creativo</strong>. Cuando el LLM trabaja en un espacio estructurado por una ontología, puede hacer lo que ningún prompt le permite: <strong>observar el delta</strong>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_álgebra_relacional_del_workspace_y_el_delta_observable">La Álgebra Relacional del Workspace y el Delta Observable</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando el LLM recorre`foundry/<code>, él tiene un<strong>malla de datos estructurados</strong>: nodos (plugins, archivos, pruebas, dependencias), aristas tipadas (`import</code>, <code>depends_on</code>, <code>generates</code>, <code>tests</code>), relaciones de composición y orden (`training-gradle`extraer el repositorio →`slider-gradle`genera las diapositivas →`capsule-gradle`reproduce el video)</p> </div> <div class="paragraph"> <p>Esta álgebra no está escrita en ninguna parte de forma clara — pero es <strong>observable</strong>. Cada`build.gradle.kts`expone las dependencias. Cada`INDEX.adoc`expone referencias cruzadas.</p> </div> <div class="paragraph"> <p>El LLM observa este álgebra y detecta el<strong>delta</strong>: la brecha entre lo que el sistema ya sabe producir y lo que la visión describe.</p> </div> <div class="paragraph"> <p>A partir de este delta, puede definir<strong>cartografías de expertos en oficios</strong>— CDA (Diseñador desarrollador de aplicaciones, Kotlin/Gradle/JHipster) y FPA (Formador profesional de adultos, Pedagogía/Qualiopi/Bloom) — e identificar lo que falta para cada experto.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Expert CDA (Kotlin/Gradle/JHipster) ├── Plugins : jhipster-gradle-plugins, plantuml-gradle, │ codebase-gradle ├── Delta : pas encore de SPG CDA formalisé, │ pas de fine-tuning expert CDA Expert FPA (Pédagogie/Qualiopi/Bloom) ├── Plugins : training-gradle, slider-gradle, │ school-backoffice/forms, capsule-gradle ├── Matériel : 38 modules cours, SPG/SPD, taxonomies └── Delta : parser AsciiDoc→JSON à créer, orchestrateur à coder</code></pre> </div> </div> <div class="paragraph"> <p>El LLM no necesita que le digan qué hacer. El delta emerge de la estructura.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_vector_compuesto_de_contexto_rag_pgvector_graphify">El Vector Compuesto de Contexto: RAG + pgvector + Graphify</h2> <div class="sectionbody"> <div class="paragraph"> <p>El álgebra relacional no es una construcción teórica. Está <strong>materializada</strong> por tres componentes que forman un<strong>vector compuesto de contexto</strong>para el LLM.</p> </div> <div class="sect2"> <h3 id="_componente_1_rag_langchain4j_postgresql_pgvector">Componente 1 — RAG LangChain4j + PostgreSQL pgvector</h3> <div class="paragraph"> <p>Ya tengo LangChain4j en producción en dos plugins :`slider-gradle`(4 proveedores LLM) y`plantuml-gradle`(7 proveedores). Los embeddings ONNX (AllMiniLmL6V2) indexan los datos de`office/`y el código fuente de`foundry/`en PostgreSQL + pgvector.</p> </div> <div class="paragraph"> <p>Este RAG opera en dos dimensiones :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Dimension data</strong> : los documentos`office/`(SPG, artículos, formaciones, esquemas JSON)</p> </li> <li> <p><strong>Dimension code</strong> : las bases de código`foundry/`(fuentes Kotlin, pruebas Cucumber, AGENT.adoc)</p> </li> </ul> </div> <div class="paragraph"> <p>La intersección cubre tanto el <strong>qué</strong> (el dominio del negocio) como el <strong>cómo</strong> (la implementación).</p> </div> </div> <div class="sect2"> <h3 id="_componente_2_knowledge_graph_graphify">Componente 2 — Knowledge Graph Graphify</h3> <div class="paragraph"> <p>Graphify está integrado en`plantuml-gradle`(109 tests, 380/380 PASS) y produce un`graph.json`— un knowledge graph estructurado con nodos, aristas y comunidades detectadas automáticamente.</p> </div> <div class="paragraph"> <p>A diferencia del RAG que opera por similitud vectorial (difuso), el knowledge graph opera por<strong>relaciones exactas</strong>(determinista) :`graphify query`para las consultas semánticas (~50 tokens)`graphify path`para navegar`graphify explain`para explicar.</p> </div> </div> <div class="sect2"> <h3 id="_componente_3_graphify_incremental_disperso_agregable_consumible">Componente 3 — Graphify incremental : Disperso, Agregable, Consumible</h3> <div class="paragraph"> <p>Es la decisión arquitectónica clave.</p> </div> <div class="paragraph"> <p>Graphify no debe vivir en un único repositorio. Debe vivir de manera<strong>disperso</strong>en cada plugin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Cada plugin</strong> incorpora una tarea Gradle`updateKnowledgeGraph`que llama a Graphify<strong>en su propio alcance</strong>y produce un`graph.json`local.</p> </li> <li> <p><strong>El script de compilación de`office/<code></strong> consume`graphify-gradle`con`rootDir = /home/cheroliv/workspace`y produce un`graph.json</code> <strong>global</strong>que agrega los grafos locales.</p> </li> <li> <p><strong>El RAG de cada plugin</strong> inyecta el`graph.json`global como<strong>filtro de contexto</strong>para las consultas LLM.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">TÂCHE GRADLE (dans chaque plugin) ↓ graphify → graph.json (scope local) ↓ office/build.gradle.kts → graph.json (scope global) ↓ RAG pgvector (dans slider, plantuml, codebase...) ↓ ← injection du graph.json comme filtre LLM (deepseek-v4-pro) ↓ ← observation algèbre relationnelle ↓ ← détection delta vs cartographies experts PRIORISATION → prochaine tâche</code></pre> </div> </div> <div class="paragraph"> <p>Resultado: el LLM no busca en el vacío — se desplaza en un espacio estructurado por el knowledge graph. Una consulta sobre "génère un diagramme" sabe alcanzar los nodos pertinentes del grafo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_clasificación_rgpd_automática_el_llm_como_enrutador">Clasificación RGPD Automática : el LLM como Enrutador</h2> <div class="sectionbody"> <div class="paragraph"> <p>La ontología espacial no se limita a alinear el LLM — le da una<strong>cuadro de clasificación RGPD</strong>para enrutar cada dato hacia su zona legítima</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 12.5%;"> <col style="width: 37.5%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Criterio</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detección LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Acción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nivel máximo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dato personal (nombre, correo electrónico, IP)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">patrón`@`, IP, nombres propios</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonimizar →`[OF_PILOTE]`o router de nivel 2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Token / Secreto / Credencial</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Patrón`sk-…​<code>, `ghp_…​</code>, <code>ya29…​</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Enrutador →<code>configuration/</code>. Referenciar por`${VAR}`en el código.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">URL interna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contiene`localhost`, IP privada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonimizar →<code>${API_URL}</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dato pedagógico (SPG, curso)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estructura Bloom/Qualiopi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Enrutador →<code>office/</code>(nivel 2). Versión doble si exporta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Código fuente / prueba</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensión`.kt`, <code>.kts`dentro`foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Router →<code>foundry/</code>. Verificar ausencia de secretos.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Al final de la sesión, el LLM ejecuta una<strong>tarea global</strong></think></p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Lectura del`.gitignore`raíz para identificar los artefactos efímeros (para excluir del snapshot) vs los artefactos estratégicos (para historizar)</p> </li> <li> <p>Inventario de todos los archivos`.adoc`de la raíz`workspace/`</p> </li> <li> <p>Filtrado: exclusión de los archivos enumerados en`.gitignore`, inclusión de todos los demás</p> </li> <li> <p>Copia en`configuration/vision-archive/$DATE/<code>y actualización del symlink`latest/</code></p> </li> <li> <p>Commit en el repositorio`configuration/`con un mensaje estructurado</p> </li> <li> <p>Clasificación automática RGPD de cada archivo modificado (todos los círculos)</p> </li> <li> <p>Enrutamiento: datos`office/<code>→ commit privado, código`foundry/</code>→<code>./gradlew check</code>, configuración → commit</p> </li> <li> <p>Informe estructurado con alertas RGPD y confirmación de archivaje</p> </li> </ol> </div> <div class="paragraph"> <p>Le `.gitignore`raíz no es un archivo de configuración de Git — es un<strong>archivo de gobernanza de la historicización</strong>. Define el esquema que el LLM consume para decidir qué archivos del jardín secreto entran en la biografía estratégica y cuáles son descartables.</p> </div> <div class="paragraph"> <p>El LLM ya no es un simple generador de texto. Él es el<strong>gestor de información</strong>del ecosistema — productor, clasificador, enrutador.</p> </div> </div> </div> <div class="sect1"> <h2 id="_roadmap_desde_asciidoc_hasta_langgraph4j">Roadmap : desde AsciiDoc hasta LangGraph4j</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hoy, esta gobernanza es <strong>determinista</strong> : el LLM aplica un procedimiento descrito en archivos AsciiDoc. Es la<strong>fase 1</strong>— la ingeniería de prompts con memoria LLM.</p> </div> <div class="paragraph"> <p>La <strong>fase 2</strong>extraerá cada paso del procedimiento en una<strong>tarea Gradle tipada</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">./gradlew endSessionWorkspace → snapshot vision-archive ./gradlew endSessionProject → archive .agents/ ./gradlew endSessionReport → rapport multi-zones</code></pre> </div> </div> <div class="paragraph"> <p>La <strong>fase 3</strong>modelará el proceso de fin de sesión como un<strong>grafo de estado</strong>conhttps://github.com/langgraph4j/langgraph4j[LangGraph4j] :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Start] → [Inventaire fichiers modifiés] → [Classification RGPD] (nœud ONNX) → [Branchement par cercle] ├→ cercle 0 → snapshot → commit ├→ cercle 2 → anonymisation → commit ├→ cercle 4 → archive → commit └→ cercle 1 → commit configuration/ → [Rapport] → [End]</code></pre> </div> </div> <div class="paragraph"> <p>Este grafo será versionado en la CI/CD, ejecutado por Gradle, configurado a través de los GitHub Secrets de los plugins. El LLM ya no tendrá que decidir el enrutamiento — el grafo lo hará.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_esta_arquitectura_resuelve_y_lo_que_no_resuelve">Lo que esta arquitectura resuelve (y lo que no resuelve)</h2> <div class="sectionbody"> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>La ontología espacial no cubre todo. Las convenciones de estilo de código, el nombre, las decisiones de diseño arquitectónico — todo eso permanece en el prompt. Lo que resuelve la ontología espacial es<strong>capa de seguridad y visibilidad</strong>donde cada octeto debe vivir, y quién puede verlo.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Esto es lo que aporta concretamente:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>No`git push`accidental de un secreto</strong>: los secretos están en`configuration/<code>(círculo 1). Los proyectos públicos están en`foundry/</code>(círculo 4). Ningún camino cruza los dos.</p> </li> <li> <p><strong>No hay código de negocio en los datos</strong> :`office/<code>contiene de</code>.adoc`, de YAML, de esquemas JSON — pero no de`.kt`. Le `build.gradle.kts`quien vive allí es un script de consumo, no código de negocio.</p> </li> <li> <p><strong>Sin pensamiento estratégico expuesto</strong> : los documentos de visión viven en el jardín secreto (raíz fuera-CVS). Los snapshots están en`configuration/`(cofre fuerte privado). Nadie, incluso en un círculo de confianza ampliado, lee el origen de la estrategia.</p> </li> <li> <p><strong>Auto-priorización</strong>: El LLM observa el delta entre el álgebra relacional (lo que existe) y los mapas de expertos (lo que es necesario). La próxima tarea de desarrollo surge de este delta.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_la_arquitectura_como_discurso">Conclusión: la arquitectura como discurso</h2> <div class="sectionbody"> <div class="paragraph"> <p>No pongo un manifiesto político en el footer de mi sitio. No pongo normas éticas en mis prompts. La alineación no está en el texto — está en el<strong>sistema de archivos</strong>.</p> </div> <div class="paragraph"> <p>Cuando un LLM trabaja en este espacio, no puede filtrar un secreto (el camino se lo impide). No puede confundir un dato pedagógico con código fuente (el área física es diferente). No puede olvidar una regla de seguridad de 80 000 tokens — porque la regla no está en el prompt, está en el`workspace/` → <code>configuration/</code>→<code>office/</code>(output nothing)`foundry/`que cada lectura de archivo sea reactiva</p> </div> <div class="paragraph"> <p>Es el principio de <strong>secure by design</strong> aplicado al alineamiento del agente: no pedir al LLM que recuerde las reglas. Hacer que la arquitectura haga que el error sea estructuralmente imposible.</p> </div> <div class="paragraph"> <p>Así que, de paso, le da al LLM lo que ningún prompt puede darle: la capacidad de<strong>percibir</strong>dónde está, lo que existe, lo que falta — y deducir de ello lo que debe hacer.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Artículo sobre la gobernanza agent Eager/Lazy<a href="../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Gobernar un agente de IA con AsciiDoc</a></p> </li> <li> <p>Artículo sobre el mecanismo Hot/Warm/Cold:<a href="../2026/0110_mecanisme_backup_contexte_agent_post.html">Ventana deslizante y onda fría</a></p> </li> <li> <p>Artículo sobre la auditoría de contexto :<a href="../2026/0111_audit_contexte_agent_post.html">Cuando su propia gobernancia se convierte en el problema</a></p> </li> <li> <p>Artículo sobre la comparación de los tres LLMs:<a href="../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0113_integration_firebase_contact_form_post.html Wed, 29 Apr 2026 00:00:00 +0000 blog/2026/0113_integration_firebase_contact_form_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_un_formulario_que_no_almacena_nada">La escena : un formulario que no almacena nada</a> <ul class="sectlevel2"> <li><a href="#_la_herencia_supabase">La herencia Supabase</a></li> <li><a href="#_el_doble_envío_fantasma">El doble envío fantasma</a></li> </ul> </li> <li><a href="#_por_qué_firebase_en_lugar_de_supabase">¿Por qué Firebase en lugar de Supabase?</a></li> <li><a href="#_fase_1_crear_el_proyecto_firebase">Fase 1 : Crear el proyecto Firebase</a> <ul class="sectlevel2"> <li><a href="#_inicialización">Inicialización</a></li> <li><a href="#_reglas_de_seguridad_de_firestore">Reglas de seguridad de Firestore</a></li> </ul> </li> <li><a href="#_phase_2_reescribir_el_javascript_de_envío">Phase 2 : Reescribir el JavaScript de envío</a> <ul class="sectlevel2"> <li><a href="#_la_dependencia_window_firebase">La dependencia `window.<em>FIREBASE</em></a></li> <li><a href="#_el_nuevo_contact_js">El nuevo `contact.js</a></li> </ul> </li> <li><a href="#_fase_3_limpiar_el_código_muerto_supabase">Fase 3: Limpiar el código muerto Supabase</a></li> <li><a href="#_fase_4_configurar_el_pie_de_página">Fase 4 : Configurar el pie de página</a></li> <li><a href="#_fase_5_arquitectura_final">Fase 5 : Arquitectura final</a></li> <li><a href="#_lo_que_esta_migración_dice_sobre_el_dogfooding">Lo que esta migración dice sobre el dogfooding</a> <ul class="sectlevel2"> <li><a href="#_resumen_de_los_cambios">Resumen de los cambios</a></li> </ul> </li> <li><a href="#_próximos_pasos_backlog">Próximos pasos (backlog)</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>Durante meses, el formulario de contacto de este sitio funcionó sobre un mock JavaScript — una promesa a 85 % de éxito, un falso Firestore, cero datos almacenados. El plan inicial preveía un backend Supabase con Google Apps Script para las notificaciones por correo electrónico. Abandonado. Hoy cuento la migración a Firebase Firestore: creación del proyecto, reglas de seguridad, reescritura del JS, limpieza del código muerto de Supabase. Y por qué esta elección dice algo más amplio sobre la filosofía de desarrollo.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_un_formulario_que_no_almacena_nada">La escena : un formulario que no almacena nada</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este sitio es generado por JBake, mi plugin Gradle`bakery`. Es 100 % estático — sin backend, sin base de datos. Excepto que tengo un formulario de contacto. La página`contact.html`existe, el HTML está listo (campos nombre, correo electrónico, teléfono, asunto, mensaje, validación HTML5, honeypot anti-spam), los estilos Bootstrap están en su lugar. Visualmente, todo es perfecto.</p> </div> <div class="paragraph"> <p>Excepto que al momento de la presentación, nada ocurre.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseMock = new Promise((resolve, reject) => { setTimeout(() => { if (Math.random() < 0.85) { resolve({ status: 201, message: 'Message stored in Firestore.' }); } else { reject({ status: 500, message: 'Firestore write failed.' }); } }, 1500); });</code></pre> </div> </div> <div class="paragraph"> <p>Un mock. Una promesa que finge. El usuario ve un spinner, luego un mensaje « ¡Mensaje enviado con éxito! ». Pero los datos se van al vacío. Ningún mensaje se almacena en ningún sitio.</p> </div> <div class="paragraph"> <p>La situación es peor que un formulario roto — es un formulario que miente.</p> </div> <div class="sect2"> <h3 id="_la_herencia_supabase">La herencia Supabase</h3> <div class="paragraph"> <p>El plan inicial, documentado en`content/draft/integration_formulaire_contact_supabase.adoc`, preveía :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Una base de Supabase con tabla`contacts`y Row Level Security</p> </li> <li> <p>Una RPC`handle_contact_form`lado servidor</p> </li> <li> <p>Un desencadenador SQL que llama a un webhook de Google Apps Script</p> </li> <li> <p>Google Apps Script que envía un correo Gmail de notificación</p> </li> </ol> </div> <div class="paragraph"> <p>El código JavaScript correspondiente todavía existe en`script.js`. Hay una clase`SupabaseManager`que inicializa un cliente Supabase con variables globales`SUPABASE_URL` et <code>SUPABASE_KEY</code>, y una clase`ContactFormHandler`que escucha el evento submit del formulario y llama`SupabaseManager.submitContactForm()`.</p> </div> <div class="paragraph"> <p>Problema: estas variables globales ya no se inyectan en el pie de página. Le`<script src="supabase-js">`ha sido retirado. El código llama`supabase.createClient()`sobre una variable`supabase`que ya no existe. Por lo tanto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">console.error : 'Supabase client library (supabase-js) is not loaded.'</code></pre> </div> </div> <div class="paragraph"> <p>No solo los datos no se almacenan, sino que el código de envío está muerto.</p> </div> </div> <div class="sect2"> <h3 id="_el_doble_envío_fantasma">El doble envío fantasma</h3> <div class="paragraph"> <p>Para empeorar las cosas, hay una<strong>competencia silenciosa</strong>entre dos handlers en el mismo formulario :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>`contact.js`Escucha el submit, llama al mock Firebase</p> </li> <li> <p><code>script.js</code>— via`ContactFormHandler`— escucha también el submit, llama`SupabaseManager`</p> </li> </ol> </div> <div class="paragraph"> <p>Los dos hacen`event.preventDefault() + event.stopPropagation()<code>. Como`contact.js`se carga primero en`footer.thyme</code>, su manejador se adjunta en primer lugar. Bloquea la propagación.`ContactFormHandler`nunca se disparará.</p> </div> <div class="paragraph"> <p>No es ni siquiera un bug activo — es un zombie. Código que nunca tiene la oportunidad de ejecutarse.</p> </div> <div id="diag-before" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE title Estado Inicial — Formulario de Contacto rectangle "contact.thyme (HTML Bootstrap, honeypot)" as FORM ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Estado Inicial — Formulario de Contacto rectangle "contact.thyme (HTML Bootstrap, honeypot)" as FORM rectangle "footer.thyme (Firebase SDK con config placeholder)" as FOOT rectangle "contact.js\n(Firebase simulado, 85% éxito)" as CONT rectangle "script.js\n(SupabaseManager + ContactFormHandler, muertos)" as SCRIPT rectangle "Usuario" as USER USER -> FORM : Soumission du formulaire FORM -> CONT : submit event (attaché en premier) CONT -> CONT : preventDefault + stopPropagation CONT -> CONT : mock Promise (1.5s, aléatoire) note right of CONT ⚠️ Aucune donnée stockée end note FORM ..> SCRIPT : submit event (bloqué par stopPropagation) note right of SCRIPT : ❌ Jamais déclenché note right of SCRIPT : ❌ supabase-js non chargé @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_firebase_en_lugar_de_supabase">¿Por qué Firebase en lugar de Supabase?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La decisión de migración está documentada en`AGENT.adoc` :</p> </div> <div class="paragraph"> <p>Firebase se elige ahora por las siguientes razones: mejor plan gratuito, Firestore nativo, Cloud Functions integradas, ecosistema de Google más adecuado. La implementación existente de Supabase está marcada como « ⚠️ Abandonado ».</p> </div> <div class="paragraph"> <p>Más allá del plan gratuito hay una razón arquitectónica. Este sitio vive en el ecosistema de Google: el repositorio de destino es`cheroliv.github.io`, el CNAME apunta a GitHub Pages, la compilación Gradle push a GitHub a través de JGit. Añadir un servicio de Google (Firebase) en lugar de un servicio de terceros (Supabase) reduce la superficie de dispersión.</p> </div> <div class="paragraph"> <p>Firestore en modo nativo (no modo Datastore) también está más cerca del modelo mental de documento NoSQL que tengo en mente: colecciones, documentos, campos tipados, marcas de tiempo del servidor, reglas de seguridad integradas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_1_crear_el_proyecto_firebase">Fase 1 : Crear el proyecto Firebase</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_inicialización">Inicialización</h3> <div class="paragraph"> <p>Como la CLI de Firebase no está instalada en mi máquina, paso por la consola web :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ir sobrehttps://console.firebase.google.com/[Consola de Firebase]</p> </li> <li> <p>Crear un proyecto`cheroliv-contact`(o reutilizar un proyecto existente)</p> </li> <li> <p>Activar Firestore en modo nativo (no Datastore)</p> </li> <li> <p>Crear una base de datos en región`eur3`(Europa)</p> </li> </ol> </div> <div class="paragraph"> <p>Para un uso minimalista como el nuestro (una sola colección, escritura pública), el modo nativo es la buena opción. No se necesitan reglas Datastore complejas.</p> </div> </div> <div class="sect2"> <h3 id="_reglas_de_seguridad_de_firestore">Reglas de seguridad de Firestore</h3> <div class="paragraph"> <p>El formulario es público — cualquiera puede enviar un mensaje. Pero quiero limitar los abusos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /contact_messages/{messageId} { // Lecture : admin uniquement (authentifié) allow read: if request.auth != null; // Écriture : publique, mais limitée allow create: if request.auth == null && request.resource.data.name is string && request.resource.data.name.size() >= 1 && request.resource.data.name.size() <= 100 && request.resource.data.email is string && request.resource.data.email.matches('.*@.*\\..*') && request.resource.data.email.size() <= 254 && request.resource.data.subject is string && request.resource.data.subject.size() >= 3 && request.resource.data.subject.size() <= 200 && request.resource.data.message is string && request.resource.data.message.size() >= 10 && request.resource.data.message.size() <= 5000 && request.resource.data.created_at == request.time && request.resource.data.user_agent is string && request.resource.data.user_agent.size() <= 500; } } }</code></pre> </div> </div> <div class="paragraph"> <p>Puntos clave:</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code>— solo los usuarios autenticados pueden leer los mensajes (yo, a través de la consola de Firebase)</p> </li> <li> <p><code>allow create</code>— cualquiera puede crear un documento, pero con validación de campos</p> </li> <li> <p>Validación del lado servidor : tamaños mín/máx, formato de email,<code>created_at`debe corresponder a`request.time</code>(anti-falsificación)</p> </li> <li> <p>`user_agent`se envía para trazabilidad (no crítico pero útil)</p> </li> </ul> </div> <div class="paragraph"> <p>Estas reglas son más estrictas que un simple`allow write: if true;`. Evitan que un atacante inyecte cargas útiles enormes o campos mal formados.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_reescribir_el_javascript_de_envío">Phase 2 : Reescribir el JavaScript de envío</h2> <div class="sectionbody"> <div class="paragraph"> <p>El contrato es sencillo:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Leer los datos del formulario</p> </li> <li> <p>Comprobar el honeypot (campo)<code>hp_name</code>— si está lleno, es un bot, simulamos un éxito sin enviar nada)</p> </li> <li> <p>llamar`addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})`</p> </li> <li> <p>Mostrar éxito o error</p> </li> </ol> </div> <div class="sect2"> <h3 id="_la_dependencia_window_firebase">La dependencia `window.<em>FIREBASE</em></h3> <div class="paragraph"> <p>en`footer.thyme`, un script de módulo inicializa el SDK de Firebase y expone un objeto global :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><script type="module"> import { initializeApp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-app.js"; import { getFirestore, collection, addDoc, serverTimestamp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-firestore.js"; const firebaseConfig = { /* valeurs réelles */ }; const app = initializeApp(firebaseConfig); const db = getFirestore(app); window.__FIREBASE__ = { db, collection, addDoc, serverTimestamp }; </script></code></pre> </div> </div> <div class="paragraph"> <p>Los scripts del módulo se ejecutan antes`DOMContentLoaded`, entonces`window.<em>FIREBASE</em>`Se garantiza que esté disponible cuando el handler`contact.js`Como precaución, agrego igualmente un polling de 5 segundos por si el CDN estuviera lento.</p> </div> </div> <div class="sect2"> <h3 id="_el_nuevo_contact_js">El nuevo `contact.js</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function () { 'use strict'; const form = document.getElementById('contact-form'); if (!form) return; const submitButton = form.querySelector('button[type="submit"]'); const successMessage = document.getElementById('contact-success-message'); const errorMessage = document.getElementById('contact-error-message'); // Éléments de validation const nameInput = form.querySelector('input[name="name"]'); const emailInput = form.querySelector('input[name="email"]'); const phoneInput = form.querySelector('input[name="phone"]'); const subjectInput = form.querySelector('input[name="subject"]'); const messageInput = form.querySelector('textarea[name="message"]'); const honeypotInput = form.querySelector('input[name="hp_name"]'); /** * Attend que window.__FIREBASE__ soit disponible. * Timeout de 5 secondes — si le CDN Firebase est lent, on abandonne. */ function waitForFirebase(timeoutMs = 5000) { return new Promise((resolve, reject) => { if (window.__FIREBASE__) { resolve(window.__FIREBASE__); return; } const start = Date.now(); const interval = setInterval(() => { if (window.__FIREBASE__) { clearInterval(interval); resolve(window.__FIREBASE__); } else if (Date.now() - start > timeoutMs) { clearInterval(interval); reject(new Error('Firebase SDK non disponible après timeout')); } }, 100); }); } // --- Validation (identique à l'existant) --- function validateForm() { nameInput.setCustomValidity(''); emailInput.setCustomValidity(''); if (phoneInput) phoneInput.setCustomValidity(''); subjectInput.setCustomValidity(''); messageInput.setCustomValidity(''); if (nameInput.value.trim().length < 1) { nameInput.setCustomValidity('Veuillez saisir votre nom.'); } const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailPattern.test(emailInput.value.trim())) { emailInput.setCustomValidity('Veuillez saisir une adresse email valide.'); } if (phoneInput && phoneInput.value.trim() !== '') { const phonePattern = /^\d{10,15}$/; if (!phonePattern.test(phoneInput.value.trim())) { phoneInput.setCustomValidity('Veuillez saisir un numéro valide (10 à 15 chiffres).'); } } if (subjectInput.value.trim().length < 3) { subjectInput.setCustomValidity('Veuillez saisir un sujet (3 caractères minimum).'); } if (messageInput.value.trim().length < 10) { messageInput.setCustomValidity('Veuillez saisir un message (10 caractères minimum).'); } form.classList.add('was-validated'); return form.checkValidity(); } // --- Handler de soumission --- form.addEventListener('submit', async function (event) { event.preventDefault(); event.stopPropagation(); if (!validateForm()) return; // Honeypot : si rempli, simuler un succès sans rien envoyer if (honeypotInput && honeypotInput.value.trim() !== '') { successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); return; } // UI : état d'envoi submitButton.disabled = true; submitButton.innerHTML = ` <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> Envoi en cours... `; successMessage.style.display = 'none'; errorMessage.style.display = 'none'; try { const fb = await waitForFirebase(); const messagesCollection = fb.collection(fb.db, 'contact_messages'); await fb.addDoc(messagesCollection, { name: nameInput.value.trim(), email: emailInput.value.trim(), phone: phoneInput ? phoneInput.value.trim() : '', subject: subjectInput.value.trim(), message: messageInput.value.trim(), created_at: fb.serverTimestamp(), user_agent: navigator.userAgent.substring(0, 500) }); successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); } catch (error) { console.error('Erreur Firestore:', error); errorMessage.style.display = 'block'; } finally { submitButton.disabled = false; submitButton.innerHTML = ` <i class="bi bi-send me-2"></i> Envoyer le Message `; } }, false); });</code></pre> </div> </div> <div class="paragraph"> <p>Los cambios respecto al mock :</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code>— polling con timeout, robusto aunque el CDN esté lento</p> </li> <li> <p><code>honeypot</code>— si el campo oculto`hp_name`está lleno, simular un éxito sin apelación Firestore. El bot cree haber tenido éxito pero nada está almacenado</p> </li> <li> <p><code>addDoc(collection, {…​})</code>— verdadero llamada Firestore con`serverTimestamp()` et <code>user_agent</code></p> </li> <li> <p>Gestión de errores con`try/catch`asíncrono</p> </li> <li> <p>Limpieza del`finally`(restauración del botón)</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>¿Por qué?<code>user_agent</code>? Es opcional, pero útil para el diagnóstico. Si llega un mensaje extraño, saber si proviene de un navegador de escritorio, móvil, o de un script curl ayuda al triaje.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_limpiar_el_código_muerto_supabase">Fase 3: Limpiar el código muerto Supabase</h2> <div class="sectionbody"> <div class="paragraph"> <p>`script.js`contiene 250 líneas de código muerto :</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code>(líneas 417-481) — 65 líneas</p> </li> <li> <p><code>ContactFormHandler</code>(líneas 490-551) — 62 líneas</p> </li> <li> <p>Bloque de inicialización (líneas 645-654) — 10 líneas</p> </li> </ul> </div> <div class="paragraph"> <p>Total : ~140 líneas a eliminar.</p> </div> <div class="paragraph"> <p>El bloque`DOMContentLoaded`crea un`SupabaseManager`luego un`ContactFormHandler`adjunto al formulario. Como se explicó anteriormente, este código nunca se ejecuta (bloqueado`contact.js`), y incluso si se ejecutara, fallaría (no se ha cargado el SDK de Supabase).</p> </div> <div class="paragraph"> <p>Elimino:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>La clase`SupabaseManager`</p> </li> <li> <p>La clase`ContactFormHandler`</p> </li> <li> <p>El bloque de inicialización en`DOMContentLoaded`(líneas 645-654)</p> </li> </ol> </div> <div class="paragraph"> <p>Le reste de <code>script.js`está intacto :`ThemeManager</code>, <code>ScrollToTopButton</code>, <code>MobileMenuManager</code>, <code>SmoothScrollWithOffset</code>, <code>NavbarHeightUpdater</code>, <code>DynamicNavbarBreakpoint</code>, <code>CodeBlockManager</code>, <code>TooltipManager</code>, <code>PhoneInputManager</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_4_configurar_el_pie_de_página">Fase 4 : Configurar el pie de página</h2> <div class="sectionbody"> <div class="paragraph"> <p>`footer.thyme`ya tiene el boilerplate Firebase pero con valores placeholder. Estoy reemplazando:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseConfig = { apiKey: "REMPLACER_PAR_VOTRE_API_KEY", authDomain: "REMPLACER_PAR_VOTRE_AUTH_DOMAIN", projectId: "REMPLACER_PAR_VOTRE_PROJECT_ID", storageBucket: "REMPLACER_PAR_VOTRE_STORAGE_BUCKET", messagingSenderId: "REMPLACER_PAR_VOTRE_SENDER_ID", appId: "REMPLACER_PAR_VOTRE_APP_ID" };</code></pre> </div> </div> <div class="paragraph"> <p>Por los valores reales recuperados desde<strong>Configuración del proyecto > General > Tus aplicaciones > Aplicación web</strong>en la consola de Firebase.</p> </div> <div class="paragraph"> <p>Los valores son sensibles`apiKey`es pública por diseño en Firebase, pero prefiero no hacerles commit en claro). Las almaceno en`site.yml`(ya en`.gitignore`) y el plugin`bakery`Los inyecta en el template por medio de una lógica que se debe agregar en el lado del build.</p> </div> <div class="paragraph"> <p>Por ahora, los pongo directamente en`footer.thyme`— el build`./gradlew serve`les cargará localmente. Durante el despliegue, migraré la inyección hacia`site.yml`o a una variable Gradle.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>L'`apiKey`Firebase no es<strong>no</strong>un secreto. Es pública por diseño. Lo que protege sus datos, son los<strong>reglas de seguridad de Firestore</strong>, no la clave API. No la pongan en uno`.env`cargado del lado del servidor — está destinado a ser expuesto al navegador.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_fase_5_arquitectura_final">Fase 5 : Arquitectura final</h2> <div class="sectionbody"> <div id="diag-after" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE title Arquitectura Final — Formulario de Contacto Firebase actor Utilisateur as USER package "Navegador" #E8F5E9 { rectangle "contact.thyme\n(HTML, trampa)" as FORM rectangle "contact.js ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE title Arquitectura Final — Formulario de Contacto Firebase actor Utilisateur as USER package "Navegador" #E8F5E9 { rectangle "contact.thyme\n(HTML, trampa)" as FORM rectangle "contact.js (validación + Firestore)" as CONT rectangle "footer.thyme\n(Firebase SDK init)" as FOOT } cloud "Firebase" #BBDEFB { rectangle "Firestore (contact_messages)" as FS } FORM --> CONT : submit event CONT --> FOOT : window.__FIREBASE__.addDoc() FOOT --> FS : Insert document\n(règles de sécurité validées) note right of FS Firestore Rules : - create: public, validé - read: auth uniquement end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_esta_migración_dice_sobre_el_dogfooding">Lo que esta migración dice sobre el dogfooding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este sitio es generado por mi propio plugin Gradle`bakery`. El formulario de contacto está dentro del sitio. La migración Supabase → Firebase está documentada en`AGENT.adoc`, se discute en el backlog, se prueba mediante`./gradlew serve`, y genera un artículo de blog (el que está leyendo).</p> </div> <div class="paragraph"> <p>Es puro dogfooding. El sitio es el producto del plugin, el plugin es el producto del desarrollador, el desarrollador documenta el proceso en el sitio mismo.</p> </div> <div class="paragraph"> <p>El bucle está cerrado.</p> </div> <div class="paragraph"> <p>El hecho de haber arrastrado un mock durante meses (sesiones completas donde el formulario mentía silenciosamente) me hizo darme cuenta de algo: el backlog de un sitio estático personal nunca está « terminado ». Siempre hay una US prioritaria, siempre un artículo en borrador, siempre una sección comentada en una plantilla. La disciplina no consiste en terminar todo — consiste en terminar lo que es visible para el usuario.</p> </div> <div class="paragraph"> <p>Un formulario de contacto roto, es peor que no tener ningún formulario. Es una promesa no cumplida.</p> </div> <div class="sect2"> <h3 id="_resumen_de_los_cambios">Resumen de los cambios</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modificación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">impacto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>blog/2026/0113_*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Creación del artículo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/contact.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reescritura (mock → Firestore real)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Funcional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/script.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Supresión SupabaseManager + ContactFormHandler + bloque de inicialización</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Limpieza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>templates/footer.thyme</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sustitución de marcador de posición config → valores reales</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configuración</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_próximos_pasos_backlog">Próximos pasos (backlog)</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Correo de notificación</strong>: Una Cloud Function`onCreate`sobre`contact_messages`que envía un correo electrónico vía SendGrid. El formulario almacena, pero no recibo notificación. Prioridad media — los mensajes son visibles en la consola de Firebase.</p> </li> <li> <p><strong>Limitación de velocidad del lado del cliente</strong>: Añadir un timestamp de localStorage para evitar los envíos múltiples en ráfaga. El honeypot bloquea a los bots ingenuos, un rate limiter bloquearía a los bots un poco más astutos.</p> </li> <li> <p><strong>Pruebas</strong>: Una prueba de Playwright que envía el formulario y verifica que el documento aparezca en Firestore. Por ahora, lo estoy probando manualmente vía`./gradlew serve`.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://firebase.google.com/docs/firestore/security/get-started">Documentación de las reglas de seguridad de Firestore</a></p> </li> <li> <p><a href="https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document">Documentación Firestore addDoc — Web v9 modular</a></p> </li> <li> <p><a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Serie agente de gobierno — Parte 1 : Eager/Lazy</a></p> </li> <li> <p><a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Serie de gobernanza del agente — Parte 2 : Hot/Warm/Cold</a></p> </li> <li> <p><a href="/blog/2026/0111_audit_contexte_agent_post.html">Serie de gobernanza de agente — Parte 3: Auditoría</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html Tue, 28 Apr 2026 00:00:00 +0000 blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contexto_no_es_un_banco_de_pruebas_es_una_obra">Contexto: no es un banco de pruebas, es una obra</a></li> <li><a href="#_mi_entorno_de_prueba">Mi entorno de prueba</a></li> <li><a href="#_la_rúbrica_de_evaluación">La rúbrica de evaluación</a></li> <li><a href="#_round_1_kimi_k2_6_la_falsa_salida">Round 1 : Kimi K2.6 — La Falsa Salida</a> <ul class="sectlevel2"> <li><a href="#_session_9_la_mejora">Session 9 : la mejora</a></li> <li><a href="#_sesión_10_el_naufragio_silencioso">Sesión 10: el naufragio silencioso</a></li> </ul> </li> <li><a href="#_ronda_2_glm_5_1_el_combatiente_honorable">Ronda 2 : GLM-5.1 — El Combatiente Honorable</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_el_dsa_contra_el_mla_puro">Arquitectura: el DSA contra el MLA puro</a></li> <li><a href="#_sesiones_11_13_sólido_pero_frustrante">Sesiones 11-13 : sólido pero frustrante</a></li> </ul> </li> <li><a href="#_ronda_3_deepseek_v4_pro_la_máquina_de_guerra">Ronda 3 : DeepSeek-V4-Pro — La Máquina de Guerra</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_csa_hca_el_listel_doble">Arquitectura : CSA + HCA, el listel doble</a></li> <li><a href="#_sesiones_1_8_el_alivio">Sesiones 1-8: el alivio</a></li> <li><a href="#_la_prueba_decisiva_refactoring_a_100k_tokens">La prueba decisiva: refactoring a 100K tokens</a></li> </ul> </li> <li><a href="#_el_cara_a_cara_métricas_comparativas">El cara a cara : métricas comparativas</a></li> <li><a href="#_por_qué_deepseek_v4_pro_gana_en_desarrollo_de_software">¿Por qué DeepSeek-V4-Pro gana en desarrollo de software?</a> <ul class="sectlevel2"> <li><a href="#_la_arquitectura_csahca_está_diseñada_para_el_código">La arquitectura CSA+HCA está diseñada para el código</a></li> <li><a href="#_2_el_contexto_eager_es_su_zona_de_confort">2. El contexto EAGER es su zona de confort</a></li> <li><a href="#_3_la_relación_calidadlatencia_es_óptima_para_el_flujo">3. La relación calidad/latencia es óptima para el flujo</a></li> </ul> </li> <li><a href="#_lecciones_aprendidas_cómo_elegir_su_llm_para_el_vibe_coding">Lecciones Aprendidas: Cómo Elegir su LLM para el Vibe Coding</a></li> <li><a href="#_y_la_gouvernance_agent_en_todo_eso">¿Y la Gouvernance Agent en todo eso?</a></li> <li><a href="#_fuentes_técnicas">Fuentes técnicas</a></li> <li><a href="#_conclusión_la_elección_del_artesano">Conclusión : La Elección del Artesano</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 18 minutes</div> <p>La guerra de los LLMs también se libra en el terminal de un desarrollador. No en los benchmarks académicos estériles. En la vida real: un prompt de 30 000 tokens, una gobernanza de agente en AsciiDoc, plugins de Gradle Kotlin DSL por depurar y sesiones que se encadenan durante tres semanas. He probado para ti DeepSeek‑V4‑Pro, Kimi K2.6 y GLM‑5.1. Aquí tienes el veredicto, con pruebas técnicas a su disposición.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_contexto_no_es_un_banco_de_pruebas_es_una_obra">Contexto: no es un banco de pruebas, es una obra</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hace tres semanas, estaba trabajando en`codebase-gradle`, mi sistema meta-build que centraliza la configuración YAML de cuatro proyectos: un generador de README PlantUML, un constructor de diapositivas AsciiDoc, un sitio estático JBake y un chatbot LLM. El agente Opencode, gobernado por mi metodología de archivos de agentes en AsciiDoc, cargaba ~30K tokens de contexto EAGER al inicio de cada sesión — reglas absolutas, backlog, historial de las 10 sesiones anteriores.</p> </div> <div class="paragraph"> <p>Es en este terreno donde me enfrenté a tres modelos :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong>(Moonshot AI, 1T params / 32B activados, 256K contexto máximo, MLA) - <strong>GLM-5.1</strong>(Zhipu AI/Tsinghua, 744B parámetros / DSA, 200K contexto máximo) - <strong>DeepSeek-V4-Pro</strong>(DeepSeek, 1.6T params / 49B activados, 1M contexto máximo, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>Todos servidos vía Ollama en servidor en la nube, todos en modo thinking (fase de reflexión activada). El reto: producir código correcto, mantener la coherencia en sesiones largas y no alucinar cuando el contexto supera los 80K tokens.</p> </div> </div> </div> <div class="sect1"> <h2 id="_mi_entorno_de_prueba">Mi entorno de prueba</h2> <div class="sectionbody"> <div id="diag-dev-env" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 12) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Entorno de Prueba — Sesiones Opencode × 3 LLMs left to right direction package "🖥️ Terminal de Desarrollador" #E8F5E9 { rectangle "AGENT.adoc\n(reglas, backlog)" as AG rectangle "PROMPT_REPRISE\n(misión)" as PR rectangle "INDEX.adoc ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Entorno de Prueba — Sesiones Opencode × 3 LLMs left to right direction package "🖥️ Terminal de Desarrollador" #E8F5E9 { rectangle "AGENT.adoc\n(reglas, backlog)" as AG rectangle "PROMPT_REPRISE\n(misión)" as PR rectangle "INDEX.adoc (hoja de ruta)" as IDX } package "☁️ Ollama Cloud" #BBDEFB { rectangle "DeepSeek-V4-Pro 1.6T / CSA+HCA" as DV4 rectangle "Kimi K2.6 1T / MLA" as KIMI rectangle "GLM-5.1\n744B / MLA+DSA" as GLMG } package "⚙️ Codebase Gradle" #FFF9C4 { folder "buildSrc/" { file "codebase.kt" file "readme.kt" file "site.kt" file "slider.kt" file "snapshot.kt" } file "build.gradle.kts (947 líneas)" file "embeds.yml" } AG --> DV4 : Sessions 1-8 ✅ AG --> KIMI : Sessions 9-10 ⚠️ AG --> GLMG : Sessions 11-13 ⚠️ DV4 --> "Base de código" : "TDD, refactorización,\nsnapshot" KIMI --> "Base de código" : "Degradación\n desde 60K tokens" note bottom of GLMG Meilleur que Kimi mais latence + DSA moins robuste que CSA+HCA end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Cada sesión comenzaba con aproximadamente 30K tokens de contexto EAGER :`AGENT.adoc`(287 líneas)<code>PROMPT_REPRISE.adoc</code>(51 líneas),<code>.agents/INDEX.adoc</code>(218 líneas),<code>LAZY_EAGER_ESSENTIALS.adoc</code>(50 líneas). El contexto crecía rápidamente con los intercambios — una sesión típica de 10 mensajes añadía 15-20K tokens al prompt acumulado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_rúbrica_de_evaluación">La rúbrica de evaluación</h2> <div class="sectionbody"> <div class="paragraph"> <p>He evaluado cada modelo en cuatro ejes críticos para el desarrollo de software asistido :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">eje</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Criterio concreto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coherencia de contexto largo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">¿Recuerda el agente los acuerdos decididos hace 40 mensajes?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Calidad del código producido</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">¿El código compila a la primera? ¿Respeta los patrones existentes?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Razonamiento arquitectónico</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">¿Entiende el agente las relaciones entre los módulos sin que yo se los vuelva a explicar?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Resistencia a las alucinaciones</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">¿A partir de cuántos tokens el agente comienza a inventar APIs o clases inexistentes?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Y una métrica sintética casera : el<strong>coeficiente de recuperación</strong>(cuánto tiempo paso corrigiendo al agente en lugar de programar con él)</p> </div> </div> </div> <div class="sect1"> <h2 id="_round_1_kimi_k2_6_la_falsa_salida">Round 1 : Kimi K2.6 — La Falsa Salida</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6 ha sido mi primera elección. Sus benchmarks en SWE-Bench Verified (80.2) y Terminal-Bench 2.0 (66.7) son excelentes. Su arquitectura MLA promete una buena eficiencia en secuencias largas.</p> </div> <div class="sect2"> <h3 id="_session_9_la_mejora">Session 9 : la mejora</h3> <div class="paragraph"> <p>Primera sesión con Kimi. Tarea: implementar el método`resolveActiveKey()<code>dentro`codebase.kt</code>— una función de resolución de clave API con fallback CLI. El contexto es de 30K tokens, Kimi razona rápido, produce un código limpio con gestión de expiración de claves.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveActiveKey( cfg: CodebaseConfiguration, logger: Logger, cliProvider: String? = null, cliAccount: String? = null, cliKey: String? = null ): NamedApiKey? { // Résolution provider → compte → clé avec CLI override // Kimi a parfaitement compris la chaîne de priorité }</code></pre> </div> </div> <div class="paragraph"> <p>El código compila. Los 7 casos de prueba pasan. Soy optimista.</p> </div> </div> <div class="sect2"> <h3 id="_sesión_10_el_naufragio_silencioso">Sesión 10: el naufragio silencioso</h3> <div class="paragraph"> <p>Segunda sesión. El contexto se incrementa a ~90K tokens con los intercambios. Pido a Kimi que agregue un mecanismo de captura instantánea AsciiDoc que anonimice los secretos antes de la escritura.</p> </div> <div class="paragraph"> <p>Es aquí donde se desvía. Kimi empieza a inventar clases que no existen. Me propone`AnonymizedObjectMapper`— una clase ficticia. Él confunde`ReadmeYmlAnonymizer` et <code>CodebaseYmlAnonymizer</code>. Él me sugiere importar`com.fasterxml.jackson.anonymize.*`— un paquete que nunca ha existido</p> </div> <div class="paragraph"> <p>Peor: en su fase de reflexión, veo que construye razonamientos basados en premisas falsas. Él "se recuerda" que`GitConfig`a un campo`anonymizedToken`— no, es`resolvedToken()<code>. Él atribuye a`SiteYmlAnonymizer`un método`maskSupabaseCredentials()</code>— que no existe.</p> </div> <div class="paragraph"> <p><em><em>_ No era un error. Era una disolución progresiva de la coherencia. Como si cada token añadido al contexto diluyera un poco más la memoria de los primeros 30 000. </em>_</em></p> </div> <div class="paragraph"> <p>Detengo a Kimi después de dos sesiones. El diagnóstico es claro: el MLA comprime bien el caché KV, pero sin un mecanismo de selección sparsa de grano fino, la atención se diluye mecánicamente más allá de 60K tokens. Cada token 've' cada vez peor el contexto distante — y comienza a rellenar los huecos con ruido.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ronda_2_glm_5_1_el_combatiente_honorable">Ronda 2 : GLM-5.1 — El Combatiente Honorable</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1 llega con una arquitectura diferente: MLA para el modelo base, luego un <strong>continued pre-training</strong> con DSA (DeepSeek Sparse Attention) — un indexador ligero que selecciona dinámicamente los top-2048 tokens relevantes de todo el historial.</p> </div> <div class="sect2"> <h3 id="_arquitectura_el_dsa_contra_el_mla_puro">Arquitectura: el DSA contra el MLA puro</h3> <div class="paragraph"> <p>La diferencia es fundamental. Donde Kimi comprime el historial en un único espacio latente (y pierde gradualmente la capacidad de discriminar la información pertinente), GLM añade un indexador post-entrenamiento que realiza una selección esparsa explícita.</p> </div> <div id="diag-mla-vs-dsa" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Arquitecturas de Atención — MLA vs MLA+DSA left to right direction rectangle "Kimi K2.6 — MLA puro" as MLA #FFCDD2 { rectangle "KV Cache ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Arquitecturas de Atención — MLA vs MLA+DSA left to right direction rectangle "Kimi K2.6 — MLA puro" as MLA #FFCDD2 { rectangle "KV Cache completo" as KV1 rectangle "Compresión\nlatente" as CL1 rectangle "Decodificación en el espacio latente" as DL1 KV1 --> CL1 CL1 --> DL1 note bottom of DL1 ⚠️ Au-delà de 60K tokens : perte de discrimination end note } rectangle "GLM-5.1 — MLA + DSA" as DSA #C8E6C9 { rectangle "KV Cache completo" as KV2 rectangle "Compresión latente (MLA)" as CL2 rectangle "Indexador ligero (DSA, top-k=2048)" as IL rectangle "Decodificación\nsobre tokens seleccionados" as DL2 KV2 --> CL2 CL2 --> IL IL --> DL2 note bottom of DL2 ✅ "Sin pérdida por construcción" Sélection explicite des tokens pertinents end note } MLA --> DSA : "Ganancia: selección escasa\nque evita la dilución" @enduml</pre> </div> </div> <div class="paragraph"> <p>El informe técnico lo dice explícitamente: DSA es <em>"lossless by construction"</em> — a diferencia de alternativas como SWA (búsqueda de patrones), Gated DeltaNet o SimpleGDN que pierden hasta 5.69 puntos en RULER@128K.</p> </div> </div> <div class="sect2"> <h3 id="_sesiones_11_13_sólido_pero_frustrante">Sesiones 11-13 : sólido pero frustrante</h3> <div class="paragraph"> <p>GLM-5.1 mantiene mejor la distancia. En la sesión 11 (~60K tokens), sigue siendo coherente. Produce un`SnapshotManager`funcional con gestión correcta de los cuatro anonimizadores.</p> </div> <div class="paragraph"> <p>Pero la latencia es un problema. Las fases de reflexión DSA son más pesadas que el MLA puro — el indexador debe volver a escanear el historial en cada paso. Una respuesta que tardaba 8 segundos con Kimi ahora tarda 15 con GLM. En una sesión de 30 mensajes, se hace sentir.</p> </div> <div class="paragraph"> <p>Y luego están los errores sutiles. GLM no delira como Kimi — pero comete errores de <strong>nommage</strong>. Él llama`toAnonymizedYaml()<code>el método que debería llamarse`anonymize()</code>. Él invierte`loadReadmeConfiguration()` et <code>loadCodebaseConfiguration()`en el`renderFileSection()</code>. No son alucinaciones, son confusiones superficiales — pero en producción, una confusión superficial puede romper un build.</p> </div> <div class="paragraph"> <p>He tenido tres sesiones con GLM. Es mejor que Kimi, sin duda. Pero tres sesiones de corrección manual sobre detalles de nomenclatura, resulta agotador.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ronda_3_deepseek_v4_pro_la_máquina_de_guerra">Ronda 3 : DeepSeek-V4-Pro — La Máquina de Guerra</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro llega con la arquitectura más ambiciosa de las tres: un sistema híbrido que combina dos mecanismos de atención complementarios.</p> </div> <div class="sect2"> <h3 id="_arquitectura_csa_hca_el_listel_doble">Arquitectura : CSA + HCA, el listel doble</h3> <div id="diag-csa-hca" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — Arquitectura híbrida CSA + HCA left to right direction rectangle "Caché KV ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — Arquitectura híbrida CSA + HCA left to right direction rectangle "Caché KV 1M tokens" as KV #E3F2FD rectangle "CSA Atención Dispersa Comprimida" as CSA #C8E6C9 { rectangle "Compresión m tokens → 1" as CC rectangle "Atención dispersa\n(DSA, top-k)" as SA CC --> SA note bottom of SA Attention locale fine + sélection sparse end note } rectangle "HCA\nAtención altamente comprimida" as HCA #BBDEFB { rectangle "Compresión extrema m' >> m → 1" as ECC rectangle "Atención densa residual" as EDA ECC --> EDA note bottom of EDA Contexte global + connexions longue distance end note } rectangle "Fusión híbrido" as FUSION #FFF9C4 rectangle "Decodificación\ncoherente" as DEC #FFE0B2 KV --> CSA : Précision locale KV --> HCA : Vision globale CSA --> FUSION HCA --> FUSION FUSION --> DEC @enduml</pre> </div> </div> <div class="paragraph"> <p>Dos niveles de compresión, dos granularidades de atención:</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong>: comprime el caché KV todos los`m`tokens, luego aplica una atención escasa (DeepSeek Sparse Attention) — solo se consulta el top-k de las entradas comprimidas. Preciso, local, eficiente. - <strong>HCA</strong>: compresión extrema (factor`m'`mucho más grande que`m`), pero atención densa sobre el residuo comprimido — mantenga las conexiones globales sin explosión cuadrática.</p> </li> </ul> </div> <div class="paragraph"> <p>Resultado: a 1M de tokens, DeepSeek-V4-Pro solo consume<strong>27% de los FLOPs de inferencia</strong> et <strong>10% del tamaño del caché KV</strong>en comparación con DeepSeek-V3.2. El modelo anterior.</p> </div> <div class="paragraph"> <p>Y sobre todo, el informe técnico (Figura 9) anuncia: <em>"Retrieval performance remains highly stable within a 128K context window."</em></p> </div> </div> <div class="sect2"> <h3 id="_sesiones_1_8_el_alivio">Sesiones 1-8: el alivio</h3> <div class="paragraph"> <p>Sesiones 1-8: el alivio</p> </div> <div class="paragraph"> <p>He pasado ocho sesiones con DeepSeek-V4-Pro en`codebase-gradle`. Ocho sesiones sin una sola alucinación, sin una sola clase inventada, sin una sola confusión de nomenclatura.</p> </div> <div class="paragraph"> <p>Sesión 1 : implementación de`CodebaseYmlConfig` et <code>CodebaseYmlAnonymizer</code>. 350 líneas de Kotlin, pruebas en línea, todo compila. Sesión 4 : adición del`SnapshotManager`con vista de árbol, recolección de archivos, renderizado AsciiDoc por archivo. 279 líneas, cero error. Sesión 7 : depuración de`renderFileSection()`que tenía que gestionar cuatro tipos de anonimizadores diferentes sin ambigüedad de resolución. Resuelto en tres mensajes.</p> </div> <div class="paragraph"> <p>La latencia es más alta que Kimi — aproximadamente 10-12 segundos por respuesta en modo thinking. Pero la tasa de corrección es prácticamente nula. No paso mi tiempo reparando los errores del agente. Codifico <strong>con</strong> él.</p> </div> </div> <div class="sect2"> <h3 id="_la_prueba_decisiva_refactoring_a_100k_tokens">La prueba decisiva: refactoring a 100K tokens</h3> <div class="paragraph"> <p>En la sesión 8, el contexto acumulado supera los 100K tokens. Solicito un refactor intensivo: extraer las cuatro tareas de verificación en línea del`build.gradle.kts`a los archivos de prueba de JUnit5 en`buildSrc/src/test/`.</p> </div> <div class="paragraph"> <p>El agente propone un plan en tres fases :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Crear las clases de prueba con migración de los casos existentes</p> </li> <li> <p>Agregar las dependencias de JUnit5 y Kotest en`buildSrc/build.gradle.kts`</p> </li> <li> <p>Eliminar el código en línea de`build.gradle.kts`</p> </li> </ol> </div> <div class="paragraph"> <p>El plan es correcto. La ejecución es limpia. Incluso identifica un caso límite que yo había pasado por alto: las dependencias Jackson duplicadas entre`buildscript {}` et `buildSrc/build.gradle.kts`que deben ser unificadas durante la migración.</p> </div> <div class="paragraph"> <p>100K tokens de contexto, y el agente recuerda que`CodebaseYmlAnonymizer.TOKEN_MASK`es`"<strong>*</strong>"`, que`GitConfig.resolvedToken()<code>es una función de extensión definida en`readme.kt</code>, y que`SnapshotManager.PRUNED_DIRS`excluye`build`, <code>.gradle</code> et <code>.git</code>.</p> </div> <div class="paragraph"> <p>Así es, la diferencia.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_cara_a_cara_métricas_comparativas">El cara a cara : métricas comparativas</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">criterio</th> <th class="tableblock halign-left valign-top">Kimi K2.6</th> <th class="tableblock halign-left valign-top">GLM-5.1</th> <th class="tableblock halign-left valign-top">DeepSeek-V4-Pro</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexto máximo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">256K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">200K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1M</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Mecanismo atención</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA puro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA + DSA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSA + HCA híbrido</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Parámetros totales</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1T</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">744B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1.6t</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Parámetros activados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">32B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">no publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49B</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Umbral de degradación observado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~60K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~120K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"></think></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Comportamiento más allá</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alucinaciones masivas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusiones de superficie</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">degradación progresiva lenta</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Estabilidad NIAH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">no publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% @128K (DSA)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">estable hasta 128K (Figura 9)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">MRCR @128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">no publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">no publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">superior a Gemini 3.1 Pro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sesiones celebradas antes del abandono</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 (y continúa)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tiempo de corrección / tiempo de código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">60%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><5%</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Latencia media (modo think)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11 s</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coeficiente de confianza*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">6/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9/10</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Coeficiente de confianza = medida subjetiva de mi capacidad para tomar el código del agente y el commit sin revisión línea por línea.</em></p> </div> <div id="diag-radar" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 17) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Radar Comparativo — 3 LLMs en Desarrollo Asistido por Software legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coherencia\n80K+ tokens" as coh #F5F5F5 rectangle "Calidad código" as qual #F5F5F5 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Radar Comparativo — 3 LLMs en Desarrollo Asistido por Software legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coherencia\n80K+ tokens" as coh #F5F5F5 rectangle "Calidad código" as qual #F5F5F5 rectangle "Razonamiento arquitectónico" as arch #F5F5F5 rectangle "Resistencia hallucinations" as hall #F5F5F5 rectangle "Velocidad\n(experiencia dev)" as speed #F5F5F5 rectangle "Conocimiento Gradle/Kotlin" as kg #F5F5F5 rectangle "Tasa de corrección" as corr #F5F5F5 coh --> qual qual --> arch arch --> hall hall --> speed speed --> kg kg --> corr note top of coh Kimi ████░░░░░░ 4/10 GLM ██████░░░░ 6/10 DeepSeek █████████░ 9/10 end note note top of qual Kimi ███████░░░ 7/10 (sous 60K) GLM ████████░░ 8/10 DeepSeek █████████░ 9/10 end note note top of arch Kimi █████░░░░░ 5/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of hall Kimi ██████░░░░ 6/10 → ██░░░░░░░░ 2/10 (> 60K) GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of speed Kimi █████████░ 9/10 GLM ██████░░░░ 6/10 DeepSeek █████░░░░░ 5/10 end note note top of kg Kimi ███████░░░ 7/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of corr Kimi ██░░░░░░░░ 2/10 (beaucoup de corrections) GLM █████░░░░░ 5/10 DeepSeek ██████████ 10/10 (presque rien à corriger) end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_deepseek_v4_pro_gana_en_desarrollo_de_software">¿Por qué DeepSeek-V4-Pro gana en desarrollo de software?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La superioridad de DeepSeek-V4-Pro no se debe a un solo factor — es una convergencia:</p> </div> <div class="sect2"> <h3 id="_la_arquitectura_csahca_está_diseñada_para_el_código">La arquitectura CSA+HCA está diseñada para el código</h3> <div class="paragraph"> <p>El desarrollo de software asistido es un caso de uso <strong>extremo</strong> para la atención de largo contexto. Necesitas: - Precisión local (¿De qué hereda esta clase? ¿Dónde está definido este método?) →<strong>CSA</strong> - Visión global (¿por qué existe este módulo? ¿cómo interactúan los cuatro anonimizadores?) →<strong>HCA</strong></p> </div> <div class="paragraph"> <p>Kimi con MLA solo gestiona la precisión local pero pierde la visión global más allá de 60K. GLM con DSA mejora la visión global pero sigue siendo mono-nivel. DeepSeek combina ambos explícitamente.</p> </div> </div> <div class="sect2"> <h3 id="_2_el_contexto_eager_es_su_zona_de_confort">2. El contexto EAGER es su zona de confort</h3> <div class="paragraph"> <p>Mi sistema de gobernanza carga ~30K tokens de reglas y de backlog al iniciar. Con una ventana estable de hasta 128K, DeepSeek tiene ~100K tokens de margen para los intercambios de la sesión. Es de 3 a 4 veces más de lo que Kimi puede manejar sin degradación.</p> </div> <div class="paragraph"> <p></think> La ventana de 128K de estabilidad perfecta corresponde exactamente a mis necesidades: 30K de EAGER + 70K de intercambios = una sesión productiva de 20-30 mensajes sin nunca salir de la zona verde. <em>__</em></p> </div> </div> <div class="sect2"> <h3 id="_3_la_relación_calidadlatencia_es_óptima_para_el_flujo">3. La relación calidad/latencia es óptima para el flujo</h3> <div class="paragraph"> <p>Sí, DeepSeek-V4-Pro es más lento que Kimi (11s vs 8s). Pero el tiempo <strong>total</strong> de una tarea es mucho menor porque no paso 20 minutos corrigiendo las alucinaciones del agente.</p> </div> <div class="paragraph"> <p>El desarrollador no mide la latencia de una respuesta. Mide el tiempo entre « me hago la pregunta » y « el código está en mi repositorio y funciona ». Con esta métrica, DeepSeek-V4-Pro es el más rápido de los tres.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas_cómo_elegir_su_llm_para_el_vibe_coding">Lecciones Aprendidas: Cómo Elegir su LLM para el Vibe Coding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Más allá de la clasificación puntual, esta experiencia me ha enseñado a evaluar un LLM para el desarrollo de software asistido según criterios que no aparecen en ningún benchmark:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Mira la arquitectura, no el tamaño del contexto anunciado</strong>— Un modelo que anuncia 256K de contexto pero solo tiene un MLA terminará como Kimi: teóricamente capaz, prácticamente inutilizable más allá de 60K.</p> </li> <li> <p><strong>Prueba en TU contexto, no en un benchmark genérico</strong>Mi prompt inicial de 30K tokens AsciiDoc con reglas absolutas y backlog no tiene nada que ver con las preguntas de HLE o AIME.</p> </li> <li> <p><strong>La latencia no es la enemiga si la calidad sigue</strong>— Un modelo lento que produce código correcto es más rápido que un modelo rápido que produce código incorrecto.</p> </li> <li> <p><strong>Desconfía de los modelos sin un informe técnico público</strong>— Si el equipo no documenta su arquitectura de atención, es porque no tiene confianza en su desempeño en contextos largos.</p> </li> </ol> </div> <div id="diag-decision-tree" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b3c52c491aa4f05a7a381385c54cfbfb.svg" alt="Arbre de décision pour choisir un LLM pour le développement logiciel assisté" width="827" height="461"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_y_la_gouvernance_agent_en_todo_eso">¿Y la Gouvernance Agent en todo eso?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta experiencia valida un punto que defiendo desde mi artículo sobre la gobernanza Eager/Lazy :<strong>la calidad del LLM y la calidad de la gobernanza son multiplicativas, no aditivas</strong>.</p> </div> <div class="paragraph"> <p>Con Kimi K2.6, mi gobernanza estaba impecable — pero el modelo diluía la información. Resultado: gobernanza perfecta × alucinación = cero.</p> </div> <div class="paragraph"> <p>Con DeepSeek-V4-Pro, la gobernanza EAGER (30K tokens de reglas) + LAZY (archivos de sesiones, referencias técnicas) + Hot/Warm/Cold (copia de seguridad rotativa) forma un ecosistema donde cada capa amplifica a la otra. El agente tiene las reglas a la vista (EAGER), puede consultar el historial (LAZY), y el contexto nunca se satura (rotación de copia de seguridad).</p> </div> <div class="paragraph"> <p><em>__</em> Un buen LLM sin gobernanza, es un motor de Ferrari sin volante. Una buena gobernanza sin buen LLM, es un volante sin motor. DeepSeek-V4-Pro + mi gobernanza agente = la primera vez que tengo la impresión de conducir. </think></p> </div> <div class="paragraph"> <p>El mecanismo de backup rotativo (rotación cada 10 sesiones o >500 líneas EAGER) tiene todo su sentido con un modelo que maneja 128K de contexto: la ventana deslizante de 10 sesiones activas mantiene el contexto fresco sin nunca superar la zona de degradación.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fuentes_técnicas">Fuentes técnicas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Crucé mi experiencia empírica con los informes técnicos oficiales para validar mis observaciones:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>DeepSeek-V4 Technical Report</strong> — PDF recuperado desdehttps://huggingface.co/deepseek-ai/DeepSeek-V4-Flash[HuggingFace]. Figura 9 : "El rendimiento de recuperación se mantiene altamente estable dentro de una ventana de contexto de 128K. Mientras que una degradación del rendimiento se hace visible más allá de la marca de 128K, las capacidades de recuperación del modelo con 1M de tokens siguen siendo notablemente fuertes." Arquitectura CSA+HCA documentada sección 2.3.</p> </li> <li> <p><strong>Informe técnico GLM-5</strong> —https://arxiv.org/abs/2602.15763[arXiv:2602.15763]. DSA se introduce mediante pre-entrenamiento continuado, "sin pérdida por construcción". Contexto máximo 202,752 tokens. Las tablas 3/5/6 documentan el rendimiento de largo contexto frente a alternativas (SWA, Gated DeltaNet, SimpleGDN).</p> </li> <li> <p><strong>Kimi K2.6 Model Card</strong> —https://huggingface.co/moonshotai/Kimi-K2.6[HuggingFace]. MLA, 256K contexto máximo. Estrategia de discard-all más allá del umbral en las tareas agenciales (confirmando implícitamente el límite práctico de MLA en contexto largo).</p> </li> <li> <p><strong>Informe Técnico de Kimi K2</strong>—https://arxiv.org/abs/2507.20534[arXiv:2507.20534]. Arquitectura MoE, MuonClip optimizer, rendimientos agenticos (HLE, BrowseComp, Terminal-Bench).</p> </li> </ol> </div> <div class="paragraph"> <p>El punto más revelador: en su propia evaluación, Moonshot aplica una estrategia de <strong>discard-all</strong> (eliminación del contexto antiguo) tan pronto como se supera la ventana de contexto. Esto confirma exactamente lo que he observado: el MLA solo no puede mantener la coherencia en toda la ventana de 256K. La arquitectura no sigue.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_la_elección_del_artesano">Conclusión : La Elección del Artesano</h2> <div class="sectionbody"> <div class="paragraph"> <p>Después de tres semanas y trece sesiones de desarrollo real, el veredicto es sin apelación:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3337%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Kimi K2.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GLM-5.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek-V4-Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Excelente por debajo de 60K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sólido hasta 120K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Domina en todas partes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Inutilizable más allá</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusiones de superficie</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estable hasta 128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 sesiones, abandonado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 sesiones, abandonado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 sessions, adoptado</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek-V4-Pro se ha convertido en mi LLM predeterminado para todas las sesiones de desarrollo de software asistido con Opencode. No porque sea el más reciente. No porque tenga los mejores benchmarks académicos. Pero porque en la vida real de un desarrollador que impulsa plugins Gradle Kotlin DSL con un contexto de agente de 30K tokens, es el único que no me falla cuando el contexto se extiende.</p> </div> <div class="paragraph"> <p>El CSA+HCA es un <strong>game changer</strong> arquitectónico. La compresión de doble nivel + esparsificación no es un detalle de implementación — es lo que marca la diferencia entre un asistente de código y un compañero confiable.</p> </div> <div class="paragraph"> <p></think> He elegido DeepSeek-V4-Pro porque es el único de los tres que transforma mi gobernanza de agente de una restricción defensiva ("¿cómo evitar que el agente olvide?") en una ventaja ofensiva ("¿qué podemos construir ahora que el agente recuerda todo?"). <em>__</em></p> </div> <hr> <div class="paragraph"> <p>*Este artículo es el resultado de 13 sesiones de desarrollo real en el proyecto`codebase-gradle`, documentadas en`.agents/sessions/`según mi metodología de gobernanza de agente Eager/Lazy/Hot/Warm/Cold. Las fuentes técnicas citadas son accesibles públicamente en HuggingFace y arXiv.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0111_audit_contexte_agent_post.html Mon, 27 Apr 2026 00:00:00 +0000 blog/2026/0111_audit_contexte_agent_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_sesión_051_algo_chirría">La escena: sesión 051, algo chirría</a></li> <li><a href="#_la_auditoría_desglosar_las_627_líneas">La auditoría: desglosar las 627 líneas</a></li> <li><a href="#_el_miedo_de_perder_la_ingeniería">El miedo de perder la ingeniería</a></li> <li><a href="#_la_solución_split_enciclopédico">La solución: split enciclopédico</a></li> <li><a href="#_el_contenido_del_archivo_essentials">El contenido del archivo ESSENTIALS</a></li> <li><a href="#_el_resultado_50_de_contexto_eager">El resultado : -50% de contexto EAGER</a></li> <li><a href="#_por_qué_se_llama_la_carpeta_encyclopedies">¿Por qué se llama la carpeta `encyclopedies/</a></li> <li><a href="#_la_continuación_lógica_de_la_serie">La continuación lógica de la serie</a></li> <li><a href="#_lo_que_habría_hecho_diferente">Lo que habría hecho diferente</a></li> <li><a href="#_el_guía_para_auditar_su_propio_contexto">El guía para auditar su propio contexto</a></li> <li><a href="#_una_gobernanza_viva">Una gobernanza viva</a></li> <li><a href="#_enlaces">Enlaces</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 14 minutes</div> <p>Has pasado semanas construyendo una gobernanza de agente impecable. Eager/Lazy, procedimiento de fin de sesión, copias de seguridad rotativas. El sistema funciona. Entonces un día, el agente se vuelve lento. Las respuestas están diluidas. Mides: 1414 líneas cargadas automáticamente. Y lo peor es que el culpable no es el código, ni el backlog, ni los archivos de sesiones. El culpable es el archivo que documenta tu método.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_sesión_051_algo_chirría">La escena: sesión 051, algo chirría</h2> <div class="sectionbody"> <div class="paragraph"> <p>30 de abril de 2026, 16:00. Estoy en plena sesión en`magic-stick`, mi proyecto de creación de ISO Linux live. El agente Opencode cargó automáticamente mis archivos Eager como de costumbre —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Todo está normal.</p> </div> <div class="paragraph"> <p>Excepto que las respuestas son blandas. El agente tarda dos segundos más en razonar. Se le olvida un detalle que tenía delante hace tres mensajes. No es un crash, no es un error — es una degradación lenta, del tipo que no se nota de inmediato.</p> </div> <div class="paragraph"> <p>Ya lo había experimentado en la sesión 048, cuando descubrí que los archivos de gobernanza pesaban 5200 líneas acumuladas. Entonces conceptualicé el mecanismo Hot/Warm/Cold con su ventana deslizante de 10 sesiones, sus olas frías idénticas, su sensor de dos disparadores. El problema estaba resuelto. En teoría.</p> </div> <div class="paragraph"> <p>Pero ahora estamos en la sesión 051. La rotación de respaldo ha tenido lugar correctamente — los archivos EAGER han pasado de 2087 a 500 líneas. Sin embargo, el contexto sigue siendo pesado. Algo se me escapa.</p> </div> <div class="paragraph"> <p>Abro un terminal y escribo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wc -l AGENT.adoc AGENT_MODUS_OPERANDI.adoc PROMPT_REPRISE.adoc \ .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>1414 líneas. La rotación de backup ha podado bien en INDEX, SESSIONS_HISTORY y COMPLETED_TASKS — están limpios. Pero hay un elefante en la habitación que no había visto:<strong>627 líneas</strong>en un solo archivo.<code>AGENT_MODUS_OPERANDI.adoc</code>.</p> </div> <div class="paragraph"> <p>Este archivo, es el que escribí en la sesión 1 para documentar la estrategia Eager/Lazy. Es el manual del método. Y se ha convertido, por sí solo, en el 44% del contexto EAGER.</p> </div> <div id="diag-before-audit" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER — 1414 líneas rectangle "AGENT_MODUS_OPERANDI **627 líneas (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 líneas (20%)" as AG #BBDEFB rectangle "INDEX.adoc 218 líneas (15%)" as IDX #C8E6C9 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER — 1414 líneas rectangle "AGENT_MODUS_OPERANDI **627 líneas (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 líneas (20%)" as AG #BBDEFB rectangle "INDEX.adoc 218 líneas (15%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 líneas (15%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE\n51 líneas (4%)" as PRO #E1BEE7 rectangle "SESSIONS_HISTORY 18 líneas (1%)" as HIS #FFE0B2 note bottom of MOD Le fichier qui documente la méthode est devenu le plus gros poste de dépense end note @enduml</pre> </div> </div> <div class="paragraph"> <p>La ironía es total. El archivo diseñado para <strong>ahorrar</strong> contexto se ha convertido en el principal <strong>consumidor</strong> de contexto. Es como si el manual de uso de tu coche pesara más que el motor.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_auditoría_desglosar_las_627_líneas">La auditoría: desglosar las 627 líneas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Decido hacer una auditoría sección por sección. No para eliminar — para <strong>comprender</strong> lo que merece estar en EAGER y lo que podría vivir en otro lugar sin pérdida de conocimiento.</p> </div> <div class="paragraph"> <p>Aquí está la estructura exacta de`AGENT_MODUS_OPERANDI.adoc`y lo que encuentro :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2739%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sección</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Líneas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contenido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ya presente en…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — Visión general</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">64</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema resuelto, principios fundamentales, analogía cuadro de mando vs manual</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P2 — Estructura de los archivos</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">97</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Arborescencia, política de carga, cuándo cargar qué</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P3 — Reglas absolutas</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git prohibido, comandos destructivos prohibidos, secretos prohibidos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>+<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P4 — Ciclo de vida de la sesión</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">133</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plantilla apertura, normas de trabajo, 6 pasos fin de sesión, lista de verificación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>§fin sesión +<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — Métricas y umbrales</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sesión ideal (15-30 min, 1-3 archivos), signos de alerta</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P6 — Tipos de sesiones</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">72</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabla de detección, formato de propuesta, excepciones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P7 — Mejora continua</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">39</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Métricas de seguimiento, revisión semanal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P8 — Checklist de arranque</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap nuevo proyecto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P9 — Referencias</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivos de referencia, recursos externos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>(archivos EAGER/LAZY)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Anexos A+B</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">42</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Glosario, historial versiones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El veredicto es inapelable:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Duplicados completos</strong>(167 líneas) : P3, P4, P9 — todo ya está en`AGENT.adoc` ou <code>INDEX.adoc</code>, a menudo palabra por palabra</p> </li> <li> <p><strong>Nunca consultado en la práctica</strong>(215 líneas) : P5, P6, P7, P8, Anexos — de la meta‑gobernancia que nunca se ha utilizado en ninguna sesión</p> </li> <li> <p><strong>Conocimiento único</strong>(161 líneas) : P1 y P2 — el vocabulario LAZY/EAGER, la analogía, la política de carga</p> </li> </ul> </div> <div class="paragraph"> <p>En 627 líneas,<strong>382 son ruido</strong>. Y estas 382 líneas se cargan <strong>al inicio de cada sesión</strong>, consumidas por el agente, diluyendo su atención incluso antes de que yo diga hola.</p> </div> <div id="diag-audit-result" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Auditoría de AGENT_MODUS_OPERANDI.adoc — 627 líneas left to right direction rectangle "🟡 **Duplicados**\n167 líneas (27%)" as DUP #FFF9C4 { card "P3 — Reglas absolutas ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Auditoría de AGENT_MODUS_OPERANDI.adoc — 627 líneas left to right direction rectangle "🟡 **Duplicados**\n167 líneas (27%)" as DUP #FFF9C4 { card "P3 — Reglas absolutas (34 líneas)" as D1 card "P4—Ciclo de vida\n(133 líneas)" as D2 card "P9 — Referencias\n(30 líneas)" as D3 } rectangle "�🔴 **Nunca consultado** 215 líneas (34%)" as JAM #FFCDD2 { card "P5 — Métricas (49 líneas)" as J1 card "P6 — Detección (72 líneas)" as J2 card "P7 — Mejora (39 líneas)" as J3 card "P8 — Bootstrap (13 líneas)" as J4 card "Anexos — Glosario (42 líneas)" as J5 } rectangle "�🟢 **Conocimiento único** 161 líneas (26%)" as UNI #C8E6C9 { card "P1 — Visión general\n(64 líneas)" as U1 card "P2 — Estructura archivos (97 líneas)" as U2 } note bottom of UNI C'est ÇA qu'il faut garder en EAGER. Le reste → cold storage. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Este diagrama es la clave de todo. Los duplicados (amarillo) son ruido puro — el agente los lee dos veces, en dos archivos diferentes. El nunca consultado (rojo) es documentación muerta — escrita con cuidado, nunca utilizada. Solo el verde contiene conocimiento que el agente no puede encontrar en otro lugar.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_miedo_de_perder_la_ingeniería">El miedo de perder la ingeniería</h2> <div class="sectionbody"> <div class="paragraph"> <p>En este punto, tengo la evidencia ante los ojos: debo reducir`AGENT_MODUS_OPERANDI.adoc`. Pero dudo.</p> </div> <div class="paragraph"> <p>Este archivo lo escribí a mano. Cada sección es el resultado de una lección aprendida en una sesión real. La parte P3 nació de un`rm -rf`accidental sobre`bakery-plugin`que me ha costado tokens reales de Firebase. La parte P4 es el resultado de quince sesiones en las que olvidaba archivar y perdí el hilo. El procedimiento de seis pasos no proviene de un libro—proviene del dolor.</p> </div> <div class="paragraph"> <p>Eliminar estas secciones sería tirar el historial de mi propia ingeniería. Las lecciones que las produjeron, las sesiones durante las cuales las descubrí, los errores que nunca quiero volver a cometer. No es texto — es experiencia cristalizada.</p> </div> <div class="paragraph"> <p>Es ahí donde formulo el principio que guiará la solución:</p> </div> <div class="paragraph"> <p><em><em>_ <strong>Nunca eliminar. Siempre reubicar.</strong>El conocimiento no tiene que desaparecer del proyecto. Sólo tiene que no cargarse automáticamente cuando no es necesario. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_split_enciclopédico">La solución: split enciclopédico</h2> <div class="sectionbody"> <div class="paragraph"> <p>El modelo que propongo es simple y se inspira en la forma en que Wikipedia ha crecido: cuando un artículo se vuelve demasiado largo, no lo cortamos — creamos un artículo detallado y mantenemos un resumen en el artículo principal.</p> </div> <div class="paragraph"> <p>Para`AGENT_MODUS_OPERANDI.adoc`, esto da:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Extraer</strong>los 161 líneas de conocimiento único (P1 + P2) en un nuevo archivo`LAZY_EAGER_ESSENTIALS.adoc`— compactado a ~50 líneas, estrictamente EAGER</p> </li> <li> <p><strong>Renombrar</strong> <code>AGENT_MODUS_OPERANDI.adoc</code> en <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code>— el archivo original de 627 líneas, preservado <strong>intact</strong>, en almacenamiento en frío</p> </li> <li> <p><strong>Nunca cargar</strong>el archivo enciclopedia automáticamente — está allí para el humano, para la destilación futura, para el agente que se invocará dentro de seis meses con un mejor modelo</p> </li> </ol> </div> <div id="diag-split-solution" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Split Enciclopédico — AGENT_MODUS_OPERANDI left to right direction rectangle "**AGENT_MODUS_OPERANDI.adoc** ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Split Enciclopédico — AGENT_MODUS_OPERANDI left to right direction rectangle "**AGENT_MODUS_OPERANDI.adoc** 627 líneas (antes de dividir)" as BEFORE #FFCDD2 { } rectangle " " as ARROW1 rectangle " " as ARROW2 rectangle "**LAZY_EAGER_ESSENTIALS.adoc** **~50 líneas — EAGER**" as ESS #C8E6C9 { card "P1 condensada (15 líneas)" as E1 card "P2 condensada (35 líneas)" as E2 } rectangle ".agents/enciclopedias/\n**LAZY_EAGER_ENCICLOPEDIA.adoc**\n627 líneas — FRÍO" as ENC #BBDEFB { card "P1 a Anexos\n(integral, intacto)" as C1 } BEFORE -[#4CAF50]-> ESS : "Extracción de conocimiento crítico" BEFORE -[#2196F3]-> ENC : "Preservación integral de la ingeniería" note bottom of ESS Chargé automatiquement en début de session → L'agent comprend le vocabulaire end note note bottom of ENC Jamais chargé automatiquement Consultable par l'humain Matériau brut pour distillation future end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El nombre`encyclopedies/`No es trivial. Una enciclopedia, no es un archivo — es una colección de conocimiento organizada, consultable pero no portátil. No se lee la Enciclopedia Universalis en el metro. La guardamos en la biblioteca, y vamos cuando tenemos una pregunta precisa.</p> </div> <div class="paragraph"> <p>Es exactamente el papel de esta carpeta: una biblioteca de referencia fría, estructurada, exhaustiva — que el agente no toca automáticamente.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_contenido_del_archivo_essentials">El contenido del archivo ESSENTIALS</h2> <div class="sectionbody"> <div class="paragraph"> <p>Así se ve concretamente el nuevo archivo`LAZY_EAGER_ESSENTIALS.adoc`, extraído y compactado a partir de P1 y P2 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Stratégie LAZY/EAGER — Principes Essentiels [abstract] Ce fichier définit la stratégie de gestion du contexte agent. Chargé automatiquement (EAGER) en début de session. == Principes |=== | EAGER | LAZY | Tableau de bord | Manuel du propriétaire | Chargé automatiquement | Chargé sur demande | <= 100 lignes, <= 10k tokens | Illimité, détaillé | Règles absolues, mission courante | Archives, historique, références |=== == Politique de Chargement |=== | Fichier | Type | Quand charger | PROMPT_REPRISE.adoc | EAGER | Début session (auto) | *_ESSENTIALS.adoc | EAGER | Début session si EPIC active | .agents/INDEX.adoc | EAGER | Début session (auto) | *_REFERENCE.adoc | LAZY | Sur besoin (détails architecture) | .agents/sessions/N-*.adoc | LAZY | Sur demande (détails session) | .agents/encyclopedies/*.adoc | COLD | Jamais auto (humain seulement) |=== == Comment l'Agent Sait Quoi Charger Début session → PROMPT_REPRISE + INDEX + ESSENTIALS actifs. Besoin de détails → charger les *_REFERENCE et sessions/ en LAZY. Connaissance froide → encyclopedies/, jamais automatique.</code></pre> </div> </div> <div class="paragraph"> <p>Cincuenta líneas. Eso es todo lo que el agente necesita para comprender la mecánica. Todo lo demás — el historial de las lecciones, las analogías detalladas, los procedimientos paso a paso, los anexos — vive en la enciclopedia.</p> </div> <div class="paragraph"> <p>Y lo más importante:<strong>nada ha sido eliminado</strong>. Las 627 líneas de ingeniería siguen estando allí, en`.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`. Están simplemente colocadas en la biblioteca en vez de sobre la encimera.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_resultado_50_de_contexto_eager">El resultado : -50% de contexto EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes del split :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>Después del split :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 50 LAZY_EAGER_ESSENTIALS.adoc ← remplace 627 lignes 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 837 total ← -41%</code></pre> </div> </div> <div id="diag-after-audit" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER después de la división enciclopédica — 837 líneas (-41%) rectangle "AGENT.adoc 287 líneas (34%)" as AG #BBDEFB ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER después de la división enciclopédica — 837 líneas (-41%) rectangle "AGENT.adoc 287 líneas (34%)" as AG #BBDEFB rectangle "INDEX.adoc\n218 líneas (26%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 líneas (25%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51 líneas (6%)" as PRO #E1BEE7 rectangle "ESSENTIALS 50 líneas (6%)" as ESS #A5D6A7 rectangle "SESSIONS_HISTORY\n18 líneas (2%)" as HIS #FFE0B2 note bottom of ESS De 627 → 50 lignes 577 lignes d'ingénierie préservées en cold storage Rien de perdu. Tout de relocalisé. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El mayor consumidor (AGENT_MODUS_OPERANDI, 627 líneas) fue reemplazado por un archivo de 50 líneas. La ganancia es inmediata: 577 líneas de contexto liberadas. El agente respira.</p> </div> <div class="paragraph"> <p>Y en`.agents/encyclopedies/`, el archivo original de 627 líneas espera. Intacto. Con todas sus secciones — incluyendo aquellas que son duplicados, incluyendo aquellas que nunca han sido utilizadas. Porque algún día, un mejor modelo o un data scientist humano querrá cruzar estos ángulos, estas redundancias asumidas, estas lecciones aprendidas. Y ese día, la materia prima estará allí.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_se_llama_la_carpeta_encyclopedies">¿Por qué se llama la carpeta `encyclopedies/</h2> <div class="sectionbody"> <div class="paragraph"> <p>La elección del nombre no es cosmética. Codifica la filosofía del mecanismo.</p> </div> <div class="paragraph"> <p>Un <strong>archivo</strong> (<code>archives/</code>) contiene datos históricos organizados cronológicamente — como los COMPLETED_TASKS mensuales. Un <strong>backup</strong> (<code>backup/</code>) es una captura con marca de tiempo — una copia de seguridad de un estado anterior.</p> </div> <div class="paragraph"> <p>Una <strong>enciclopedia</strong>, es otra cosa. Es una colección de conocimiento temático, estructurada por tema, exhaustiva pero no lineal. No se lee una <strong>enciclopedia</strong> del principio al final. Se sumerge para responder a una pregunta precisa.</p> </div> <div class="paragraph"> <p>Es exactamente el contrato de este expediente:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Expediente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">rol</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Acceso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">granularidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>archives/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Datos históricos (tareas completadas por mes)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY, estructurado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cronológico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>backup/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Instantáneas frías (olas de 10 sesiones)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, copia completa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cronológico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>encyclopedies/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Conocimiento temático exhaustivo (metodología, patterns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, nunca automático</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Temática</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Esta distinción evita el desorden. Cada archivo sabe dónde debe vivir según <strong>lo que contiene</strong>, no según <strong>cuando fue creado</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_continuación_lógica_de_la_serie">La continuación lógica de la serie</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si ha leído los dos primeros artículos, aquí tiene cómo encajan las tres piezas:</p> </div> <div id="diag-trilogie" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Trilogía de la Gobernanza del Agente left to right direction package "�📖 **Artículo 0108** ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Trilogía de la Gobernanza del Agente left to right direction package "�📖 **Artículo 0108** Estrategia Eager/Lazy" as A1 #E8F5E9 { card "Agente de memoria entre sesiones" as M1 card "Archivos EAGER\n(auto-cargados)" as M2 card "Archivos LAZY\n(a petición)" as M3 card "Procedimiento 6 pasos" as M4 } package "�🧊 **Article 0110**\nMecanismo Hot/Warm/Cold" as A2 #FFF9C4 { card "Envejecimiento del contexto" as V1 card "Ventana deslizante 10 sesiones" as V2 card "Ola fría idéntica" as V3 card "Sensor a dos disparadores" as V4 } package "�🔍 **Artículo 0111** Auditoría + Solución Enciclopédica" as A3 #BBDEFB { card "Auditoría de archivos EAGER" as E1 card "Identificación\ndel despilfarro" as E2 card "Split ESSENTIALS/enciclopedia" as E3 card "Preservación de la ingeniería" as E4 } A1 --> A2 : "La memoria crece → se necesita un mecanismo de envejecimiento" A2 --> A3 : "El envejecimiento no basta → es necesario auditar lo que merece estar en EAGER" note bottom of A3 ✅ Les trois couches sont en place sur 6 projets actifs end note @enduml</pre> </div> </div> <div class="ulist"> <ul> <li> <p><strong>0108</strong>responde a: « ¿Cómo darle una memoria al agente entre dos sesiones ?</p> </li> <li> <p><strong>0110</strong>responde a: « ¿Cómo evitar que esta memoria ahogue al agente?</p> </li> <li> <p><strong>0111</strong>responde a : «¿Y si el problema no es el tamaño de los archivos, sino lo que hemos <strong>elegido</strong> poner en EAGER?</p> </li> </ul> </div> <div class="paragraph"> <p>El primer artículo construyó la estructura. El segundo añadió el mecanismo de envejecimiento. El tercero audita el contenido—y descubre que la metodología misma se ha convertido en el problema.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lo_que_habría_hecho_diferente">Lo que habría hecho diferente</h2> <div class="sectionbody"> <div class="paragraph"> <p>En retrospectiva, veo el error de diseño inicial.`AGENT_MODUS_OPERANDI.adoc`Fue creado como un documento único — un manifiesto. Era el enfoque correcto para formalizar el pensamiento. Pero una vez formalizado el pensamiento, el documento debería haberse dividido inmediatamente: lo esencial en EAGER, lo exhaustivo en cold.</p> </div> <div class="paragraph"> <p>Yo no lo hice porque estaba orgulloso del documento. 627 líneas de ingeniería pura, escritas a mano, cada sección fruto de una lección de sesión. Era mi obra. Y como todo autor, tuve dificultad para recortarla.</p> </div> <div class="paragraph"> <p>La lección :<strong>No es porque un documento sea bueno que debe cargarse automáticamente</strong>. La calidad del contenido no tiene relación con su pertinencia para el contexto inmediato del agente.</p> </div> <div class="paragraph"> <p>Hoy, la regla es sencilla: cualquier documento con más de 100 líneas en el contexto EAGER es sospechoso. Merece una auditoría. No una condenación — una auditoría. Y la pregunta nunca es « ¿deberíamos borrarlo ? » pero « ¿deberíamos cargarlo en cada sesión ?».</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_guía_para_auditar_su_propio_contexto">El guía para auditar su propio contexto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si ha seguido los dos primeros artículos y ha implementado su propia gobernanza Eager/Lazy, aquí tiene un procedimiento de auditoría en cinco pasos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Medir</strong>:`wc -l`en todos sus archivos EAGER. El total debería ser menos de 1000 líneas.</p> </li> <li> <p><strong>Identificar el más grande</strong>: el archivo que pesa más del 20% del total es el sospechoso número uno.</p> </li> <li> <p><strong>Auditar sección por sección</strong>: para cada sección, pregúntate « ¿Esta información ya está en otro lugar? ¿El agente ya la ha leído en otro archivo? ¿Ha servido en las últimas 5 sesiones ?</p> </li> <li> <p><strong>Clasificador</strong>: duplicado, nunca usado, conocimiento único.</p> </li> <li> <p><strong>Separar o relocalizar</strong>: lo que es único y crítico → ESSENTIALS compactado. Todo lo restante →<code>encyclopedies/</code>.</p> </li> </ol> </div> <div id="diag-audit-checklist" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-59036b142119740b160bc1978d4f7d88.svg" alt="Procédure d’audit en 5 étapes" width="540" height="741"> </div> </div> <div class="paragraph"> <p>Este procedimiento lleva 15 minutos. En un proyecto de 50 sesiones, ahorra cientos de tokens por sesión futura. El ROI es inmediato.</p> </div> </div> </div> <div class="sect1"> <h2 id="_una_gobernanza_viva">Una gobernanza viva</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo que esta serie de tres artículos me ha enseñado, es que la gobernanza de agentes no es un producto terminado. Es un<strong>organismo vivo</strong>Ella crece con el proyecto. Ella contrae enfermedades de crecimiento. Ella requiere chequeos regulares.</p> </div> <div class="paragraph"> <p>La sesión 048 reveló que los archivos se inflan. La sesión 051 reveló que la metodología misma se infla. La sesión 060 probablemente revelará otra cosa. Es normal. Es sano. Una gobernanza que nunca se cuestiona es una gobernanza muerta.</p> </div> <div class="paragraph"> <p>Los tres mecanismos implementados — Eager/Lazy, Hot/Warm/Cold, split enciclopédico — forman un sistema de defensa en profundidad contra la saturación del contexto. Ninguno es suficiente por sí solo. Juntos, se complementan :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ansioso/Perezoso</strong>estructura la información <strong>por disponibilidad</strong></p> </li> <li> <p><strong>Caliente/Tibio/Frío</strong>estructura la información <strong>por frescura</strong></p> </li> <li> <p><strong>Auditoría enciclopédica</strong>estructura la información por densidad</p> </li> </ul> </div> <div id="diag-defense-in-depth" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam nodeBackgroundColor #E3F2FD title Defensa en Profundidad contra la Saturación del Contexto node "**Contexto Agente** ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam nodeBackgroundColor #E3F2FD title Defensa en Profundidad contra la Saturación del Contexto node "**Contexto Agente** ~800 líneas sano" as CTX #C8E6C9 node "Capa 1 **EAGER / LAZY**" as C1 #BBDEFB node "Capa 2\n**HOT / WARM / COLD**" as C2 #BBDEFB node "Capa 3 **ESSENCIALES / ENCICLOPEDIA**" as C3 #BBDEFB CTX --> C1 : "Estructura por **disponibilidad**" CTX --> C2 : "Estructura por\n**frescura**" CTX --> C3 : "Estructura por\n**densidad**" note bottom of C3 Les trois couches sont nécessaires. Aucune n'est suffisante seule. end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Con estas tres capas, el contexto agente sobre`magic-stick`pasó de 2087 líneas (antes de cualquier optimización) a aproximadamente 800 líneas — una división por 2,6. Sin haber perdido ni una sola línea de documentación, ni un solo archivo de sesión, ni una sola lección aprendida.</p> </div> <div class="paragraph"> <p>Todo está aquí. Solo mejor organizado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_enlaces">Enlaces</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Artículo 0108 — Estrategia Eager/Lazy :<a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Gobernar un agente IA con AsciiDoc</a></p> </li> <li> <p>Artículo 0110 — Mecanismo Hot/Warm/Cold:<a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Ventana deslizante y onda fría</a></p> </li> <li> <p>Mi sitio: <a href="https://cheroliv.com" class="bare">https://cheroliv.com</a></p> </li> <li> <p>El proyecto`magic-stick`: <a href="https://github.com/cheroliv/magic-stick" class="bare">https://github.com/cheroliv/magic-stick</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p>El conocimiento no tiene que desaparecer. Solo tiene que no estar cargada cuando no es necesario.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0110_mecanisme_backup_contexte_agent_post.html Sun, 26 Apr 2026 00:00:00 +0000 blog/2026/0110_mecanisme_backup_contexte_agent_post.html <div class="sect1"> <h2 id="_resumen">Resumen</h2> <div class="sectionbody"> <div class="paragraph"> <p>Después de 48 sesiones en un solo proyecto y 150+ en total, el sistema de gobernanza Eager/Lazy que había construido con cuidado empezaba a ahogarse. Los archivos de agentes, supuestos de ser ligeros, pesaban 5200 líneas acumuladas. El contexto auto-cargado aumentaba más rápido que mi capacidad para controlarlo. Este artículo cuenta cómo conceptualicé un mecanismo de respaldo — entre ventana deslizante y ola fría idéntica — para mantener un contexto activo ligero sin perder nada.</p> </div> </div> </div> <div class="sect1"> <h2 id="_señal_5200_líneas">Señal: 5200 Líneas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estoy en plena sesión 048 sobre`magic-stick`, mi proyecto de construcción de ISO Linux en vivo. Opencode me observa. Como siempre, ha cargado automáticamente mis archivos Eager al comienzo de la sesión —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Nada anormal</p> </div> <div class="paragraph"> <p>Pero algo no cuadra. Las respuestas son más lentas. El razonamiento es más difuso. El agente olvida detalles que tenía a la vista hace dos mensajes.</p> </div> <div class="paragraph"> <p>Abro una terminal y tecleo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wc -l .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="paragraph"> <p>260 líneas para INDEX. 55 para SESSIONS_HISTORY.<strong>1756 para COMPLETED_TASKS_ARCHIVE</strong>.</p> </div> <div class="paragraph"> <p>El dossier`sessions/`ajoute aún ~3200 líneas. Total:<strong>5200 líneas</strong>de contexto que se cargan, de una manera u otra, en el cerebro temporal del agente</p> </div> <div class="paragraph"> <p>La estrategia Eager/Lazy que había teorizado en el artículo anterior funciona — pero tiene un defecto de nacimiento que no había anticipado: no tiene<strong>no hay mecanismo de envejecimiento</strong>. Cada sesión agrega una línea a INDEX, un párrafo a COMPLETED_TASKS, un archivo en sessions/. Nunca sale nada. El contexto es una bola de nieve que crece con cada nueva sesión.</p> </div> <div id="diag-growth" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-f6ae90468b25eb2ca7145d10e857b985.svg" alt="Courbe de croissance des fichiers agents — de la session 1 à 48" width="481" height="591"> </div> </div> <div class="paragraph"> <p>No es un error, es una consecuencia directa del procedimiento de finalización de sesión que archiva meticulosamente cada detalle. El sistema es víctima de su propio éxito.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_diagnóstico_triple_redundancia">El Diagnóstico: Triple Redundancia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le pido al agente que diagnostique el problema. Su respuesta es inmediata y quirúrgica.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Líneas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">rol</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">problema</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">260+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (cargado automático)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabla de todas las sesiones desde la 001 —<strong>+1 línea por sesión</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/SESSIONS_HISTORY.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">55</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabla resumen —<strong>redundancia con INDEX</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1756</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (implícito)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detalles completos de todas las sesiones de abril</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/sessions/*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[No French text was provided for translation, so no output is generated per instructions.]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PEREZOSO (supuesto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivos individuales, pero<strong>no utilizadas</strong>Porque todo ya está en COMPLETED_TASKS</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El agente identifica cuatro causas raíz:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE absorbe todo</strong>— En lugar de apuntar a los archivos`.sessions/`, copia íntegramente cada sesión.</p> </li> <li> <p><strong>INDEX.adoc cumple la función de un historial completo</strong>— La tabla "Sesiones Recientes" contiene 30+ entradas.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc redundante</strong>— Misma info que INDEX, formato diferente.</p> </li> <li> <p><strong>La regla LAZY no se cumple</strong>— COMPLETED_TASKS es implícitamente EAGER porque contiene todo.</p> </li> </ol> </div> <div class="paragraph"> <p>Su propuesta es radical: limitar INDEX a 10 sesiones, vaciar COMPLETED_TASKS, mover SESSIONS_HISTORY a LAZY puro. Ganancia inmediata :<strong>~1900 líneas ahorradas</strong>.</p> </div> <div class="paragraph"> <p>Es limpio, eficiente, lógico. Pero tengo un problema con este enfoque.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_rechacé_la_solución_evidente">¿Por qué rechacé la solución evidente?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La solución del agente es la de un ingeniero que optimiza una caché. Limitar. Truncar. Eliminar las redundancias.</p> </div> <div class="paragraph"> <p>Pero estas "redundancias" no lo son. Cada archivo de gobernanza captura un<strong>ángulo diferente</strong>sobre la misma realidad :</p> </div> <div class="ulist"> <ul> <li> <p><strong>ÍNDICE</strong>= vista macro, tablero ejecutivo</p> </li> <li> <p><strong>HISTORIAL_DE_SESIONES</strong>= tabla cronológica lineal, puntuada</p> </li> <li> <p><strong>ARCHIVO_DE_TAREAS_COMPLETADAS</strong>= narrativa detallada con métricas</p> </li> <li> <p>sessions/*.adoc" = archivos individuales, contexto completo</p> </li> </ul> </div> <div class="paragraph"> <p>No es una duplicación tonta. Es de la<strong>perspectiva múltiple estructurada</strong>. Es exactamente lo que necesitamos para destilar — para que más tarde, un humano (o un LLM futuro mejor entrenado) pueda cruzar los ángulos y extraer patrones.</p> </div> <div class="paragraph"> <p>Imagina a un científico de datos que te dice: «Eliminemos 3 columnas de 6, están correlacionadas». ¿Qué le respondes? Que la correlación no es redundancia cuando cada columna captura una dimensión diferente del mismo fenómeno. Que es precisamente esta riqueza dimensional la que hace que el conjunto de datos sea explotable.</p> </div> <div class="paragraph"> <p>Es mi intuición. Y la defiendo contra la racionalidad fría del agente.</p> </div> <div class="paragraph"> <p><em>__</em> No veo un saco de todo silencioso en mi idea. No rellenamos todo, desplazamos el resultado estructurado del procedimiento de fin de sesión — cada archivo con su ángulo, sus redundancias que en realidad son un enriquecimiento. Es este material multidimensional que será mejor para la destilación. (blank)</p> </div> <div class="paragraph"> <p>El agente encaja el golpe. Y se corrige.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_proposición_onda_fría_idéntica">La Proposición : Onda Fría Idéntica</h2> <div class="sectionbody"> <div class="paragraph"> <p>Entonces el agente propone un mecanismo más fino, que respeta mi intuición de conjunto de datos rico mientras resuelve el problema técnico del contexto que explota.</p> </div> <div class="paragraph"> <p>El principio es simple y se inspira directamente del patrón<strong>Almacenamiento en caliente/tibio/frío</strong>aplicado a la gestión de archivos:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Caliente (ANSIO)</strong>= las 10 sesiones más recientes en INDEX, PROMPT_REPRISE de la sesión N+1, los 2 últimos archivos de sesión</p> </li> <li> <p><strong>Cálido (PEREZOSO)</strong>= SESSIONS_HISTORY reciente, SCRIPT_VERIFICATION, toda la documentación de referencia</p> </li> <li> <p><strong>frío (copia/)</strong>= todo lo demás, desplazado<strong>intacto</strong>, sin transformación, sin reindexación</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- .agents/ ├── INDEX.adoc → Sessions N-9 à N (10 dernières) ├── SESSIONS_HISTORY.adoc → Sessions N-9 à N ├── SCRIPT_VERIFICATION.adoc → Dernière vérif (pas d'historique) ├── PROMPT_REPRISE.adoc → Session N+1 uniquement ├── sessions/ → Sessions N-1 à N uniquement └── backup/ └── Y2026-sessions-001-039/ ← Vague froide, COPIE INTÉGRALE ├── INDEX.adoc → Sessions 001 à 039 (complet) ├── SESSIONS_HISTORY.adoc → Sessions 001 à 039 (complet) ├── COMPLETED_TASKS_ARCHIVE.adoc → Sessions 001 à 039 (complet) └── sessions/ → 001.adoc, 002.adoc... ---- La clave del mecanismo:**La copia de seguridad no es un índice central, es una copia fiel de la ola pasada**. Cuando se supera el horizonte de las 10 sesiones activas, no se elimina nada. No se reindexa nada. No se fusiona nada. Se toma el paquete de archivos de agentes tal como estaba en la sesión N-10, y se mueve a`backup/`. Los archivos activos, por su parte, están truncados: * INDEX : solo las últimas 10 líneas (ventana deslizante) * SESSIONS_HISTORY : lo mismo * COMPLETED_TASKS_ARCHIVE : nuevo archivo para el período en curso * sessions/ : únicamente las 2 últimas sesiones [plantuml, format=svg, id=diag-hot-warm-cold, alt="Architecture Hot/Warm/Cold du contexte agent — EAGER/LAZY/backup"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Arquitectura Hot / Warm / Cold del Agente de Contexto package "HOT (EAGER)\nCargado automáticamente\n~300 líneas" as HOT #FFCDD2 { file "INDEX.adoc\n(10 sesiones)" as IDX_HOT file "PROMPT_REPRISE\n(sesión N+1)" as PRO_HOT file "AGENT.adoc\n(reglas absolutas)" as AG_HOT } package "WARM (LAZY) Cargado bajo demanda ~500 líneas" as WARM #FFF9C4 { file "SESSIONS_HISTORY\n(10 últimos)" as HIS_WARM file "SCRIPT_VERIFICATION (última)" as VER_WARM file "PROCEDURES.adoc (templates)" as PRO_WARM file "*_REFERENCE.adoc\n(documento técnico)" as REF_WARM } package "COLD (backup/)\nNunca cargado\nSólo lectura humana" as COLD #BBDEFB { folder "Y2026-001-039/" as WAVE { file "ÍNDICE (completo)" as IDX_COLD file "SESSIONS_HISTORY\n(completo)" as HIS_COLD file "COMPLETED_TASKS\n(completado)" as ARCH_COLD folder "sesiones/ (001-039)" as SESS_COLD } folder "Y2026-040-??? (futuro)" as FUTURE } HOT --> WARM : "Agente sube si es necesario" WARM --> COLD : "Nunca automático El ser humano va allí solo" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- El beneficio inmediato es masivo: el contexto EAGER pasa de**~5200 líneas a ~300 líneas**. Una división por 17. Sin haber perdido una sola línea de datos históricos. == ¿Por qué no es un cajón de sastre? El agente, en su primera iteración, temía que`backup/`Se convierta en una caja negra — una carpeta donde se archivan documentos que nunca volveremos a leer. Es un temor legítimo. Pero descansa sobre un error de concepto. Un cajón de sastre es cuando se tiran archivos.**sin estructura, sin convención, sin lógica de agrupación**. Aquí, el backup está estructurado por período (Y2026-001-039), y cada carpeta de backup contiene**la misma estructura**que el expediente`.agents/`activo: INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/ No es un cajón de sastre. Es un**instantánea horodatada**. Se podría incluso decir que es un mecanismo de versionado simplificado — con la salvedad de que no versiona los archivos individualmente, sino el paquete completo de la gobernanza en un momento dado. Cuando quieras recuperar una información antigua, no necesitas un índice central. Tienes dos opciones: 1. **grep` dirigido**:`grep -r "zsh" backup/Y2026-001-039/`— y encuentras todo lo que menciona zsh en el período, sin importar el ángulo (INDEX, SESSIONS_HISTORY, archivo de sesión). 2. **Reintegración manual**: copias temporariamente la carpeta de backup en el contexto activo, y le pides al agente que analice este período específico. El índice es implícito. Está en la misma estructura de los archivos — cada uno ya siendo un índice desde su propio ángulo. == La metáfora de las estanterías Para hacer el mecanismo intuitivo, lo he conceptualizado en tres estantes : * **Estantería 1 (EAGER)**— el plan de trabajo. Lo que necesito *ahora*. INDEX reciente, PROMPT_REPRISE, reglas absolutas. Ligero, inmediato, crítico. * **Estantería 2 (LAZY)**— la biblioteca de consulta. Lo que puedo buscar bajo petición. Referencias técnicas, historial reciente, procedimientos. Más voluminoso, pero no cargado en memoria. * **Bodega (backup/)**— los archivos fríos. Todo lo que ha pasado pero que no quiero desechar. El agente nunca entra allí. El ser humano baja cuando quiere destilar. El agente propuso inicialmente una cuarta estantería — un`index-backup.adoc`que sería LAZY y contendría un índice de todo el backup. Lo rechacé. Sería una redundancia más en un sistema que ya sufre de crecimiento lineal. La estructura de los archivos archivados ya es un índice. == El sensor de dos disparadores La conceptualización era sólida, pero quedaba un punto ciego:**¿Cuándo exactamente desencadenar la rotación?**El artículo inicial lo identificaba como una pregunta abierta. Dos días después, la respuesta está codificada en los archivos de gobernanza de seis proyectos: un sensor con dos disparadores. === El Desencadenador Automático — `N % 10 == 0 El primer desencadenante es matemático. Cuando el número de sesión es múltiplo de 10 — sesión 10, 20, 30, 40 — la rotación de backup se ejecuta automáticamente dentro del procedimiento de fin de sesión, justo después del paso 6. ¿Por qué 10? Es el compromiso entre dos fuerzas opuestas: una ventana demasiado corta (5 sesiones) pierde el contexto necesario para la continuidad; una ventana demasiado larga (20 sesiones) no resuelve el problema de sobrepeso del contexto. Diez sesiones, a un ritmo de una a dos sesiones por día, cubren aproximadamente una semana de trabajo — suficiente para que el agente recuerde las decisiones recientes, pero no suficiente para que el contexto explote. === El Desencadenante por Umbral — 500 Líneas EAGER El segundo disparador es dinámico. Independientemente del número de sesión, si los archivos EAGER acumulados superan**500 líneas**, la rotación se dispara. Este umbral protege contra el escenario en el que las sesiones son excepcionalmente productivas — mucho contenido escrito en pocas sesiones. Una sesión que produce 120 líneas de contenido editorial hace crecer COMPLETED_TASKS_ARCHIVE mucho más rápido que una sesión de depuración que corrige dos líneas. El umbral de 500 líneas, medido vía`wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, detecta esta asimetría. === El Desencadenador Manual — "copia de seguridad de rotación Finalmente, el humano mantiene el control. Las palabras clave`rotation backup`, `backup rotation` ou `lance la rotation backup`Activan el procedimiento a petición, independientemente del final de la sesión. Útil cuando se siente que el contexto se vuelve pesado pero aún no se ha alcanzado un múltiplo de 10, o cuando se desea archivar una fase de trabajo antes de comenzar una nueva. [plantuml, format=svg, id=diag-capteur-trigger, alt="Les trois déclencheurs du capteur de rotation backup — automatique, seuil, manuel"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Sensor de Rotación Backup — Los Tres Desencadenadores start :Procédure de fin de session; note right: Mots-clés "fin de la sesión"\nou "paramos aquí" :Étapes 1 à 6\n(archivage standard); note right 1. Archive sessions/N.adoc 2. MAJ PROMPT_REPRISE 3. MAJ SESSIONS_HISTORY 4. MAJ INDEX.adoc 5. MAJ TEST_COVERAGE 6. MAJ COMPLETED_TASKS end note if (N % 10 == 0\nOU\nEAGER cumulé > 500 lignes ?) then (oui) :⚙️ Rotation Backup\n(étape 7); note right 1. Créer backup/Y20XX-sessions-X-Y/ 2. Copier intégrale INDEX + HISTORY + COMPLETED_TASKS + sessions/ 3. Tronquer actifs à 10 sessions 4. Ajouter _Localisation active_ end note else (non) :Pas de rotation; endif :Checklist [✅] x 7\n(si applicable); stop @enduml ---- Este diagrama muestra la inserción exacta del sensor en el procedimiento de finalización de sesión. El paso 7 es opcional — solo se ejecuta si una de las dos condiciones es verdadera — pero se *verificada* sistemáticamente. La lista de verificación final incluye`[✅] 7. Backup roté (si applicable)`. === El Bucle Cerrado Este sensor cierra el bucle abierto por el artículo anterior. La gobernanza Eager/Lazy había resuelto el problema de la memoria del agente entre dos sesiones. El mecanismo Hot/Warm/Cold ha resuelto el problema de la memoria que aumenta. El sensor de dos desencadenantes resuelve el problema del *cuándo* — quitando al humano la carga mental de vigilar el tamaño del contexto. [plantuml, format=svg, id=diag-boucle-fermee, alt="Les trois couches de la gouvernance agent — Eager/Lazy, Hot/Warm/Cold, Capteur"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Las Tres Capas de la Gobernanza de Agentes left to right direction package "Capa 1 — Memoria\n(Artículo 0108)" as C1 #E8F5E9 { rectangle "**EAGER** Panel de control Cargado automáticamente" as EAG rectangle "**LAZY** Manual del propietario Cargado bajo demanda" as LAZ EAG -[hidden]right-> LAZ } package "Capa 2 — Envejecimiento (Artículo 0110)" as C2 #FFF9C4 { rectangle "**HOT** 10 sesiones activas ~300 líneas" as HOT rectangle "**WARM** Referencias Procedimientos" as WRM rectangle "**FRÍO** backup/ Ola fría" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "Capa 3 — Desencadenante\n(Hoy)" as C3 #BBDEFB { rectangle "**Automático** N % 10 == 0" as AUTO rectangle "**Umbral**\n> 500 líneas" as SEUIL rectangle "**Manuel** copia de seguridad rotativa" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "La memoria crece\n→ hace falta un mecanismo\nde envejecimiento" C2 --> C3 : "El envejecimiento → hace falta un desencadenador para ejecutarlo" note bottom of C3 ✅ Déployé sur 6 projets magic-stick · bakery-gradle plantuml-gradle · cheroliv.com jhipster-gradle-plugins quizz-benchmark-gradle end note @enduml ---- Las tres capas se apilan lógicamente. La primera le da una memoria al agente. La segunda impide que esa memoria ahogue al agente. La tercera automatiza el mantenimiento de esa memoria para que el humano no tenga que pensar en ello. === La migración efectiva en cheroliv.com El mecanismo no se quedó teórico. Sobre`cheroliv.com`, la primera rotación de copia de seguridad se ejecutó el 29 de abril de 2026 — las sesiones -6 a 2 se han migrado a`.agents/backup/Y2026-sessions-neg6-a-002/`: |=== |Archivo |Antes de la rotación |Después de la rotación |ganancia |`.agents/INDEX.adoc` |19 sesiones listadas |10 sesiones (3-12) |-9 entradas |`.agents/SESSIONS_HISTORY.adoc` |18 sesiones |10 sesiones |-8 entradas |`COMPLETED_TASKS_ARCHIVE` |161 líneas (sesiones 1-12) |135 líneas (sesiones 3-12) |-26 líneas |`sessions/` |20 archivos |10 archivos |-10 archivos |**copia de seguridad/** |inexistente |1 ola fría (10 sesiones archivadas) |+1 paquete frío |=== La ganancia en líneas era modesta — el proyecto es joven, 12 sesiones — pero lo importante es que el**el mecanismo está establecido**. La próxima rotación automática se activará en la sesión 20, o antes si se alcanzan las 500 líneas EAGER. == La Lección Humano-Agente Esta sesión 048 me ha enseñado algo fundamental sobre la colaboración con un agente IA. El agente tiene un sesgo natural: busca**optimizar**, à **simplificar**, à **eliminar las redundancias**. Es el sesgo de un sistema entrenado para producir respuestas limpias y concisas. Ante un conjunto de datos rico y multidimensional, su primer reflejo es reducirlo a su forma más simple. El ser humano, por su parte, tiene una intuición diferente: presiente que la redundancia estructurada es una**ventaja**, no es un defecto. Que la diversidad de ángulos sobre una misma realidad es precisamente lo que permitirá, más tarde, una destilación de calidad. No es que el agente esté equivocado. Es que su 'óptimo' no es el mío. El agente optimiza para el**presente**— el contexto inmediato, la respuesta rápida a la pregunta planteada. El ser humano optimiza para el**futuro**— la capacidad de encontrar, cruzar, destilar en tres meses o tres años. ____ Lo que quiero es el material bruto. Tus reflexiones, tus dudas, tus respuestas a mis preguntas. No tu síntesis. La síntesis, sé hacerla mejor que tú. Quiero la materia prima. ____ Esta frase que le dije al final de la sesión lo resume todo. El agente es una herramienta de producción. El humano es la herramienta de destilación. La gobernanza no está hecha para que el agente lo entienda todo solo — está hecha para que el humano pueda, más tarde, trabajar el material producido. La ola fría idéntica es la traducción arquitectónica de esta filosofía: no se tira nada, no se fusiona nada, no se reindexa nada. Se desplaza el paquete intacto. La destilación vendrá más tarde, a mano, por el humano. == La continuación lógica del artículo anterior Si has leídolink:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[el artículo sobre la estrategia Eager/Lazy], reconocerá la progresión natural : 1. **Artículo 0108**El gobierno Eager/Lazy: *cómo* estructurar el contexto del agente en dos niveles de disponibilidad 2. **Este artículo 0110**— El mecanismo de backup : *comment* hacer envejecer este contexto sin perderlo cuando se vuelve demasiado voluminoso El primer artículo respondía a la pregunta: « El agente no recuerda nada entre dos sesiones, ¿cómo darle una memoria? Esto responde a la pregunta que inevitablemente se deriva de la primera: «La memoria crece en cada sesión, ¿cómo impedir que ahogue al agente sin borrarla? La respuesta está en un patrón:**Caliente/Templado/Frío**, aplicado a los archivos de gobernanza. Y en principio:**nunca perder nada, siempre relocalizar todo**. == Enlaces * Artículo anterior :link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gobernar un agente IA con AsciiDoc] * Mi sitio: https://cheroliv.com * El proyecto`magic-stick`: https://github.com/cheroliv/magic-stick --- Un buen sistema de gobernanza nunca elimina datos. Los ordena. ----</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html Sat, 25 Apr 2026 00:00:00 +0000 blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_un_proyecto_jhipster_una_compilación_que_ya_no_carga">La escena: un proyecto JHipster, una compilación que ya no carga</a></li> <li><a href="#_error_1_la_variable_fantasma_reportsdir">Error 1 : la variable fantasma `reportsDir</a></li> <li><a href="#_error_2_main_ya_no_existe_en_gradle_9">Error 2: <code>main = \"…​\"</code> ya no existe en Gradle 9</a></li> <li><a href="#_error_3_sourcecompatibility_ya_no_es_una_propiedad_del_proyecto">Error 3: <code>sourceCompatibility</code> ya no es una propiedad del proyecto</a></li> <li><a href="#_error_4_la_afirmación_de_groovy_a_tres_operandos">Error 4 : la afirmación de Groovy a tres operandos</a></li> <li><a href="#_error_5_la_dependencia_implícita_compilekotlin_openapigenerate">Error 5 : la dependencia implícita <code>compileKotlin</code> → `openApiGenerate</a></li> <li><a href="#_error_6_generategitproperties_falla_en_filteroutputstream_write">Error 6 : <code>generateGitProperties</code> falla en `FilterOutputStream.write()</a></li> <li><a href="#_finalmente_testcontainers_entra_en_escena">Finalmente: Testcontainers entra en escena</a></li> <li><a href="#_fase_1_la_pista_docker_java">Fase 1: la pista docker-java</a></li> <li><a href="#_fase_2_búsqueda_web_y_camino_de_migas_de_pan_github">Fase 2 : búsqueda web y camino de migas de pan GitHub</a></li> <li><a href="#_fase_3_la_trampa_de_los_artifacts_renombrados">Fase 3 : la trampa de los artifacts renombrados</a></li> <li><a href="#_fase_4_forzar_la_resolución">Fase 4 : forzar la resolución</a></li> <li><a href="#_resultado_final">Resultado final</a></li> <li><a href="#_resumen_de_correcciones">Resumen de correcciones</a></li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 15 minutes</div> <p>Ya has conocido ese momento en el que un simple`./gradlew build`que lanzas cien veces al día se bloquea repentinamente ante un error nunca visto ? Multiplícalo por once errores sucesivos, agrega una buena dosis de incompatibilidad de Docker Engine 29, espolvorea con Gradle 9 que hace desaparecer las API que utilizábamos desde hace diez años. Aquí tienes el cuaderno de bitácora completo.</p> </div> <hr> <div class="paragraph"> <div class="title">Diagrama 1 — Migración Gradle 9 (cadena de errores)</div> <p>Objetivo: mostrar la serie de incompatibilidades.</p> </div> <div class="listingblock"> <div class="title">👉 Claro, centrado en Gradle.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml left to right direction title Migración Gradle 9 rectangle "1\nreportsDir" as A rectangle "2 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml left to right direction title Migración Gradle 9 rectangle "1\nreportsDir" as A rectangle "2 clase principal" as B rectangle "3\nsourceCompatibility" as C rectangle "4\nGroovy assert" as D A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">Diagrama 2 — Plugins JHipster incompatibles</div> <p>Objetivo: aislar los plugins rotos.</p> </div> <div class="listingblock"> <div class="title">👉 Visión propia de las dependencias</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml left to right direction title Plugins a corregir skinparam shadowing false skinparam roundcorner 18 rectangle "1 ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml left to right direction title Plugins a corregir skinparam shadowing false skinparam roundcorner 18 rectangle "1 openApiGenerate" as A #FFF3E0 rectangle "2 gitProperties 2.5.7" as B #FFF3E0 rectangle "3 Versiones corregidas" as C #E3F2FD rectangle "4\nEnsamblar OK" as D #E8F5E9 A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">Diagrama 3 — Docker 29 / Testcontainers</div> <p>Objetivo: problema de tiempo de ejecución.</p> </div> <div class="listingblock"> <div class="title">👉 Historia clara del runtime.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 12) ] @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1\nEnsambla OK" as A #E8F5E9 rectangle "2\nTests Cucumber FAIL" as B #FFEBEE rectangle "3\nTestcontainers 1.32\nrechazado" as C #FFF3E0 rectangle "4 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1\nEnsambla OK" as A #E8F5E9 rectangle "2\nTests Cucumber FAIL" as B #FFEBEE rectangle "3\nTestcontainers 1.32\nrechazado" as C #FFF3E0 rectangle "4 Actualización versiones es es es versiones" as D #E3F2FD rectangle "5\nCompilación final OK" as E #E8F5E9 A --> B B --> C C --> D D --> E @enduml</pre> </div> </div> <hr> <div class="listingblock"> <div class="title">otra manera de representárselo</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 17) ] @startuml skinparam backgroundColor #FEFEFE skinparam shadowing false skinparam defaultFontName Inter skinparam defaultFontSize 14 skinparam ArrowThickness 2 skinparam RoundCorner 18 title Roadmap de Estabilización — Gradle 9 hacia Build Final left to right direction rectangle "�⚙️ Migración Gradle 9" as A #E3F2FD rectangle "Plugins JHipster" as B #FFF3E0 rectangle "🐳 Docker 29 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml !option handwritten true skinparam backgroundColor #FEFEFE skinparam shadowing false skinparam defaultFontName Inter skinparam defaultFontSize 14 skinparam ArrowThickness 2 skinparam RoundCorner 18 title Roadmap de Estabilización — Gradle 9 hacia Build Final left to right direction rectangle "�⚙️ Migración Gradle 9" as A #E3F2FD rectangle "Plugins JHipster" as B #FFF3E0 rectangle "🐳 Docker 29 Testcontainers" as C #FCE4EC rectangle "�✅ Build Estable" as D #E8F5E9 note bottom of A reportsDir mainClass sourceCompatibility Groovy assert end note note bottom of B openApiGenerate gitProperties versions alignées end note note bottom of C tests Cucumber KO image Docker rejetée upgrade libs end note A -[#42A5F5]-> B : corrections build.gradle B -[#FB8C00]-> C : assemble OK C -[#E53935]-> D : tests réparés @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_un_proyecto_jhipster_una_compilación_que_ya_no_carga">La escena: un proyecto JHipster, una compilación que ya no carga</h2> <div class="sectionbody"> <div class="paragraph"> <p>El proyecto`edster`es una aplicación JHipster generada en 2024. El script de build raíz`build.gradle`estuvo estable durante meses. Entonces deciden subir a una versión:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Componente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Versión objetivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9.4.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21.0.11-tem (Eclipse Temurin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JHipster</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8.x (framework`tech.jhipster:jhipster-framework:8.11.0`)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spring Boot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3.4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.3.0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Docker Engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29.4.1 (API 1.54)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El cambio de versión de Java se realiza mediante SDKMAN:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk use java 21.0.11-tem</code></pre> </div> </div> <div class="paragraph"> <p>Primer lanzamiento:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon FAILURE: Build failed with an exception. * Where: Build file '/home/.../edster/build.gradle' line: 18 * What went wrong: An exception occurred applying plugin request [id: 'jhipster.cucumber-conventions'] > Failed to apply plugin 'jhipster.cucumber-conventions'. > Could not create task ':cucumberTest'. > Could not create task ':consoleLauncherTest'. > Could not set unknown property 'reportsDir' for task ':consoleLauncherTest'</code></pre> </div> </div> <div class="paragraph"> <p>No podemos ni siquiera iniciar la carga del script de compilación. El problema está en`buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_1_la_variable_fantasma_reportsdir">Error 1 : la variable fantasma `reportsDir</h2> <div class="sectionbody"> <div class="paragraph"> <p>El script`jhipster.cucumber-conventions.gradle`contiene:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">tasks.register('consoleLauncherTest', JavaExec) { dependsOn(testClasses) String cucumberReportsDir = file("$buildDir/reports/tests") outputs.dir(reportsDir) // <-- reportsDir n'existe PAS classpath = sourceSets["test"].runtimeClasspath main = "org.junit.platform.console.ConsoleLauncher" // ... }</code></pre> </div> </div> <div class="paragraph"> <p>La variable definida es`cucumberReportsDir`. La utilizada es`reportsDir`-- que no está definida en ninguna parte.</p> </div> <div class="paragraph"> <p><strong>Corrección</strong>:`outputs.dir(cucumberReportsDir)`</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_2_main_ya_no_existe_en_gradle_9">Error 2: <code>main = \"…​\"</code> ya no existe en Gradle 9</h2> <div class="sectionbody"> <div class="paragraph"> <p>Reinicio inmediato:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'main' for task ':consoleLauncherTest' of type org.gradle.api.tasks.JavaExec.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 elimina la propiedad`main`en beneficio de`mainClass`sobre las tareas`JavaExec`.</p> </div> <div class="paragraph"> <p><strong>Corrección</strong> : <code>mainClass = "org.junit.platform.console.ConsoleLauncher"</code></p> </div> </div> </div> <div class="sect1"> <h2 id="_error_3_sourcecompatibility_ya_no_es_una_propiedad_del_proyecto">Error 3: <code>sourceCompatibility</code> ya no es una propiedad del proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuevo error:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'sourceCompatibility' for root project 'edster' of type org.gradle.api.Project.</code></pre> </div> </div> <div class="paragraph"> <p>El script raíz tenía:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">sourceCompatibility=17 targetCompatibility=17</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 elimina estas propiedades a nivel raíz. Deben vivir en un bloque.<code>java</code>.</p> </div> <div class="paragraph"> <p><strong>Corrección</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">java { sourceCompatibility = JavaVersion.VERSION_21 targetCompatibility = JavaVersion.VERSION_21 }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_error_4_la_afirmación_de_groovy_a_tres_operandos">Error 4 : la afirmación de Groovy a tres operandos</h2> <div class="sectionbody"> <div class="paragraph"> <p>El antiguo script contenía :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] == "17" || "21" || "24"</code></pre> </div> </div> <div class="paragraph"> <p>En Groovy,<code>"21"</code> et <code>"24"`son strings truthy. La expresión se resuelve en</code>(…​ == "17") || true || true`, lo cual es siempre cierto — pero la sintaxis no es válida para la afirmación estricta deseada.</p> </div> <div class="paragraph"> <p><strong>Corrección</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] in ["17", "21", "23", "24"]</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_error_5_la_dependencia_implícita_compilekotlin_openapigenerate">Error 5 : la dependencia implícita <code>compileKotlin</code> → `openApiGenerate</h2> <div class="sectionbody"> <div class="paragraph"> <p>El build progresa. Compilación de Kotlin exitosa. Luego:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Task ':compileKotlin' uses this output of task ':openApiGenerate' without declaring an explicit or implicit dependency.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 rechaza las dependencias implícitas entre tareas. Desde`compileKotlin`lee las fuentes generadas por`openApiGenerate`, hay que declarar el enlace</p> </div> <div class="paragraph"> <p><strong>Corrección</strong>en`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">afterEvaluate { tasks.named("compileKotlin").configure { dependsOn(tasks.named("openApiGenerate")) } }</code></pre> </div> </div> <div class="paragraph"> <p>Le `afterEvaluate`es necesario porque`openApiGenerate`es una extensión (plugin OpenAPI Generator) y no una tarea directamente accesible durante la fase de configuración.</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_6_generategitproperties_falla_en_filteroutputstream_write">Error 6 : <code>generateGitProperties</code> falla en `FilterOutputStream.write()</h2> <div class="sectionbody"> <div class="paragraph"> <p>La compilación Java pasa. Los recursos son procesados. Entonces:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">> Task :generateGitProperties FAILED No signature of method: java.io.FilterOutputStream.write() is applicable for argument types: (Integer) values: [103]</code></pre> </div> </div> <div class="paragraph"> <p>El plugin`gradle-git-properties`la versión 2.5.0 es incompatible con Java 21 / Gradle 9. Un error interno intenta llamar`write(int)`a través de Groovy en un flujo que lo cerró.</p> </div> <div class="paragraph"> <p><strong>Corrección</strong>en`gradle.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">gitPropertiesPluginVersion=2.5.7</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_finalmente_testcontainers_entra_en_escena">Finalmente: Testcontainers entra en escena</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hasta ahora, era "build script debugging" puro. Cada error era una incompatibilidad de Gradle 9 o Java 21 en los scripts de construcción. Después de las seis correcciones anteriores, el`./gradlew assemble`pasa con éxito.</p> </div> <div class="paragraph"> <p>Pero`./gradlew build`ejecuta también las pruebas, y las pruebas de Cucumber utilizan Testcontainers para iniciar un PostgreSQL efímero.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not find a valid Docker environment. EnvironmentAndSystemPropertyClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"} UnixSocketClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"}</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers es incapaz de comunicarse con Docker. Dos estrategias diferentes (variables de entorno + socket Unix) fallan con el mismo error.</p> </div> <div id="diag-docker-handshake" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers\n1.20.6" as TC participant "docker-java ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers\n1.20.6" as TC participant "docker-java 3.4.1" as DJ participant "Docker Engine 29.4.1" as DE TC -> DJ : new DockerClient() DJ -> DE : GET /_ping\nUser-Agent: docker-java/3.4.1\nAPI-Version: 1.32 DE --> DJ : HTTP 400 Bad Request\nclient version 1.32 is too old.\nMinimum supported API version is 1.40 DJ --> TC : BadRequestException TC --> TC : Could not find a valid\nDocker environment note right of DE Docker Engine 29.x impose API minimum = 1.40 (défaut ancien : 1.24) end note note left of DJ docker-java 3.4.1 envoie hardcoded API version 1.32 dans l'en-tête HTTP end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_1_la_pista_docker_java">Fase 1: la pista docker-java</h2> <div class="sectionbody"> <div class="paragraph"> <p>Primer reflejo : el cliente Docker Java utilizado por Testcontainers envía la versión API`1.32`en su handshake HTTP, pero Docker Engine 29.4.1 requiere un mínimo de`1.40`. El problema está a nivel del cliente, no del daemon.</p> </div> <div class="paragraph"> <p>Verificación de la versión de docker-java resuelta por Testcontainers 1.20.6 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew dependencies --configuration testRuntimeClasspath | grep docker-java +--- com.github.docker-java:docker-java-api:3.4.1 +--- com.github.docker-java:docker-java-transport:3.4.1</code></pre> </div> </div> <div class="paragraph"> <p>docker-java 3.4.1, de Testcontainers 1.20.6. La última versión pública de docker-java es 3.5.1. Intentemos forzar la actualización de la versión mediante`resolutionStrategy`en el bloque`configurations` de <code>build.gradle</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.5.1") } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Reinicio del build. Mismo error:`client version 1.32 is too old`.</p> </div> <div class="paragraph"> <p>Comprobación del caché de Gradle : los JARs han sido re-descargados correctamente, pero el error persiste. docker-java 3.5.1 sigue enviando`1.32`. Esta versión por lo tanto NO es suficiente para Docker Engine 29.4.1.</p> </div> <div class="paragraph"> <p><strong>Acción de purificación</strong>: vaciar completamente el caché de Gradle, solo para estar seguro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">rm -rf ~/.gradle/caches rm -rf /path/to/project/.gradle</code></pre> </div> </div> <div class="paragraph"> <p>Reinicio completo después de la purga. Mismo error.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_2_búsqueda_web_y_camino_de_migas_de_pan_github">Fase 2 : búsqueda web y camino de migas de pan GitHub</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1 es insuficiente. Solo queda buscar si alguien ha encontrado este problema exacto.</p> </div> <div class="paragraph"> <p>Búsqueda específica sobre los problemas testcontainers-java y docker-java :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">site:github.com/testcontainers "client version 1.32 is too old" site:github.com/docker-java "client version 1.32" Docker Engine 29</code></pre> </div> </div> <div class="paragraph"> <p>Primeros resultados inmediatos :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11210">testcontainers-java#11210</a>—<code>[Bug]: client version 1.32 is too old. Minimum supported API version is 1.44</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11212">testcontainers-java#11212</a>—<code>[Bug]: Docker 29.0.0 could not find a valid Docker environment</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11491">testcontainers-java#11491</a>—<code>[Bug]: Incompatibility in Ubuntu Github runners with Docker Engine 29.1.*</code></p> </li> </ul> </div> <div class="paragraph"> <p>El rastro de migas es claro: Docker Engine 29.x ha elevado su versión mínima de API de`1.24`(antiguo defecto) a`1.40`. Testcontainers 1.20.x utiliza docker-java 3.4.x que negocia la versión de la API al enviar`1.32`. El daemon rechaza cortés pero firmemente.</p> </div> <div class="paragraph"> <p>En el issue #11491, un mantenedor responde:</p> </div> <div class="paragraph"> <p><em>__</em> Hola, tengo un proyecto en ejecución con la versión 2.0.3 en un runner de GH con motor 29.1 y funciona. ¿Podrían todos comprobar por favor que no haya ningún conflicto de versiones? Por favor, recuerda que todos los módulos estaban prefijados con`testcontainers-<code>. Así que, empezando con la versión 2.x pasamos de`postgresql</code> to <code>testcontainers-postgresql</code> (blank)</p> </div> <div class="paragraph"> <p>Esta respuesta contiene<strong>dos informaciones críticas</strong>(empty)</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+ resuelve el problema</p> </li> <li> <p>Los módulos han sido<strong>renombrados con el prefijo `testcontainers-</strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_la_trampa_de_los_artifacts_renombrados">Fase 3 : la trampa de los artifacts renombrados</h2> <div class="sectionbody"> <div class="paragraph"> <p>El renombramiento es brutal. En Testcontainers 2.x, ninguno de los antiguos nombres funciona bajo ese nombre :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Antiguo nombre (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nuevo nombre (2.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">sin cambios</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Primer intento: aplicar la BOM Testcontainers 2.0.5 y los nuevos nombres de artefactos en`build.gradle`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers" }</code></pre> </div> </div> <div class="paragraph"> <p><code>./gradlew build</code></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">FAILURE: Could not find org.testcontainers:jdbc:2.0.5. Could not find org.testcontainers:junit-jupiter:2.0.5.</code></pre> </div> </div> <div class="paragraph"> <p><strong>El BOM de testcontainers-bom no es suficiente.</strong>¿Por qué? Porque Spring Boot 3.4.5 expone su propio BOM de gestión de dependencias`spring-boot-dependencies`) quien<strong>gana</strong>en el BOM de Testcontainers en la resolución transitiva. Spring Boot establece`testcontainers` à <code>1.20.6</code>, y por lo tanto todos los artefactos que no están explícitamente en el BOM de Spring Boot (como los nuevos`testcontainers-*<code>) resuelven a los antiguos nombres`1.20.6</code>-- que ya no existen en esta versión.</p> </div> <div class="paragraph"> <p>Al inspeccionar el`dependencies --configuration testRuntimeClasspath`, se encuentra :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">+--- org.testcontainers:testcontainers -> 1.20.6 (*) | \--- org.testcontainers:testcontainers:2.0.5 -> 1.20.6</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>→`indica la sustitución: Testcontainers 2.0.5 es <strong>solicitado</strong>, pero Spring Boot fuerza`1.20.6</code>.</p> </div> <div id="diag-bom-war" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 17) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle\n(consumidor)" as BG #E3F2FD { rectangle "solicitud\n`testcontainers-bom:2.0.5" as REQ rectangle "solicitud\n`testcontainers-postgresql" as REQ2 } component "Maven Central" as MC #FFF3E0 component "Declaraciones" as DEC #E8F5E9 { rectangle "testcontainers-bom:2.0.5`\ncorrige 2.0.5" as BOM2 rectangle "spring-boot-dependencies:3.4.5` ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle\n(consumidor)" as BG #E3F2FD { rectangle "solicitud\n`testcontainers-bom:2.0.5" as REQ rectangle "solicitud\n`testcontainers-postgresql" as REQ2 } component "Maven Central" as MC #FFF3E0 component "Declaraciones" as DEC #E8F5E9 { rectangle "testcontainers-bom:2.0.5`\ncorrige 2.0.5" as BOM2 rectangle "spring-boot-dependencies:3.4.5` fijo 1.20.6" as BOM1 } component "Resolución Gradle" as RES #FFEBEE { rectangle "Versión ganadora\n`testcontainers:1.20.6" as WIN #EF9A9A } BG --> DEC : "analiza los BOMs" BOM2 --> RES : "propone 2.0.5" BOM1 --> RES : "propone 1.20.6" WIN -> MC : "descarga testcontainers:1.20.6" note bottom of WIN Spring Boot BOM prime car le plugin spring-boot applique ses dépendances de gestion après la résolution du consommateur end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_4_forzar_la_resolución">Fase 4 : forzar la resolución</h2> <div class="sectionbody"> <div class="paragraph"> <p>La estrategia se vuelve doble:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Forzar docker-java a su versión 3.7.1 (probada como compatible con Docker Engine 29)</p> </li> <li> <p>Forzar Testcontainers core a 2.0.5 evitando el BOM de Spring Boot</p> </li> </ol> </div> <div id="diag-resolution-override" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle (con resolutionStrategy)" as BG #E8F5E9 { rectangle "BOM Testcontainers `2.0.5" as BOM2 rectangle "resolutionStrategy\n.eachDependency" as RS #66BB6A } component "Conflicto resuelto" as RESOLVED #E3F2FD { rectangle "docker-java\n`3.7.1` (forzado)" as DJ rectangle "testcontainers `2.0.5` (forzado)" as TC #81C784 rectangle "testcontainers-postgresql `2.0.5" as TPG rectangle "testcontainers-jdbc\n`2.0.5" as TJ rectangle "testcontainers-junit-jupiter `2.0.5" as TJJ } component "BOM Spring Boot\n(implícito, sobrescrito)" as BOM1 #FFEBEE component "Maven Central" as MC #FFF3E0 BG --> RESOLVED : "BOM Testcontainers 2.0.5 pasa directamente" RS -> DJ : "fuerza 3.7.1" RS -> TC : "fuerza 2.0.5" RESOLVED --> MC : "descarga los JARs compatibles Docker 29" BOM1 -[#gray,dashed]-> RESOLVED : "ignorado en testcontainers\net docker-java" note bottom of RS Le `eachDependency` intercepte la résolution Gradle AVANT que le BOM Spring Boot ne gagne. C'est une intervention chirurgicale. end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Corrección final</strong>en`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.7.1") } if (details.requested.group == "org.testcontainers" && details.requested.name == "testcontainers") { details.useVersion("2.0.5") } } } } dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers" // ... autres dépendances Spring Boot }</code></pre> </div> </div> <div class="paragraph"> <p>Le `resolutionStrategy.eachDependency`es el único modo de sobrepasar el BOM`spring-boot-dependencies`gestionado por el plugin Spring Boot. La prueba de igualdad sobre`details.requested.name == "testcontainers"`es voluntariamente restrictivo: solo forzamos el módulo core. Los módulos`testcontainers-*`siguen el BOM de Testcontainers 2.0.5 que hemos declarado explícitamente.</p> </div> </div> </div> <div class="sect1"> <h2 id="_resultado_final">Resultado final</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon > Task :consoleLauncherTest [2 containers found] [2 containers started] [2 containers successful] BUILD SUCCESSFUL in 1m 16s</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers 2.0.5 + docker-java 3.7.1 finalmente logran crear sus contenedores PostgreSQL mediante Docker Engine 29.4.1. El error de negocio final (HTTP 500 en la prueba Cucumber) es un problema de aplicación completamente independiente del script de compilación.</p> </div> </div> </div> <div class="sect1"> <h2 id="_resumen_de_correcciones">Resumen de correcciones</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Archivo</th> <th class="tableblock halign-left valign-top">Problema</th> <th class="tableblock halign-left valign-top">Corrección</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variable`reportsDir`inexistente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>outputs.dir(cucumberReportsDir)</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`main`obsoleto Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mainClass</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sourceCompatibility`top-level prohibido Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bloque`java { sourceCompatibility = JavaVersion.VERSION_21 }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aserción Groovy sintácticamente inválida</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assert …​ in ["17", "21", "23", "24"]</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dependencia implícita`compileKotlin` → <code>openApiGenerate</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>afterEvaluate { tasks.named("compileKotlin").dependsOn("openApiGenerate") }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle.properties</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`gitPropertiesPluginVersion`incompatible Java 21</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>2.5.7</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Caché Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 probado, resuelto pero insuficiente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Purga + paso docker-java 3.7.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Testcontainers 1.20.6 incompatible con Docker Engine 29</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Forzamiento Testcontainers 2.0.5 + prefijo`testcontainers-*`+ resoluciónStrategy frente a Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si tu build JHipster/Gradle falla después de una actualización a Gradle 9 + Docker Engine 29, los errores se dividen en dos categorías :</p> </div> <div class="paragraph"> <p><strong>Errores de script de construcción</strong>(las 6 primeras): Gradle 9 elimina propiedades y sintaxis que funcionaban desde hace años (<code>sourceCompatibility=</code>, <code>main =</code>, <code>reportsDir</code>). Son migraciones mecánicas una vez que se conoce la nueva API.</p> </div> <div class="paragraph"> <p><strong>Errores de tiempo de ejecución Docker</strong>(las 2 últimas): Docker Engine 29.4.1 descarta los clientes API < 1.40. Testcontainers 1.20.6 (impuesto por Spring Boot 3.4.5) utiliza docker-java 3.4.1 que envía 1.32. Solo Testcontainers 2.0.5 + docker-java 3.7.1 resuelve el problema, con el renombrado de los artefactos y el forzado de la versión via`resolutionStrategy.eachDependency`como única forma de evitar el BOM implícito de Spring Boot.</p> </div> <div class="paragraph"> <p>El script de build de Gradle en la raíz del proyecto ahora está limpio.`./gradlew build`pasa a Java 21, Gradle 9.4.1, Spring Boot 3.4.5 y Docker Engine 29.4.1.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html Fri, 24 Apr 2026 00:00:00 +0000 blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html <div class="sect1"> <h2 id="_resumen">resumen</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando se trabaja con un agente de IA como Opencode en proyectos complejos en varias sesiones, nos enfrentamos a un problema fundamental :<strong>la fuga de contexto</strong>. El agente no recuerda la sesión anterior. Todo lo que le han explicado — la arquitectura, las convenciones, el estado del backlog — se ha perdido. Reconstruir este contexto en cada sesión es costoso, lento y fuente de error.</p> </div> <div class="paragraph"> <p>Este artículo expone la estrategia artesanal que he construido para resolver este problema: un sistema de gobernanza persistente basado en archivos AsciiDoc, con una dicotomía<strong>Ansioso/Perezoso</strong>para optimizar el consumo del token de contexto, y una<strong>procedimiento de fin de sesión imprescindible</strong>para asegurar la continuidad.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_lunes_21_de_abril_900">La Escena : Lunes 21 de abril, 9:00</h2> <div class="sectionbody"> <div class="paragraph"> <p>Vuelvo a abrir Opencode para retomar mi plugin Gradle`plantuml-plugin`. Anoche pasé tres horas discutiendo con el agente de la arquitectura del pool de claves API — rotación round-robin, gestión de cuotas, fallback automático. Esta mañana, el agente me mira con ojos de pez rojo.</p> </div> <div class="paragraph"> <p></think> <em><em>_ — ¡Hola, soy su asistente Opencode. ¿Cómo puedo ayudarle hoy? </em>_</em></p> </div> <div class="paragraph"> <p>No — Ah sí, el pool de claves API, estábamos en la estructura YAML. No — Atención,<code>PlantumlManager`es un objeto singleton de Kotlin, no una clase. No — No, hemos decidido ayer que`SyntaxValidationResult`quedaba una clase sealed anidada en`PlantumlService</code>.</p> </div> <div class="paragraph"> <p>Todo está por rehacer. O mejor dicho: todo está por volver a explicar. Voy a pasar los veinte primeros minutos de mi sesión reconstituyendo un contexto que el agente ya tuvo entre sus manos ayer. Veinte minutos de tokens quemados. Veinte minutos en los que podría codificar, pero en los que hago una tarea pedagógica obligatoria.</p> </div> <div class="paragraph"> <p>No es un error de Opencode. Es la propia naturaleza de los LLM conversacionales: entre dos sesiones, la memoria de trabajo está<strong>totalmente borrada</strong>. El agente no recuerda la misión anterior, las decisiones tomadas, las trampas identificadas, el código que escribimos juntos.</p> </div> <div class="paragraph"> <p>He vivido eso decenas de veces. En cuatro proyectos simultáneos. Con sesiones que se encadenan durante semanas. He calculado: en promedio,<strong>Del 30 al 40 % del tiempo de la sesión</strong>estaba dedicado a recontextualizar al agente. En la sesión 87 del proyecto`plantuml-plugin`, me rompí. Ya no podía permitirme volver a explicar por décima vez que`AttemptEntry`es una clase de datos de nivel superior en`DiagramProcessor.kt`.</p> </div> <div class="paragraph"> <p>Necesitaba un sistema. No un hack. Una verdadera gobernanza.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_génesis_del_caos_al_método">La Génesis: Del Caos al Método</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_las_primeras_sesiones_la_edad_de_las_tinieblas">Las Primeras Sesiones : La Edad de las Tinieblas</h3> <div class="paragraph"> <p>Mi primer proyecto con Opencode,<code>plantuml-plugin</code>, empezó sin ninguna gobernanza. Hago una pregunta, el agente responde, iteramos, la sesión termina, y al día siguiente empezamos de cero. Era la sesión 1, luego la 2, luego la 3…​ hasta la sesión 62 donde me doy cuenta de que he perdido horas acumuladas volviendo a explicar la misma arquitectura.</p> </div> <div class="paragraph"> <p>En la sesión 62, los datos están aquí :<strong>198 pruebas unitarias pasan</strong>, <strong>42 pruebas funcionales validadas</strong>, el plugin funciona. Pero el costo cognitivo es insoportable. Cada nueva sesión comienza con un monólogo de veinte minutos sobre la estructura del proyecto.</p> </div> </div> <div class="sect2"> <h3 id="_el_episodio_del_sitio_yml_destruido_sesión_2_bakery_plugin">El episodio del sitio.yml Destruido (Sesión 2, bakery-plugin)</h3> <div class="paragraph"> <p>El método también nace de una catástrofe. Sobre el proyecto`bakery-gradle`, en la sesión 2, pido al agente que modifique el archivo`site.yml`. El agente, sin comprobar si el archivo está versionado, hace un`Write`completo que sobrescribe el contenido. Resultado: los tokens reales (claves de API Firebase, secretos de despliegue) son reemplazados por placeholders ficticios. El archivo no estaba en git — estaba en`.gitignore`para proteger los secretos.</p> </div> <div class="paragraph"> <p>Sin copia de seguridad. Sin`git restore`posible. Estoy bloqueado. Necesito reconstruir manualmente el archivo de configuración, encontrar los tokens en mis gestores de contraseñas, volver a pegar todo.</p> </div> <div class="paragraph"> <p>Es de esta frustración que nace la<strong>Regla Absoluta 1b</strong> :</p> </div> <div class="paragraph"> <p><em><em>_ <strong>NUNCA aplastar</strong>un archivo config con un`Write`completo cuando uno`Edit`un parcial basta.<strong>NUNCA reemplazar</strong>valores sensibles por valores ficticios.<strong>Verificar <code>git check-ignore</code> y `git ls-files</strong>antes de cualquier modificación. </em>_</em></p> </div> <div class="paragraph"> <p>Esta regla, hoy grabada en el mármol de todos mis archivos`AGENT.adoc` et `INDEX.adoc`de cuatro proyectos, nació de un error real que me costó una hora de trabajo manual.</p> </div> </div> <div class="sect2"> <h3 id="_la_migración_markdown_asciidoc_sesión_1_cheroliv_com">La Migración Markdown → AsciiDoc (Sesión 1, cheroliv.com)</h3> <div class="paragraph"> <p>El 25 de abril de 2026, sobre`cheroliv.com`, tomo una decisión radical: convertir la totalidad de la gobernanza de Markdown a AsciiDoc. No es estético. Es funcional. AsciiDoc ofrece una estructura semántica que los LLM leen mejor: secciones jerárquicas, tablas tipadas, admoniciones (<code>NOTE</code>, <code>WARNING</code>, <code>CAUTION</code>), atributos de documento legibles por la máquina.</p> </div> <div class="paragraph"> <p>La sesión 1 de`cheroliv.com`Formaliza la estructura :</p> </div> <div class="ulist"> <ul> <li> <p>Conversión de`AGENTS.md` en <code>AGENT.adoc</code></p> </li> <li> <p>Creación de los agentes especializados :`CODER.adoc`, <code>SCRUM_MASTER.adoc</code>, <code>PLANTUML_DESIGNER.adoc</code></p> </li> <li> <p>Creación de la estructura Eager/Lazy :`INDEX.adoc`, <code>SESSIONS_HISTORY.adoc</code>, <code>AGENT_SESSION_MANAGER.adoc</code>, <code>SESSION_CHECKLIST.adoc</code>, <code>PROCEDURES.adoc</code></p> </li> </ul> </div> <div class="paragraph"> <p>Un solo commit:`90975e9 refactor: migrate agent governance from Markdown to AsciiDoc`. Y el sitio sigue funcionando.</p> </div> <div id="diag-timeline" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 18) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false title Evolución de las Sesiones — Desde la Sesión 1 hasta 150+ legend top |= Couleur |= Projet | | <#4CAF50> | cheroliv.com | | <#2196F3> | plantuml-plugin | | <#FF9800> | bakery-plugin | | <#9C27B0> | magic-stick | endlegend concise "Sesiones Activas" as S @S 0 is ".md bruto" 1 is "Migración ^^^^^ Syntax Error? (Assumed diagram type: timing) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false title Evolución de las Sesiones — Desde la Sesión 1 hasta 150+ legend top |= Couleur |= Projet | | <#4CAF50> | cheroliv.com | | <#2196F3> | plantuml-plugin | | <#FF9800> | bakery-plugin | | <#9C27B0> | magic-stick | endlegend concise "Sesiones Activas" as S @S 0 is ".md bruto" 1 is "Migración AsciiDoc" 10 is "Eager/Lazy\nformalizado" 62 is "Regla seguridad\n(site.yml)" 87 is "Cracking\ncontexto" 109 is "Optimización -60% tokens" 133 is "133 sesiones\n240 pruebas PASS" S@0 -> S@1 : Session 1\n(cheroliv.com) S@1 -> S@10 S@10 -> S@62 : Session 62\n(plantuml-plugin) S@62 -> S@87 : Session 87\n(Cry 4 help) S@87 -> S@109 : Session 109\n(API Key Pool) S@109 -> S@133 : Session 133\n(Aujourd'hui) @enduml</pre> </div> </div> <div class="paragraph"> <p>La línea de tiempo anterior ilustra la progresión real. El punto de inflexión es la sesión 87: ahí es donde la frustración de la recontextualización repetida supera el umbral de tolerancia, y el método Eager/Lazy deja de ser una idea para convertirse en una obligación.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_estrategia_eagerlazy_en_profundidad">La estrategia : Eager/Lazy en profundidad</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_filosofía_caché_informático_aplicado_a_la_cognición">Filosofía : Caché informático aplicado a la cognición</h3> <div class="paragraph"> <p>Mi enfoque se inspira directamente de la gestión de caché informática. Todo lo que es<strong>crítico y frecuentemente utilizado</strong>debe ser inmediatamente accesible<strong>ansioso</strong>). Todo lo que es<strong>contextual o voluminoso</strong>debe cargarse bajo demanda (<strong>Perezoso</strong>)</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Eager (Panel de control)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lazy (manual del propietario)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Talla</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">< 100 líneas, < 10k tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ilimitado, detallado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cargando</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto, al inicio de la sesión</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A solicitud del agente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Contenido</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reglas absolutas, misión corriente, estado crítico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivos de sesiones, historial completo, procedimientos detallados, referencias técnicas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Rol</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Orientar inmediatamente al agente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Responder a las preguntas de contexto profundo</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_los_archivos_eager_el_panel_de_control">Los Archivos Eager: El Panel de Control</h3> <div class="paragraph"> <p>Estos archivos viven en la raíz de cada proyecto y son cargados automáticamente por el agente al inicio de cada sesión. Forman el<strong>tablero</strong>-- información crítica, inmediatamente accesible.</p> </div> <div id="diag-eager-lazy" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 15) ] @startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 package "Raíz del Proyecto (Eager - Auto-cargado)" { component "<b>AGENT.adoc</b>\nReglas absolutas\nEstructura & Convenciones" as AGENT component "<b>PROMPT_REPRISE.adoc</b>\nMisión de la sesión N\nResumen N-1" as PROMPT component "<b>INDEX.adoc</b>\nPunto de entrada\nReglas + Sesiones" as INDEX component "<b>*_ESSENTIALS.adoc</b>\nContexto de negocio\ncrítico" as ESS } package ".agents/ (Lazy - cargado bajo demanda)" { component "<b>sessions/N-*.adoc</b>\nArchivos detallados\nDecisiones & Output" as SESS component "<b>SESSIONS_HISTORY.adoc</b>\nResumen\nDate/Type/Score" as HIST component "<b>PROCEDURES.adoc</b> ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 package "Raíz del Proyecto (Eager - Auto-cargado)" { component "<b>AGENT.adoc</b>\nReglas absolutas\nEstructura & Convenciones" as AGENT component "<b>PROMPT_REPRISE.adoc</b>\nMisión de la sesión N\nResumen N-1" as PROMPT component "<b>INDEX.adoc</b>\nPunto de entrada\nReglas + Sesiones" as INDEX component "<b>*_ESSENTIALS.adoc</b>\nContexto de negocio\ncrítico" as ESS } package ".agents/ (Lazy - cargado bajo demanda)" { component "<b>sessions/N-*.adoc</b>\nArchivos detallados\nDecisiones & Output" as SESS component "<b>SESSIONS_HISTORY.adoc</b>\nResumen\nDate/Type/Score" as HIST component "<b>PROCEDURES.adoc</b> Plantillas fin de sesión 6 pasos" as PROC component "<b>*_REFERENCE.adoc</b>\nArquitectura completa\nReferencias técnicas" as REF component "<b>COMPLETED_TASKS_ARCHIVE</b>\nTareas completadas\nPor mes" as ARCH component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nDocumentación de estrategia\nMetodología" as MOD component "<b>*_REFERENCE.adoc</b> Boot tests, A/B partition Contextos específicos" as SPEC } AGENT --> PROMPT : "Referencias" AGENT --> INDEX : "Referencias" INDEX --> SESS : "Indexa" INDEX --> HIST : "Indexa" INDEX --> PROC : "Referencia" INDEX --> ARCH : "Referencia" INDEX --> REF : "Referencia" PROMPT --> SESS : "archivo N-1" PROMPT --> ESS : "Contexto de negocio" @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>AGENT.adoc</strong>-- El archivo maestro. Sobre`cheroliv.com`, tiene 200 líneas y contiene :</p> </div> <div class="ulist"> <ul> <li> <p>Las reglas absolutas del proyecto (no commit sin permiso, no`rm`sin confirmación)</p> </li> <li> <p>La estructura del proyecto y las convenciones de código</p> </li> <li> <p>Los comandos esenciales (<code>./gradlew serve</code>, <code>./gradlew test</code>)</p> </li> <li> <p>Las épicas y el backlog del producto (historias de usuario priorisées)</p> </li> <li> <p>Los criterios de calidad transversales (accesibilidad, responsive, compatibilidad)</p> </li> </ul> </div> <div class="paragraph"> <p>sobre`bakery-plugin`, la Regla 0 es diferente:<strong>./gradlew -q publishToMavenLocal` obligatorio después de cada modificación del código fuente</strong>. Porque probar el plugin sin volver a publicar el JAR local me hizo perder una hora depurando un código que aún no estaba empaquetado.</p> </div> <div class="paragraph"> <p><strong>PROMPT_REPRISE.adoc</strong>-- La misión de la sesión en curso. Actualizado al final de cada sesión, contiene :</p> </div> <div class="ulist"> <ul> <li> <p>El número de sesión y la misión prioritaria</p> </li> <li> <p>El resumen de la sesión anterior (lo que se ha hecho, lo que queda por hacer)</p> </li> <li> <p>Los criterios de aceptación de la sesión actual</p> </li> <li> <p>Los recordatorios técnicos específicos</p> </li> </ul> </div> <div class="paragraph"> <p><strong>.agents/INDEX.adoc</strong>El punto de entrada. Resumen las reglas absolutas, las sesiones recientes, y sobre todo el<strong>cartera de proyectos</strong>gestionados con la misma metodología. A día de hoy, cinco proyectos aparecen allí:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- | magic-stick | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 | | bakery-gradle | Session 11 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | cheroliv.com | Session 9 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS | 2026-04-23 | | jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 | ---- Por favor, proporcione el texto que desea traducir del francés al español.`*_ESSENTIALS.adoc`** -- Un añadido reciente (Sesión 109, plantuml-plugin) para optimizar aún más el contexto Eager. En lugar de cargar 200 líneas de contexto empresarial en el grupo de claves API, cargo 50 líneas de lo esencial, y las otras 150 líneas permanecen en LAZY en`*_REFERENCE.adoc`. Resultado medido: paso de**~25k tokens EAGER a ~10k tokens**(ganancia del 60%). El agente ya no necesita recordatorios que consumen energía. ==== El Eslabón Perdido : `opencode.json Debo confesarles una cosa que casi olvidé documentar. Por encima de todos estos archivos .adoc, hay un pequeño archivo JSON sin el cual nada funciona. Se llama`opencode.json`y hace seis líneas. Literalmente seis líneas. [source,json] ---- { "$schema": "https://opencode.ai/config.json", "instructions": [ "AGENT.adoc" ] } ---- Este es el archivo que le dice a Opencode: «Al iniciar, carga`AGENT.adoc`automáticamente. » Sin él, el agente es una página en blanco exactamente como lo describía al inicio del artículo. Con él, el agente ya tiene entre las manos las reglas absolutas, la arquitectura del proyecto y los comandos esenciales — antes incluso de que yo diga hola. Descubrí por casualidad la importancia de este archivo. Sobre`bakery-plugin`, no existía. Me preguntaba por qué el agente estaba sistemáticamente más « perdido » en este proyecto que en los otros. Las reglas absolutas estaban bien dentro de`AGENT.adoc`— pero`AGENT.adoc`nunca estaba cargado. El agente solo leía lo que yo le decía que lea, manualmente, en cada sesión. Era la sesión 11 de`bakery-plugin`cuando me di cuenta de la ausencia del`opencode.json`. Lo creé — y la sesión 12 comenzó como las demás. Este archivo es tan obvio para mí ahora que ni siquiera lo tenía en cuenta. Un error clásico del desarrollador que conoce demasiado su herramienta. Hoy, lo creo sistemáticamente *antes*`AGENT.adoc`. Es la primera piedra. ==== La dualidad de `INDEX.adoc Otra sutileza que merece ser explicitada :`INDEX.adoc`vive en`.agents/`— una carpeta que he presentado como `LAZY`. Sin embargo, la enumero como `EAGER` en todas mis tablas. Hay una tensión aparente aquí. La realidad de campo: los archivos`.agents/INDEX.adoc`están bien cargados automáticamente al inicio de la sesión, al mismo nivel que`AGENT.adoc` et `PROMPT_REPRISE.adoc`Ellos están en`.agents/`Por razones de organización — no invadir la raíz — pero su comportamiento es EAGER. sobre`plantuml-plugin`, `INDEX.adoc`tiene 200 líneas y contiene las reglas absolutas *completas* con su historial (las lecciones de las sesiones pasadas), los EPICs con puntuaciones, y el portafolio de proyectos. Es el documento que el agente consulta para saber « dónde estamos». Sobre`bakery-plugin`, hace 150 líneas con la hoja de ruta y las sesiones recientes. La redundancia voluntaria entre`AGENT.adoc` et `INDEX.adoc`Puede sorprender. Las reglas absolutas están presentes en ambos. ¿Por qué? Porque cumplen dos funciones diferentes: en`AGENT.adoc`, son *explicativas* (el storytelling de la regla, la lección aprendida); en`INDEX.adoc`, ellas son *ejecutivas*(la regla desnuda, sin justificación, para una consulta rápida). El agente lee`AGENT.adoc`una vez para *comprender* ; él vuelve a leer`INDEX.adoc`à cada sesión para *aplicar*. Dos usos, dos formatos. [plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Dualidad AGENT.adoc ←→ INDEX.adoc left to right direction rectangle "AGENT.adoc\n(Raíz — EAGER)" as AGENT #E3F2FD { rectangle "📖 **Formato Narrativo** El storytelling de la regla la lección aprendida, el contexto" as NARR rectangle "�🏗️ **Arquitectura Completa**\nEstructura del proyecto, componentes\nBacklog detallado US" as ARCHI rectangle "📋 **Reglas Explicatives** ¿Por qué existe la regla? Historial del incidente" as EXPL } rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 { rectangle "�⚡ **Formato Ejecutivo** La regla desnuda, sin justificación Consulta rápida" as EXEC rectangle "📊 **Roadmap & EPICs**\nTabla resumen\nProgreso, Puntuación, Prioridad" as ROAD rectangle "�🌐 **Portafolio de proyectos** Visión transversal 5 proyectos sincronizados" as PORT } AGENT --> INDEX : "Agent lee AGENT.adoc 1 vez para **comprender**" INDEX --> AGENT : "Agent vuelve a leer INDEX.adoc\nCada sesión para **aplicar**" note bottom of AGENT Taille max : 200 lignes end note note bottom of INDEX Taille max : 200 lignes Source de vérité en cas de divergence end note @enduml ---- Esta redundancia asumida es una elección de diseño. Consume ~50 líneas adicionales de tokens EAGER — pero garantiza que el agente siempre tenga las reglas a la vista, incluso en el formato conciso que facilita la obediencia inmediata. === Los Archivos LAZY: El Manual del Propietario Estos archivos viven en`.agents/`y solo se leen cuando el agente los necesita. Constituyen la verdadera riqueza del método, porque acumulan el conocimiento del proyecto sin contaminar el contexto actual. [plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"] ---- @startuml skinparam folderBackgroundColor #E3F2FD skinparam folderBorderColor #1565C0 skinparam fileBackgroundColor #FFF3E0 skinparam fileBorderColor #EF6C00 folder ".agents/" as ROOT { file "INDEX.adoc (EAGER -- 200 líneas)" as IDX #E8F5E9 file "AGENT_SESSION_MANAGER.adoc (Sesión de plantilla)" as ASM file "SESSION_CHECKLIST.adoc (¿Cuándo cambiar?)" as CHK file "PROCEDURES.adoc\n(6 pasos + LAZY/EAGER)" as PRO file "SESSIONS_HISTORY.adoc\n(Toutes sessions)" as HIS folder "sesiones/" as SESS { file "1-chore-migration.adoc" as S1 file "109-formalización-lazy.adoc" as S109 #FFECB3 file "133-epic11-article.adoc" as S133 file "... +130 otros" as SMORE } folder "archivos/" as ARCH { file "COMPLETED_TASKS_2026-04.adoc" as CTA file "SESSIONS_HISTORY_83-95.adoc" as SHIST folder "sessions_resúmenes/" as SUM { file "SESSION_64_SUMMARY.adoc" as SU64 file "SESSION_73_SUMMARY.adoc" as SU73 file "..." as SUMORE } folder "prompts_archive/" as PARCH { file "PROMPT_REPRISE_S65.adoc" as PR65 file "PROMPT_REPRISE_S75.adoc" as PR75 file "..." as PMORE } } } IDX --> SESS : "Índice" IDX --> HIS : "Índice" IDX --> ARCH : "Referencia" note right of S109 Session 109 = Formalisation stratégie LAZY/EAGER Token : ~25k → ~10k end note @enduml ---- El árbol anterior muestra la estructura real de la carpeta`.agents/`sobre`plantuml-plugin`, el proyecto más maduro. Observe la profundidad en tres capas: archivos raíz (metadatos), carpeta`sessions/`(archivos cronológicos), y expediente`archives/`(agregaciones y resúmenes). Es esta profundidad la que transforma la gobernanza de un simple archivo TODO en una**memoria organizacional completa**. **.agents/sessions/{N}-{título}.adoc**Los archivos detallados de cada sesión. Actualmente : * `plantuml-plugin`:**133 sesiones archivadas**(de la sesión 1 al 133) * `bakery-plugin`:**11 sesiones** * `magic-stick` : **23 sesiones** * `cheroliv.com`:**9 sesiones formales**+ 7 sesiones pre-sistema reconstituidas retroactivamente Cada archivo contiene el contexto completo de la sesión, las decisiones tomadas, los problemas encontrados y su resolución, los comandos ejecutados y su salida. **.agents/SESSIONS_HISTORY.adoc**-- Un cuadro resumen de todas las sesiones con una puntuación. Ejemplo sobre`cheroliv.com`: ---- | -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 | 1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 | 7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 | 8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10 **.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc**-- Las tareas completadas archivadas por mes, para no sobrecargar el backlog activo. Cuando una historia de usuario está completa, se mueve aquí. El backlog sigue siendo legible: máximo 10 ítems activos. **.agents/PROCEDURES.adoc**-- Plantillas detalladas del procedimiento de fin de sesión. Larga, pero leída una sola vez por el agente cuando aprende el método. Luego, el procedimiento se vuelve mecánico. **.agents/AGENT_MODUS_OPERANDI.adoc**-- La documentación estratégica completa. Sobre`plantuml-plugin`, este archivo hace**900+ líneas**y se llama en realidad`AGENT_METHODOLOGIES.adoc`— cambié el nombre entre la redacción de este artículo y su implementación efectiva. Este tipo de divergencia de naming es inevitable en un sistema artesanal que evoluciona. Lo importante es la convención de nomenclatura: si el archivo documenta la *méthode*, comienza por`AGENT_`o un prefijo explícito. Documenta la metodología Eager/Lazy, los patrones a seguir, los anti-patrones a evitar. Es LAZY porque un agente no necesita volver a leer toda la estrategia en cada sesión, solo cuando hay ambigüedad. **`*_REFERENCE.adoc`** -- Las referencias técnicas específicas del proyecto. Sobre`magic-stick`, dos archivos LAZY densos : * `AB_PARTITION_REFERENCE.adoc`(147 líneas) -- Arquitectura de partición A/B GPT, scripts`update-system.sh`, tamaños estimados, mecanismo de rollback * `BOOT_TEST_REFERENCE.adoc`(144 líneas) -- Procedimiento QEMU + VNC para probar el arranque de la ISO sin hardware físico, lista de verificación BIOS/UEFI, limitaciones CI/CD Sobre`plantuml-plugin`</think> </think> * `ARCHITECTURE.adoc`(134 líneas) -- Estructura de las 11 clases de datos, puntos de atención (trampas a evitar), comandos de prueba optimizados * `API_KEY_POOL_REFERENCE.adoc`-- Detalles completos del pool de claves (LAZY mientras que`ESSENTIALS`está EAGER) == Los Agentes Especializados : Un Equipo Virtual La gobernanza no se limita a archivos pasivos. He formalizado de**roles de agentes especializados**en archivos LAZY dedicados, que definen el flujo de trabajo esperado según el tipo de tarea. |=== |agente |Archivo |rol |Proyecto |**CODIFICAR** |`CODER.adoc` |Implementación FTL/CSS/JS, etiquetas semánticas, criterios de accesibilidad |cheroliv.com |**Maestro SCRUM** |`SCRUM_MASTER.adoc` |Planificación EE. UU., desglose en sub-tareas, detección de dependencias |cheroliv.com |**PlantUML Diseñador** |`PLANTUML_DESIGNER.adoc` |Creación de diagramas, sintaxis PUML, integración JBake |cheroliv.com |=== El archivo`CODER.adoc`sobre`cheroliv.com`contiene reglas concretas : _Un solo`<h1>`por página_, _Prefijar los caminos con`${content.rootpath}`_, _Declarar el idioma`<html lang="${content.lang!"fr"}">`_. Estas convenciones, escritas una vez, se respetan automáticamente por el agente desde la sesión 1. El archivo`SCRUM_MASTER.adoc`impone una estructura de entregable:**Objetivo**, **Tareas**(coordenadas con asignación)**Criterios de aceptación**, **Riesgos**. Cuando pido un plan de acción, el agente produce esta estructura sin que yo se la haya pedido. La gobernanza**programa**el agente. ==== Cuando los agentes especializados se vuelven indispensables La creación de los agentes especializados sigue una curva natural. Al comienzo de un proyecto, no los necesitas —`AGENT.adoc`basta ampliamente. Pero cuando el proyecto crezca (digamos, más de 20 sesiones), dos señales deben alertarle: 1. El agente mezcla las convenciones de dos dominios distintos (ej: sintaxis PlantUML y reglas CSS) 2. Pasas más tiempo corrigiendo al agente sobre convenciones que ya le has explicado 5 veces Sobre`cheroliv.com`, llegó a la sesión... 1. Sí, desde el principio. Porque este proyecto es un sitio web con tres lenguajes (FTL, CSS, JS), contenido AsciiDoc, y diagramas PlantUML — tres áreas que no tienen nada que ver. El agente CODER necesita conocer los tamaños de fuente y las media queries; el agente PLANTUML_DESIGNER necesita conocer la sintaxis`@startuml`. Sin separación, el agente CODER me proponía diagramas, y viceversa. El caos. Sobre`jhipster-gradle-plugins`, he creado dos agentes especializados adaptados al desarrollo de plugins Gradle :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. El primero codifica todas las convenciones Kotlin/Gradle (no`!!`, clases de datos para los modelos,`@TaskAction`para las tareas). El segundo sabe que`persistence`debe ser estable antes de que`assistant`no comienza su desarrollo — una dependencia crítica en un mono-repo. El error que no se debe cometer : crear demasiados agentes demasiado temprano`plantuml-plugin`Esperó la sesión 108 antes de formalizar un agente especializado para el conjunto de claves API. Antes de eso, el contexto del negocio se encontraba en`AGENT.adoc`. La regla empírica: un agente especializado se justifica cuando su dominio de negocio supera las 100 líneas de documentación. ==== Convención de Nomenclatura de Sesiones Un detalle que parece fútil pero que se vuelve crítico cuando se alcanzan 100 sesiones. ¿Cómo nombrar los archivos de archivo? He aprendido a mis expensas que una convención es necesaria — cuatro proyectos, cuatro formatos diferentes al principio, y ya no sabía orientarme. Hoy, la convención que he estabilizado es :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> <div class="paragraph"> <p>{N}-{type}-{sujet-kebab-case}.adoc</p> </div> <div class="listingblock"> <div class="content"> <pre>Ejemplos concretos: * `1-chore-migration-gouvernance-agent.adoc`— sesión 1, tipo tarea * `10-solidification-tests.adoc`— sesión 10, sin tipo explícito (el sujeto basta) * `036-debug-graphify-symlink-epic9.adoc`— sesión 36 con número de 3 dígitos para la ordenación El número de sesión es el criterio de ordenación principal. Los proyectos que utilizan números de tres cifras (001, 036, 133) evitan los problemas de ordenación lexicográfica cuando se supera 99. Esto es lo que ahora utilizo en`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`. El tipo es opcional y se deriva de las palabras clave de la sesión (debug, feature, refactor, docs, chore, test). El asunto en kebab-case es la parte más importante: debe permitir recuperar una sesión sin abrir el archivo. Si te preguntas « ¿cuál fue la sesión en la que se corrigió el timeout de las pruebas de integración? », la respuesta es`124-fix-timeout-integration-test.adoc`. Para las sesiones históricas reconstituidas (proyectos nacidos antes de la gobernanza), utilizo números negativos. Sobre`cheroliv.com`, las sesiones -6 a 0 cubren todo el historial pre-gobernanza del proyecto. Y para las sesiones « no documentadas » o perdidas, creo una entrada en`SESSIONS_HISTORY.adoc`sin archivo correspondiente, con una puntuación`?`. Es más honesto que fingir. [plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200</p> </div> <div class="paragraph"> <p>title Convención de Nomenclatura de Sesiones start</p> </div> <div class="paragraph"> <p>:Une session se termine; note right: Trigger "final de la sesión"</p> </div> <div class="paragraph"> <p>if (Session antérieure\nà la gouvernance ?) then (oui) :Numéro <strong>NÉGATIF</strong>\n-6, -5 …​ 0; note right: Historique\nreconstitué :Suffixe : reconstitution; else (non) :Numéro <strong>POSITIF</strong>\nsur 3 chiffres si > 99; note right: 001, 036, 133\npour le tri lexicographique</p> </div> <div class="literalblock"> <div class="content"> <pre>:Détecter le **TYPE**; if (Mots-clés trouvés ?) then (oui) :debug / feature / refactor\ndocs / chore / test; else (non) :Omettre le type\n(le sujet suffit); endif</pre> </div> </div> <div class="literalblock"> <div class="content"> <pre> :Formuler le **SUJET** en kebab-case; note right Ex: fix-timeout-integration-test Doit permettre de retrouver sans ouvrir le fichier end note endif</pre> </div> </div> <div class="paragraph"> <p>note right • 1-chore-migration-gouvernance.adoc • 036-debug-graphify-symlink.adoc • 124-fix-timeout-integration-test.adoc • 133-epic11-article-blog-kg.adoc end note</p> </div> <div class="paragraph"> <p>if (Session documentée ?) then (oui) :Créer archive dans sessions/; :Ajouter ligne SESSIONS_HISTORY\navec score X/10; else (non) :Ajouter ligne SESSIONS_HISTORY\navec score <strong>?</strong>\n<strong>sans archive</strong>; note right: L’honnêteté\nplutôt que le vide endif</p> </div> <div class="paragraph"> <p>stop @enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>==== TEST_COVERAGE_ANALYSIS.adoc` — El Paso 5 Detallado El paso 5 del procedimiento de fin de sesión es el más misterioso. Dice « Actualizar`TEST_COVERAGE_ANALYSIS.adoc`si se han añadido o modificado las pruebas. » Pero, ¿qué aspecto tiene este archivo? sobre`plantuml-plugin`, ha evolucionado de unas pocas líneas a una estructura completa. Aquí está su forma estabilizada: [source]</pre> </div> </div> </div> </div> </div> <h1 id="_analyse_de_couverture_de_tests" class="sect0">Analyse de Couverture de Tests</h1> <div class="sect1"> <h2 id="_suivi_des_tests">Suivi des Tests</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Classe de test</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tests</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Statut</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dernière MAJ</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PlantumlServiceTest</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">unit</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">45/45</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ PASS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-23</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ApiKeyPoolTest</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">integration</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15/15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ PASS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-20</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_historique_par_session">Historique par Session</h2> <div class="sectionbody"> <div class="paragraph"> <p>| Session | Tests ajoutés | Tests modifiés | Couverture | 133 | 0 | 2 | 100% | 132 | 5 | 0 | 100%</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">----</p> <p class="tableblock">El interés no es el archivo en sí — es la obligación de <strong>notar</strong> lo que ha cambiado. Sin este paso, después de 50 sesiones, ya no sabes qué pruebas cubren qué. El agente tampoco. El archivo se convierte en el único repositorio de verdad sobre la cobertura de pruebas del proyecto.</p> <p class="tableblock">Para los proyectos sin pruebas tradicionales (como`magic-stick`que prueba scripts bash), el paso 5 se sustituye por`SCRIPT_VERIFICATION.adoc`. El mecanismo es el mismo: un archivo que sigue el estado de validación de los scripts. Adapta el paso 5 a tu proyecto, pero nunca lo omitas. Es la red de seguridad que evita la regresión silenciosa.</p> <p class="tableblock">Si su proyecto no tiene <strong>ninguna</strong> prueba — ni unitaria, ni funcional, ni de script — cree incluso el archivo vacío con una sección « Por hacer: definir una estrategia de prueba. » Es un marcador que le recordará a su futuro yo que este tema no está tratado.</p> <p class="tableblock">[plantuml, format=svg, id=diag-session-flow, alt="Flux d’une session type avec Eager/Lazy et agents"] ---- @startuml skinparam backgroundColor #FEFEFE</p> <p class="tableblock">start</p> <p class="tableblock">:Début session; note right: L’agent est une page blanche</p> <p class="tableblock">:Chargement EAGER auto; note right * AGENT.adoc (règles absolues) * PROMPT_REPRISE.adoc (mission N) * INDEX.adoc (état projet) end note</p> <p class="tableblock">if (Mission claire ?) then (oui) :Exécution directe; else (non) :Charge LAZY sur demande; note right * SESSIONS_HISTORY.adoc (contexte passé) * sessions/{N-1}-<strong>.adoc (décisions) * *<em>REFERENCE.adoc (architechture) end note endif</p> <p class="tableblock">:Délégation agent spécialisé ?;</p> <p class="tableblock">if (CODER ?) then (oui) :Lit CODER.adoc; :Suit conventions FTL/CSS; elseif (SCRUM Master ?) then (oui) :Lit SCRUM_MASTER.adoc; :Structure livrable imposée; elseif (PlantUML ?) then (oui) :Lit PLANTUML_DESIGNER.adoc; :Syntaxe PUML + intégration; else (non) endif</p> <p class="tableblock">:Travail de la session;</p> <p class="tableblock">:Fin de session (trigger utilisateur);</p> <p class="tableblock">:Procédure 6 étapes; note right 1. Archive sessions/N-</strong>.adoc 2. Maj PROMPT_REPRISE.adoc (N+1) 3. Maj SESSIONS_HISTORY.adoc 4. Maj INDEX.adoc 5. Maj TEST_COVERAGE (si applicable) 6. Maj COMPLETED_TASKS_ARCHIVE.adoc end note</p> <p class="tableblock">:Checklist [✅] x 6;</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">El diagrama de arriba muestra el ciclo de vida completo de una sesión. El punto clave es la bifurcación después de la carga EAGER: ya sea la misión es suficientemente clara para ejecutar directamente (80% de los casos), o el agente carga el LAZY para resolver una ambigüedad (20% de los casos). Es esta discriminación la que ahorra los tokens.</p> <p class="tableblock">== El Procedimiento de Fin de Sesión: La Regla de Oro</p> <p class="tableblock">=== ¿Por qué es imprescindible?</p> <p class="tableblock">Sin este procedimiento, la estrategia Eager/Lazy no sirve de nada. Es ella quien transforma el trabajo de la sesión en información persistente. Se ejecuta<strong>a petición explícita del usuario</strong>(palabras clave : "fin de sesión", "me voy", etc.), y ella está<strong>obligatorio</strong>-- ninguna excepción, ninguna omisión.</p> <p class="tableblock">El archivo`SESSION_CHECKLIST.adoc`define las métricas de sesión ideal:</p> <p class="tableblock">* Duración: 15-30 minutos * Archivos modificados: 1-3 máximo * Intercambios LLM : 5-10 mensajes * Contexte tokens : < 50k</p> <p class="tableblock">Y hay signos de que hay que cambiar de sesión : _El LLM repite errores ya corregidos</em>, <em>Más de 3 archivos modificados en paralelo</em>, <em>Conversación > 50 mensajes</em>. La regla de oro :<strong>Vale más 5 sesiones de 20 minutos que una sesión de 2 horas con debugging caótico.</strong></p> <p class="tableblock">=== El flujo de los 6 pasos (Silenciosamente)</p> <p class="tableblock">[plantuml, format=svg, id=diag-end-session-flow, alt="Flux de la procédure de fin de session"] ---- @startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 skinparam activityBackgroundColor #E3F2FD</p> <p class="tableblock">start :L’utilisateur dit "fin de sesión"; note right: Mots-clés déclencheurs</p> <p class="tableblock">:Agent détecte le trigger;</p> <p class="tableblock">:Étape 1\nCréer archive\n`.agents/sessions/N-<strong>.adoc`; note right: Tout le contexte de la session</p> <p class="tableblock">:Étape 2\nMettre à jour\n`PROMPT_REPRISE.adoc`; note right: Mission N + critères d’acceptation N+1</p> <p class="tableblock">:Étape 3\nMettre à jour\n`SESSIONS_HISTORY.adoc`; note right: Ligne récap : # / Date / Type / Sujet / Score</p> <p class="tableblock">:Étape 4\nMettre à jour\n`INDEX.adoc`; note right: État courant, roadmap, fichiers modifiés</p> <p class="tableblock">:Étape 5\nMettre à jour\n`TEST_COVERAGE_ANALYSIS.adoc`; note right: Si tests ajoutés ou modifiés</p> <p class="tableblock">:Étape 6\nMettre à jour\n`COMPLETED_TASKS_ARCHIVE.adoc`; note right: Archiver tâches terminées</p> <p class="tableblock">:Afficher la checklist de confirmation; note right: Vérifier que chaque [✅] est mérité</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">=== Los Resultados de 150+ Sesiones</p> <p class="tableblock">Esto es lo que produce este procedimiento aplicado sistemáticamente en mis cuatro proyectos:</p> <p class="tableblock"><strong>plantuml-plugin</strong>:</p> <p class="tableblock">* <strong>133 sesiones</strong>desde el inicio del proyecto * <strong>240/240 pruebas aprobadas</strong>(100% cobertura) — EPICs 1-7 completados * <strong>57 escenarios Cucumber BDD</strong>validados * Regla de seguridad sobre los archivos de configuración surgida de un error real (Sesión 2 bakery-plugin)</p> <p class="tableblock"><strong>panadería-plugin</strong> :</p> <p class="tableblock">* <strong>11 sesiones</strong>en dos semanas * Migración de Supabase a Firebase completada (9 pruebas corregidas) * EPIC 6 (publishProfile) funcional en producción * Regla 0 creada :`publishToMavenLocal`obligatorio después de cada modificación</p> <p class="tableblock"><strong>palo mágico</strong> :</p> <p class="tableblock">* <strong>23 sesiones</strong>para construir un sistema live Xubuntu con partición A/B * Primera ISO generada en la sesión 10 * Pruebas de arranque QEMU + VNC formalizadas (documentación LAZY de 144 líneas) * CI/CD SourceForge funcional</p> <p class="tableblock"><strong>cheroliv.com</strong>:</p> <p class="tableblock">* <strong>9 sesiones formales</strong>+ reconstitución de 7 sesiones pre-sistema * Artículo 0101 (OpenCode PATH) publicado * Article 0108 (éste) reescrito después del análisis de sus deficiencias * Gobernanza completa migrada de Markdown a AsciiDoc</p> <p class="tableblock">=== La lista de verificación final</p> <p class="tableblock">Tras la ejecución silenciosa de los 6 pasos, el agente debe mostrar una lista de verificación de confirmación:</p> <p class="tableblock">----</p> <p class="tableblock">✅ Procédure de fin de session exécutée 📋 Checklist :</p> <p class="tableblock"><strong>Regla absoluta</strong>: ningún paso puede marcarse`[✅]<code>si el archivo no ha sido efectivamente modificado y verificado.</p> <p class="tableblock">== La Guía de Bootstrap: Día 1, Sesión 0</p> <p class="tableblock">Estás convencido del método. Quieres aplicarlo a un nuevo proyecto. ¿Por dónde empezar?</p> <p class="tableblock">Viví este momento el 28 de abril de 2026. Abro Opencode en`jhipster-gradle-plugins</code>, mi mono-repo de dos plugins Gradle JHipster. Es un proyecto que ya existe — el código está allí, las tareas Gradle funcionan. Pero el agente de gobernanza ? Cero. Página blanca. Como`plantuml-plugin`A su sesión 1, hace varios meses.</p> <p class="tableblock">Este es el procedimiento exacto que seguí, y que seguiré para todo nuevo proyecto. Tenga en cuenta el orden — es importante.</p> <p class="tableblock">[plantuml, format=svg, id=diag-bootstrap, alt="Flux de bootstrap en 6 étapes pour initialiser la gouvernance agent sur un nouveau projet"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 250 skinparam activityBackgroundColor #E8F5E9</p> <p class="tableblock">title Bootstrap Gobernanza — Día 1, Sesión 0 start :Étape 0\nCréer <strong>opencode.json</strong>\n(6 lignes, instructions: AGENT.adoc); note right: Le pont qui charge\nAGENT.adoc automatiquement</p> <p class="tableblock">:Étape 1\nCréer les dossiers\n<strong>mkdir -p .agents/sessions/ .agents/archives/</strong>; note right: Les conteneurs vides\navant que l’agent écrive dedans</p> <p class="tableblock">:Étape 2\nCréer <strong>AGENT.adoc</strong>\n(200 lignes, règles absolues); note right: Le fichier maître\nStructure minimale v1</p> <p class="tableblock">:Étape 3\nCréer <strong>PROMPT_REPRISE.adoc</strong>\nMission session 1 (max 70 lignes); note right: Ce que l’agent doit\nfaire à la prochaine session</p> <p class="tableblock">:Étape 4\nCréer <strong>.agents/INDEX.adoc</strong>\nRègles exécutives + roadmap; note right: Point d’entrée EAGER\ndans le dossier LAZY</p> <p class="tableblock">:Étape 5\nCréer les fichiers LAZY structurants\n6 fichiers : SESSIONS_HISTORY, CHECKLIST, etc.; note right • SESSIONS_HISTORY.adoc • SESSION_CHECKLIST.adoc • PROCEDURES.adoc • AGENT_SESSION_MANAGER.adoc • TEST_COVERAGE_ANALYSIS.adoc • Agents spécialisés (si besoin) end note</p> <p class="tableblock">:Étape 6\nAjouter le projet au Portefeuille\nMettre à jour TOUS les INDEX.adoc existants; note right: Maintenance transverse\nObligatoire mais fastidieuse</p> <p class="tableblock">:✅ Bootstrap terminé\nSession 1 prête; note right: 20 minutes investies\nDes centaines économisées</p> <p class="tableblock">stop @enduml ----</p> <p class="tableblock">=== Paso 0 : Crear <code>opencode.json</p> <p class="tableblock">Este es el primer archivo. No`AGENT.adoc</code>, no`INDEX.adoc`.<code>opencode.json`primero, por una razón simple: si creas`AGENT.adoc`Al principio, olvidarás crear el puente que lo carga automáticamente. Lo he hecho sobre.`bakery-plugin</code>, yo sé de lo que hablo.</p> <p class="tableblock">=== Paso 1: Crear las Carpetas</p> <p class="tableblock">[source,bash] ---- mkdir -p .agents/sessions .agents/archives ----</p> <p class="tableblock">Dos carpetas vacías.<code>sessions/`recibirá los archivos de cada sesión.`archives/`recibirá los COMPLETED_TASKS_ARCHIVE mensuales. Estos directorios deben existir *avant</strong> de que el agente necesite escribir en ellos. Un agente que debe crear el directorio ET el archivo al mismo tiempo, es un agente que puede fallar silenciosamente.</p> <p class="tableblock">=== Paso 2: Crear `AGENT.adoc</code> — El Archivo Maestro</p> <p class="tableblock">Estructura mínima para la primera versión (crecerá) :</p> <p class="tableblock">[source] ---- = {NOM_PROJET} — Directives Agent</p> <p class="tableblock">[CAUTION] ----</p> <p class="tableblock"><strong>PARADA OBLIGATORIA</strong>antes de rm, Escribir, supresión :</p> <p class="tableblock">1. LEER el archivo completo 2. VERIFICAR git ls-files 3. SOLICITAR confirmación 4. ESPERAR "sí</p> <p class="tableblock">== Proyecto</p> <p class="tableblock"><strong>Nombre</strong>: …​ <strong>pila</strong>: …​ <strong>Documentación</strong>: AsciiDoc</p> <p class="tableblock">== Reglas Absolutas</p> <p class="tableblock">=== 0. ENTORNO DE DESARROLLO</p> <p class="tableblock">Comandos esenciales…​</p> <p class="tableblock">=== 1. COMMITS/GIT</p> <p class="tableblock">prohibición formal…​</p> <p class="tableblock">=== 1b. ARCHIVOS DE CONFIGURACIÓN — REGLA ABSOLUTA DE SEGURIDAD</p> <p class="tableblock">Nunca aplastar…​</p> <p class="tableblock">=== 2. EXÁMENES AL FINAL DE LA SESIÓN</p> <p class="tableblock">Prohibición formal…​</p> <p class="tableblock">=== 3. PROCEDIMIENTO DE FIN DE SESIÓN</p> <p class="tableblock">Las 6 etapas obligatorias…​</p> <p class="tableblock">== Gestión del Contexto — LAZY/EAGER</p> <p class="tableblock">Archivos EAGER / Archivos LAZY…​</p> <p class="tableblock">Esta plantilla mínima permite al agente comenzar. La versión rica — con la estructura del proyecto, los componentes clave, los EPICs, el backlog — llegará en la sesión 1, cuando el agente ya tenga las reglas básicas en mano y pueda ayudarte a enriquecer el documento.</p> <p class="tableblock">=== Paso 3 : Crear <code>PROMPT_REPRISE.adoc</code> — La Misión Sesión 1</p> <p class="tableblock">Un archivo que dice explícitamente: « Esta es la sesión 1, misión por definir. » Máximo 70 líneas, con una sección Sesión 0 (resumen del bootstrap) y una sección Sesión 1 (prioridades por definir con el usuario).</p> <p class="tableblock">=== Paso 4: Crear <code>.agents/INDEX.adoc</code> — El Punto de Entrada</p> <p class="tableblock">El archivo que contendrá las reglas absolutas (versión ejecutiva) y la tabla de sesiones. Para el bootstrap, enumera las reglas 0 a 3 en su formato conciso, el portafolio de proyectos (incluyendo el nuevo proyecto con un emoji 🆕), y la hoja de ruta vacía lista para ser completada.</p> <p class="tableblock">=== Paso 5: Crear los archivos LAZY estructurantes</p> <p class="tableblock">En orden :</p> <p class="tableblock">1. <code>.agents/SESSIONS_HISTORY.adoc</code>— una tabla con solo la sesión 0 2. <code>.agents/SESSION_CHECKLIST.adoc</code>— la plantilla « Cuándo cambiar de sesión 3. <code>.agents/PROCEDURES.adoc</code>— el procedimiento completo de los 6 pasos + EAGER/LAZY 4. <code>.agents/AGENT_SESSION_MANAGER.adoc</code>— la plantilla de archivo 5. <code>.agents/TEST_COVERAGE_ANALYSIS.adoc</code>— el cuadro de seguimiento de pruebas, vacío al inicio</p> <p class="tableblock">Si su proyecto tiene un dominio de negocio complejo (como`jhipster-gradle-plugins`con su mono-repo persistence/assistant), cree los agentes especializados ahora:</p> <p class="tableblock">1. <code>.agents/PLUGIN_DEVELOPER.adoc</code>— las convenciones de código y el límite de dependencias (si plugin) 2. <code>.agents/BACKLOG_MANAGER.adoc</code>— la estructura de planificación y los riesgos identificados</p> <p class="tableblock">No cree agentes que no vaya a utilizar. Un agente sin convenciones concretas para codificar es un archivo muerto que contamina.<code>.agents/</code>.</p> <p class="tableblock">=== Paso 6 : Agregar el Proyecto al Portafolio de TODOS los Proyectos</p> <p class="tableblock">Es el paso que olvidamos sistemáticamente. Cada`INDEX.adoc`de cada proyecto contiene una tabla « Portafolio de Proyectos » que enumera TODOS los proyectos con la misma metodología. Cuando creas un nuevo proyecto, debes:</p> <p class="tableblock">1. Añadir una línea en el portafolio del nuevo proyecto (lógico) 2. Añadir una línea en el portafolio de TODOS los proyectos existentes — sí, todos</p> <p class="tableblock">En mis cuatro (ahora cinco) proyectos, eso significa abrir los`INDEX.adoc` de <code>magic-stick</code>, <code>bakery-gradle</code>, <code>cheroliv.com</code>, `plantuml-gradle`y allí añadir la línea`jhipster-gradle-plugins</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Session 1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2026-04-28 🆕<code>. (just a period).</p> <p class="tableblock"></think></p> <p class="tableblock">.</p> <p class="tableblock">Es tedioso. Es manual. También es la única forma de garantizar que, cualquiera que sea el proyecto en el que estás trabajando, el agente sepa cuáles otros proyectos existen y cuál es su estado. En la sesión 012 de`magic-stick</code>, el agente detectó dos inconsistencias en la cartera —`bakery-gradle`tenía su COMPLETED_TASKS_ARCHIVE atrasado, y`plantuml-gradle`Tenía un desfase entre su documentación de procedimiento (5 pasos) y su ÍNDICE (6 pasos). Sin esta tabla transversal, estas incoherencias habrían permanecido invisibles.</p> <p class="tableblock">[plantuml, format=svg, id=diag-portfolio-graph, alt="Graphe du portefeuille de projets — références croisées entre INDEX.adoc"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam nodeBackgroundColor #E3F2FD</p> <p class="tableblock">title Portafolio de Proyectos — Referencias Cruzadas INDEX.adoc node "<strong>magic-stick</strong>\nSesión 037\nSCRIPT_VERIFICATION" as MS #E1BEE7 node "<strong>bakery-gradle</strong> Sesión 11 PRUEBA_COBERTURA" as BG #FFE0B2 node "<strong>cheroliv.com</strong> Sesión 10 TEST_COVERAGE" as CH #C8E6C9 node "<strong>plantuml-gradle</strong>\nSesión 133\nTEST_COVERAGE" as PG #BBDEFB node "<strong>jhipster-gradle</strong> Sesión 1 🆕 TEST_COVERAGE" as JG #FFCDD2</p> <p class="tableblock">MS -→ BG : INDEX.adoc référence MS -→ CH : INDEX.adoc référence MS -→ PG : INDEX.adoc référence MS -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">BG -→ MS : INDEX.adoc référence BG -→ CH : INDEX.adoc référence BG -→ PG : INDEX.adoc référence BG -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">CH -→ MS : INDEX.adoc référence CH -→ BG : INDEX.adoc référence CH -→ PG : INDEX.adoc référence CH -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">PG -→ MS : INDEX.adoc référence PG -→ BG : INDEX.adoc référence PG -→ CH : INDEX.adoc référence PG -→ JG : INDEX.adoc référence 🆕</p> <p class="tableblock">JG -→ MS : INDEX.adoc référence JG -→ BG : INDEX.adoc référence JG -→ CH : INDEX.adoc référence JG -→ PG : INDEX.adoc référence</p> <p class="tableblock">note bottom of JG Quand on ajoute un projet : • 4 INDEX.adoc à mettre à jour • 1 ligne par portefeuille • Coût : 5 minutes end note</p> <p class="tableblock">legend bottom</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">= Couleur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">= Projet</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#E1BEE7></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">magic-stick — ISO Linux live</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#FFE0B2></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle — Plugin JBake</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#C8E6C9></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com — Site personnel</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><#BBDEFB></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">plantuml-gradle — Plugin IA</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><#FFCDD2></p></td> </tr> </tbody> </table> </div> </div> https://cheroliv.com//blog/2026/0107_jbake_serve_rendering_bug_fix_post.html Wed, 22 Apr 2026 00:00:00 +0000 blog/2026/0107_jbake_serve_rendering_bug_fix_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_cuatro_screenshots_dos_renderizados">La escena : cuatro screenshots, dos renderizados</a> <ul class="sectlevel2"> <li><a href="#_renderizado_local">Renderizado local</a></li> <li><a href="#_renderizado_en_línea">Renderizado en línea</a></li> </ul> </li> <li><a href="#_el_diagnóstico_serve_no_apuntaba_al_directorio_correcto">El diagnóstico: <code>serve</code> no apuntaba al directorio correcto</a></li> <li><a href="#_la_causa_raíz_jbake_cli_no_funciona_así">La causa raíz: JBake CLI no funciona así</a></li> <li><a href="#_la_solución_argumentos_posicionales_no_banderas">La solución: argumentos posicionales, no banderas</a></li> <li><a href="#_verificación_rápida_con_curl">Verificación rápida con curl</a></li> <li><a href="#_por_qué_este_bug_era_vicioso">¿Por qué este bug era vicioso?</a></li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 10 minutes</div> <p>¿Conoces ese momento en que tu sitio local parece nada, pero una vez desplegado en línea todo está perfecto? Eso es lo que me pasó con mi plugin Gradle JBake. La tarea`serve`mostraba botones cuadrados, texto oscuro sobre fondo negro, y un CSS extrañamente ausente. Sin embargo`publishSite`generaba el mismo sitio, él, impecable. El culpable no era ni el CSS, ni el navegador, ni la caché. Era una línea de código Kotlin — y un mal hábito con los argumentos de línea de comandos.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_cuatro_screenshots_dos_renderizados">La escena : cuatro screenshots, dos renderizados</h2> <div class="sectionbody"> <div class="paragraph"> <p>Era después de un fallo del sistema. Había hecho cuatro capturas de pantalla para comparar el renderizado local (<code>./gradlew serve`sobre`localhost:8820</code>) con el renderizado en línea (`publishSite`en GitHub Pages). Dos capturas de pantalla por página: la parte superior e inferior.</p> </div> <div class="sect2"> <h3 id="_renderizado_local">Renderizado local</h3> <div class="paragraph"> <p><strong>Principio de página</strong>— Los botones <strong>Project</strong> y <strong>Template</strong> son<strong>pequeños, rectangulares</strong>, a los colores estándar (azul y verde). La tarjeta <strong>Start Writing</strong> tiene un<strong>fondo negro uniforme</strong>, sin marco.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local1.png" alt="Rendu local - haut de page"> </div> </div> <div class="paragraph"> <p><strong>pie de página</strong>— El subtítulo <strong>"Últimos artículos y recursos"</strong> es<strong>casi ilegible</strong>, demasiado oscuro sobre fondo negro. Las fechas debajo de las imágenes del blog ("17 October 2013", etc.) son<strong>ausentes</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local2.png" alt="Rendu local - bas de page"> </div> </div> </div> <div class="sect2"> <h3 id="_renderizado_en_línea">Renderizado en línea</h3> <div class="paragraph"> <p><strong>Encabezado de página</strong>— Los mismos botones son<strong>grandes, ovino, verde neón llamativo</strong>, texto en mayúsculas. La tarjeta tiene un<strong>marco blanco redondeado con sombra proyectada</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online1.png" alt="Rendu en ligne - haut de page"> </div> </div> <div class="paragraph"> <p><strong>Pie de página</strong>— El subtítulo es<strong>bien legible</strong>. Las fechas son<strong>visibles</strong>. Las tarjetas de los artículos tienen<strong>esquinas redondeadas</strong>y los títulos son<strong>en negrita</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online2.png" alt="Rendu en ligne - bas de page"> </div> </div> <div class="paragraph"> <p>Primer reflejo: el tema. Uso un sistema de tema dinámico (claro, oscuro, alto contraste) basado en`localStorage`. Tal vez el local store activaba un tema high-contrast? No. Ya había escritohttps://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[un artículo completo sobre la precarga de temas], sé cómo funciona. Además, incluso en modo alto contraste, la estructura CSS (botones ovales, sombras) debía estar allí. No estaba.</p> </div> <div class="paragraph"> <p>Segundo reflejo: el caché del navegador. No, había hecho la prueba con perfiles limpios. El diff persistía.</p> </div> <div class="paragraph"> <p>Tercer reflejo:`serve`no servía los mismos archivos que`publishSite`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_diagnóstico_serve_no_apuntaba_al_directorio_correcto">El diagnóstico: <code>serve</code> no apuntaba al directorio correcto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mi plugin Gradle`bakery`a deux tâches principales :</p> </div> <div class="ulist"> <ul> <li> <p><code>bake</code>: genera el sitio estático en`build/bake/`</p> </li> <li> <p><code>serve</code>: lanza un servidor web local</p> </li> <li> <p>`publishSite`empuja`build/bake/`a GitHub Pages</p> </li> </ul> </div> <div class="paragraph"> <p>La divergencia solo podía provenir de`serve`. Si <code>publishSite`publicaba el contenido correcto, es que`build/bake/`estaba bien. Si`serve`mostraba otra cosa, es que no servía`build/bake/</code>.</p> </div> <div class="paragraph"> <p>Miremos el código. En`SiteManager.kt`, la tarea`serve`está definida así :</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version buggy)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("serve", JavaExec::class.java) { task -> task.apply { mainClass.set("org.jbake.launcher.Main") classpath = jbakeRuntime environment("GEM_PATH", jbakeRuntime.asPath) jvmArgs(/* ... */) args = listOf( "-b", file(site.bake.srcPath).absolutePath, "-s", layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath ) } }</code></pre> </div> </div> <div class="paragraph"> <p><code>org.jbake.launcher.Main`es el punto de entrada de la CLI JBake 2.7.0. La idea : pasar</code>-b`para el directorio de origen y`-s`para el directorio de destino, lanzar el modo servidor. Excepto que…​</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_causa_raíz_jbake_cli_no_funciona_así">La causa raíz: JBake CLI no funciona así</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0 está esperando<strong>argumentos posicionales</strong>para origen y destino, luego flags opcionales. La firma es :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake <source> <destination> [options]</code></pre> </div> </div> <div class="paragraph"> <p>Pero, en mi código, escribía:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", "/path/to/site", "-s", "/path/to/build/bake")</code></pre> </div> </div> <div class="paragraph"> <p>JBake lo interpretaba como :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ parse el flag "bake" (booleano), consumido</p> </li> <li> <p><code>/path/to/site</code>→ se convierte en argumento posicional 1(fuente)</p> </li> <li> <p><code>-s</code>→ parsear la bandera "serve" (booleana), servidor iniciado<strong>inmediatamente</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ se convierte en un argumento huérfano, ignorado o malinterpretado</p> </li> </ol> </div> <div class="paragraph"> <p>Resultado : JBake estaba tomando`/path/to/site`como fuente,<strong>no tenía en cuenta el destino</strong>proporcionada (<code>build/bake</code>), y utilizaba su repertorio por defecto (a menudo`./output`o una copia temporal). El archivo`css/styles.css`del build estaba entonces sobrescrito o ignorado, y era un CSS predeterminado antiguo (sin las variables personalizadas, sin los bordes redondeados, sin las sombras) que se servía.</p> </div> <div class="paragraph"> <p>En comparación,<code>bake</code> et <code>publishSite`utilizan el<strong>plugin oficial de Gradle JBake</strong>(`jbake-gradle-plugin</code>) quien escribe ordenadamente en`build/bake/`mediante la API de Gradle. No pasan por la CLI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_argumentos_posicionales_no_banderas">La solución: argumentos posicionales, no banderas</h2> <div class="sectionbody"> <div class="paragraph"> <p>La corrección es trivial — una vez que se sabe. Basta con pasar la fuente y el destino como argumentos posicionales, entonces`-s`finalmente</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version corrigée)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">args = listOf( file(site.bake.srcPath).absolutePath, layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath, "-s" )</code></pre> </div> </div> <div class="paragraph"> <p>Eso es todo. Tres líneas cambiadas, bug resuelto.</p> </div> <div class="paragraph"> <p>Después de la publicación local del plugin (<code>publishToMavenLocal</code>), un `./gradlew serve`lanza JBake con la sintaxis correcta :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake /home/user/project/site /home/user/project/build/bake -s</code></pre> </div> </div> <div class="paragraph"> <p>Y esta vez, el servidor Jetty integrado a JBake sirve bien el contenido de`build/bake/`— idéntico a lo que se publica en línea.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/serve-vs-publish-diagram.svg" alt="serve vs publish diagram" width="1742" height="5484"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificación_rápida_con_curl">Verificación rápida con curl</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para asegurarse de que el servidor sirva bien el contenido correcto, un simple`curl`confirma que`index.html`contiene`data-bs-theme="light"`y que`build/bake/css/styles.css`pesa bien 31 402 octets — idéntico al archivo generado por`bake`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew serve # Dans un autre terminal : $ curl -s http://localhost:8820/ | grep data-bs-theme <html ... data-bs-theme="light" ...> $ curl -I http://localhost:8820/css/styles.css HTTP/1.1 200 OK Content-Length: 31402 Content-Type: text/css</code></pre> </div> </div> <div class="paragraph"> <p>El renderizado local ahora es<strong>pixel idéntico</strong>al renderizado desplegado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_este_bug_era_vicioso">¿Por qué este bug era vicioso?</h2> <div class="sectionbody"> <div class="paragraph"> <p>¿Ves por qué era difícil de atrapar?</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Sin error explícito</strong>: JBake no fallaba. Simplemente estaba funcionando con una carpeta incorrecta.</p> </li> <li> <p><strong>El build funcionaba</strong>:`./gradlew bake`generaba correctamente los archivos en`build/bake/`.</p> </li> <li> <p><strong>El despliegue funcionaba</strong>:`publishSite`publicaba el buen contenido en línea.</p> </li> <li> <p><strong>Sólo <code>serve</code> estaba roto</strong>: la tarea de desarrollo, la que utilizamos constantemente para iterar.</p> </li> <li> <p><strong>La costumbre de <code>-key value</strong>: como desarrollador, se condiciona por años de CLI Unix (</code>-o output`, <code>-i input</code>). JBake CLI es una excepción — el origen y el destino son posicionales.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si usted mantiene un plugin Gradle que envuelve JBake(o cualquier herramienta CLI),<strong>lee la documentación de los argumentos</strong>aunque los conozcas. Una hipótesis implícita (<code>-s</code> = "set destination"` puede costarte horas de depuración visual.</p> </div> <div class="paragraph"> <p>Aquí, el fix era literalmente cambiar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", src, "-s", dest) // ❌ BUG</code></pre> </div> </div> <div class="paragraph"> <p>en :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf(src, dest, "-s") // ✅ FIX</code></pre> </div> </div> <div class="paragraph"> <p>Tres tokens desplazados, y mi sitio local vuelve a ser tan bonito como el sitio en producción.</p> </div> <div class="paragraph"> <p><strong>Lección</strong>: cuando el renderizado difiere entre local y prod sin razón evidente, sospecha primero del <strong>pipeline</strong> — no el CSS, no el navegador, y mucho menos el framework. Suele ser el paso justo antes del renderizado el que engaña.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0106_opencode_path_sdkman_nvm_post.html Tue, 21 Apr 2026 00:00:00 +0000 blog/2026/0106_opencode_path_sdkman_nvm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_escena_un_agente_ciego_en_un_mundo_de_herramientas">La escena: un agente ciego en un mundo de herramientas</a></li> <li><a href="#_anatomía_del_bug_dos_shells_dos_mundos">Anatomía del bug: dos shells, dos mundos</a></li> <li><a href="#_los_culpables_zshrc_vs_zshenv">Los culpables : .zshrc vs .zshenv</a></li> <li><a href="#_diagnóstico_paso_a_paso">Diagnóstico paso a paso</a> <ul class="sectlevel2"> <li><a href="#_comprobar_el_path_del_agente">Comprobar el PATH del agente</a></li> <li><a href="#_identificar_lo_que_está_en_zshrc_pero_no_está_en_zshenv">Identificar lo que está en .zshrc pero no está en .zshenv</a></li> <li><a href="#_3_verificar_si_zshenv_existe">3. Verificar si .zshenv existe</a></li> </ul> </li> <li><a href="#_la_solución_zshenv_los_buenos_caminos">La solución: .zshenv + los buenos caminos</a> <ul class="sectlevel2"> <li><a href="#_crear_zshenv_con_todos_los_caminos_esenciales">Crear .zshenv con todos los caminos esenciales</a></li> <li><a href="#_por_qué_no_source_sdkman_init_sh_en_zshenv">¿Por qué no <code>source sdkman-init.sh</code> en .zshenv?</a></li> </ul> </li> <li><a href="#_el_caso_nvm_cuando_el_gestor_de_versiones_olvida_dejar_una_huella">El caso NVM: cuando el gestor de versiones olvida dejar una huella</a> <ul class="sectlevel2"> <li><a href="#_el_problema_nvm">El problema NVM</a></li> <li><a href="#_la_solución_crear_el_symlink_current_para_nvm">La solución: crear el symlink <code>current</code> para NVM</a></li> <li><a href="#_automatizar_la_actualización_del_enlace_simbólico">Automatizar la actualización del enlace simbólico</a></li> </ul> </li> <li><a href="#_tabla_resumen_de_los_caminos">Tabla resumen de los caminos</a></li> <li><a href="#_trampas_y_mitigaciones">Trampas y mitigaciones</a></li> <li><a href="#_lecciones_aprendidas">Lecciones aprendidas</a></li> <li><a href="#_verificación_final">Verificación final</a></li> <li><a href="#_enlaces">Enlaces</a> <ul class="sectlevel2"> <li><a href="#_documentación_oficial">Documentación oficial</a></li> <li><a href="#_herramientas_mencionadas">Herramientas mencionadas</a></li> <li><a href="#_para_ir_más_lejos">Para ir más lejos</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 13 minutes</div> <p>Lanzas OpenCode en tu terminal, todo funciona. El agente intenta un`gh`— no encontrado. Un`java -version`— ausente. un`node`— en ninguna parte. Sin embargo, estas herramientas están realmente allí en tu <em>shell</em>. ¿El problema? OpenCode lanza shells<strong>no interactivos</strong>que nunca leen su`.zshrc`. Aquí tienes cómo diagnosticar y corregir esto correctamente.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_escena_un_agente_ciego_en_un_mundo_de_herramientas">La escena: un agente ciego en un mundo de herramientas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Era un martes por la noche. Acababa de instalarhttps://opencode.ai[OpenCode], el agente IA que prometía transformar mi forma de programar. Primera prueba: pedirle que liste mis repositorios de GitHub.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode > Utilise gh pour lister mes repos ❌ bash: gh: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Extraño.`gh`funcionaba perfectamente en mi terminal. Estoy probando otra cosa :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Vérifie la version de Java ❌ bash: java: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Entonces :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Lance le build Gradle ❌ bash: gradle: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Java, Gradle, Node,<code>gh</code>— todo era invisible para el agente. Mi terminal, él, veía todo. Como si el agente y yo viviéramos en dos mundos paralelos.</p> </div> <div class="paragraph"> <p>Me llevó horas entender. Horas de`echo $PATH`, de <code>which java</code>, de frustración creciente. Por fin entendí que el problema no eran las herramientas — era<strong>shell</strong>. OpenCode, como cualquier agente que lance subprocesos, trabaja en shells<strong>no interactivos</strong>.Y Zsh, en esos shells, ignora pura y simplemente su`.zshrc`.</p> </div> <div class="paragraph"> <p>Lo que sigue es el relato completo de este diagnóstico, de la resolución y de la lección que he aprendido. Si utilizas un agente de IA — OpenCode, Aider, Cursor o incluso scripts cron — este problema te afectará algún día.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomía_del_bug_dos_shells_dos_mundos">Anatomía del bug: dos shells, dos mundos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando abre un terminal, Zsh lo trata como un shell<strong>interactivo</strong>. Él carga`.zshrc`, que inicializa todo: SDKMAN, NVM, pnpm, los alias, tu bonito prompt. Tu entorno está completo.</p> </div> <div class="paragraph"> <p>Pero cuando OpenCode ejecuta un comando, no inicia una terminal interactiva. Inicia una shell<strong>no interactivo</strong>— un shell de tarea, sin humano detrás de la pantalla. Y Zsh, en este contexto, salta`.zshrc`. Solo lee`.zshenv`.</p> </div> <div class="paragraph"> <p>¿Por qué existe esta distinción? Porque un shell no interactivo está diseñado para ejecutar scripts, no para servir a un usuario humano. Cargar los alias, el prompt y las completaciones en un script que se ejecuta en segundo plano sería un desperdicio. El problema es que tu PATH — la información más crítica para encontrar los ejecutables — suele inicializarse en`.zshrc`, no en`.zshenv`.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE actor "Usted" as user actor "OpenCode\n(agente)" as agent participant "Shell\ninteractivo\n(.zshrc cargado)" as ishell participant "Shell ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor "Usted" as user actor "OpenCode\n(agente)" as agent participant "Shell\ninteractivo\n(.zshrc cargado)" as ishell participant "Shell no interactivo (.zshrc ignorado)" as nshell user -> ishell : gh, java, node ✅ agent -> nshell : gh, java, node ❌ note right of ishell Source .zshrc : - SDKMAN init - NVM init - ~/apps dans PATH - pnpm dans PATH end note note right of nshell .zshrc ignoré ! PATH = /usr/bin:/bin + quelques répertoires défaut end note @enduml</pre> </div> </div> <div class="paragraph"> <p>La raíz del problema :<strong>Zsh solo source <code>.zshrc</code> para los shells interactivos</strong>. OpenCode, como cualquier agente de IA que lanza subprocesos, utiliza shells no interactivos. Estos shells solo leen`.zshenv`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_los_culpables_zshrc_vs_zshenv">Los culpables : .zshrc vs .zshenv</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh dispone de<strong>cuatro archivos de inicialización</strong>, cada uno con un papel preciso. Es un diseño elegante — pero también es el nudo del problema:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">obtenido cuando</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Papel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">¿Modifica el PATH?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshenv</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>siempre</strong>(interactivo + no interactivo + inicio de sesión)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variables de entorno esenciales, PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Sí — es SA lugar</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zprofile</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Shells de inicio de sesión únicamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comandos lentos (una vez por sesión)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Posible</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshrc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Sólo shells interactivos</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias, prompt, completado, herramientas interactivas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No para las variables críticas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zlogin</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Shells de inicio de sesión (después de .zshrc)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mensajes de bienvenida, finalización</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rara vez</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La tabla da una pista, pero hay que comprenderla en profundidad. Piensa en ella como las piezas de una casa:</p> </div> <div class="ulist"> <ul> <li> <p>`.zshenv`es el<strong>hall de entrada</strong>— todos pasan por aquí, sea visitante o residente. Si pones algo aquí, cualquier shell podrá verlo.</p> </li> <li> <p>`.zshrc`es el<strong>salón</strong>— solo los residentes (shells interactivos) entran. Los visitantes (shells no interactivos) permanecen en el vestíbulo.</p> </li> <li> <p><code>.zprofile</code> et `.zlogin`son piezas especializadas para shells de inicio de sesión (como cuando te conectas por SSH).</p> </li> </ul> </div> <div class="paragraph"> <p>El drama es que la mayoría de nosotros ponemos el PATH en la sala. Y el agente de IA, él, nunca tiene derecho a entrar.</p> </div> <div class="paragraph"> <p>El problema en un diagrama:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/zsh-init-flow.svg" alt="zsh init flow" width="543" height="404"> </div> </div> <div class="paragraph"> <p>Cuando abre una terminal, Zsh es interactivo: lee`.zshrc`, todo funciona. Cuando OpenCode lanza un shell para ejecutar un comando, Zsh es no interactivo: salta`.zshrc`, solo lee`.zshenv`. Et si `.zshenv`no existe o no contiene el PATH — es el desierto.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>¿Por qué Zsh hace eso?</strong>es una elección de diseño heredada de Unix. Un shell no interactivo debe ser<strong>rápido</strong> et <strong>reproducible</strong>. Cargar los alias, los prompts coloreados y las inicializaciones pesadas de SDKMAN en un script de cron o un agente IA sería lento y frágil. La separación, por lo tanto, tiene sentido :`.zshenv`en esencia (variables, PATH)`.zshrc`Para la comodidad (aliases, prompt, completamos). El problema surge cuando se pone lo esencial en la comodidad.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_diagnóstico_paso_a_paso">Diagnóstico paso a paso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de corregir, es necesario comprender exactamente qué falta. Aquí tienes un método de diagnóstico reproducible — guárdalo en favoritos si trabajas con agentes de IA.</p> </div> <div class="sect2"> <h3 id="_comprobar_el_path_del_agente">Comprobar el PATH del agente</h3> <div class="paragraph"> <p>Se compara lo que ve su terminal interactivo con lo que ve un shell no interactivo — es decir, lo que ve OpenCode.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans votre terminal interactif (tout fonctionne) echo $PATH | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>Resultado típico :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/apps /home/cheroliv/.nvm/versions/node/v22.19.0/bin /home/cheroliv/.sdkman/candidates/java/current/bin /home/cheroliv/.sdkman/candidates/gradle/current/bin /home/cheroliv/.local/share/pnpm /home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p>Ahora, simulemos lo que ve el agente — un shell no interactivo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif : pas de .zshrc zsh -c 'echo $PATH' | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>Resultado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p><strong>Cinco de seis caminos han desaparecido.</strong>El agente está amputado del 83% de su entorno. Es como si te pidieran cocinar sin la mitad de tus utensilios — podrías hervir agua, pero poco más.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>El pedido`zsh -c 'echo $PATH'`es su<strong>herramienta de diagnóstico número 1</strong>. Si una herramienta que utilizas diariamente no aparece en el resultado, tu agente de IA tampoco podrá verla. Pruébala antes y después de cada modificación de`.zshenv`.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_identificar_lo_que_está_en_zshrc_pero_no_está_en_zshenv">Identificar lo que está en .zshrc pero no está en .zshenv</h3> <div class="paragraph"> <p>Ahora, estamos buscando al culpable en`.zshrc`. Filtramos las líneas que mencionan nuestras herramientas :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">grep -n 'apps\|SDKMAN\|NVM\|PNPM\|PATH' ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>Se encuentra típicamente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">119: PATH="/usr/bin/python3:$HOME/apps:$PATH" # ← pas exporté ! 171: export NVM_DIR="$HOME/.nvm" 172: [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # ← NVM init 176: nvm use --lts --silent # ← active une version 179: export PNPM_HOME="/home/cheroliv/.local/share/pnpm" 187: export SDKMAN_DIR="$HOME/.sdkman" 188: [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>Todo eso es<strong>invisible</strong>para OpenCode. Y el`PATH`de la línea 119 ni siquiera`export`é — él nunca abandona el shell actual. Es un detalle técnico crucial: una variable sin`export`permanece local al shell que lo define. Los sub-shells — como los lanzados por OpenCode — nunca lo heredan.</p> </div> </div> <div class="sect2"> <h3 id="_3_verificar_si_zshenv_existe">3. Verificar si .zshenv existe</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cat ~/.zshenv 2>/dev/null || echo "FICHIER ABSENT"</code></pre> </div> </div> <div class="paragraph"> <p>Si la respuesta es « FICHIER ABSENT », ahí es donde se juega todo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_zshenv_los_buenos_caminos">La solución: .zshenv + los buenos caminos</h2> <div class="sectionbody"> <div class="paragraph"> <p>La estrategia es simple, pero requiere precisión: poner en`.zshenv` <strong>solo</strong>los caminos esenciales, sin cargar los scripts de inicialización pesados. No lo movemos`.zshrc`en`.zshenv`— se extrae lo esencial.</p> </div> <div class="sect2"> <h3 id="_crear_zshenv_con_todos_los_caminos_esenciales">Crear .zshenv con todos los caminos esenciales</h3> <div class="paragraph"> <p>`.zshenv`es el<strong>único archivo</strong>que Zsh garantiza de sourcear en<strong>todos</strong>los contextes. Es ahí donde debe ir el PATH.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export SDKMAN_DIR="$HOME/.sdkman" export NVM_DIR="$HOME/.nvm" export PNPM_HOME="$HOME/.local/share/pnpm" export PATH="$HOME/apps:$HOME/.sdkman/candidates/java/current/bin:$HOME/.sdkman/candidates/gradle/current/bin:$HOME/.nvm/current/bin:$PNPM_HOME:$HOME/.local/bin:$HOME/.local/share/JetBrains/Toolbox/scripts:/usr/bin/python3:$PATH"</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Se utiliza`$HOME/.nvm/current/bin`y no`$HOME/.nvm/versions/node/v22.19.0/bin`. La razón: las versiones de Node cambian. Un camino fijo se vuelve falso en el próximo`nvm install`. Más detalles en la sección siguiente.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_por_qué_no_source_sdkman_init_sh_en_zshenv">¿Por qué no <code>source sdkman-init.sh</code> en .zshenv?</h3> <div class="paragraph"> <p>El enfoque más tentador sería simplemente reproducir en`.zshenv`lo que hacemos en`.zshrc`— sourcer los scripts de inicialización. Nosotros<strong>podría</strong>ser tentado de hacer :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ MAUVAISE IDÉE [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>Problemas :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Cuaresma</strong>:`sdkman-init.sh`Hace resoluciones de red y verificaciones en cada shell. En un shell no interactivo, es un costo innecesario.</p> </li> <li> <p><strong>Frágil</strong>: SDKMAN espera un contexto interactivo. Su inicialización puede fallar silenciosamente en una tubería o un sub-shell.</p> </li> <li> <p><strong>Inútil</strong>: SDKMAN coloca a sus candidatos en`~/.sdkman/candidates/<tool>/current/bin`— enlaces simbólicos estables que apuntan a la versión activa. Se pueden utilizar<strong>directamente</strong>.</p> </li> </ul> </div> <div class="paragraph"> <p>La buena aproximación: evitar la inicialización de SDKMAN y apuntar directamente a los symlinks`current`. Es la clave de toda la solución :<strong>utilizar la estructura de archivos como contrato, en lugar del código de inicialización</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Enfoque LENTO (source sdkman-init.sh)" as slow { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "Enfoque LENTO (source sdkman-init.sh)" as slow { card ".zshenv source sdkman-init.sh 2-3 segundos por shell Comprobaciones de red Riesgo de fallo" as s1 #FDEDEC } rectangle "Enfoque rápido (enlaces simbólicos directos)" as fast { card ".zshenv export PATH=...current/bin\n0 ms\nSin red\nSin inicialización" as s2 #E8F8E8 } slow --> fast : Même résultat final\nLe PATH pointe sur current/bin\ndans les deux cas @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_caso_nvm_cuando_el_gestor_de_versiones_olvida_dejar_una_huella">El caso NVM: cuando el gestor de versiones olvida dejar una huella</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_problema_nvm">El problema NVM</h3> <div class="paragraph"> <p>Este es el lugar donde la investigación me ha llevado más lejos. SDKMAN tiene un diseño elegante: cuando se hace`sdk install java 25.0.2-tem`, crea un enlace simbólico:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.sdkman/candidates/java/current -> ~/.sdkman/candidates/java/25.0.2-tem</code></pre> </div> </div> <div class="paragraph"> <p>Este enlace simbólico es<strong>siempre al día</strong>. Apúntalo encima en`.zshenv`y estás cubierto, sea cual sea el shell. Hermoso.</p> </div> <div class="paragraph"> <p>NVM, él, no crea<strong>nada</strong>de tel. No hay enlace simbólico`current`. No hay un punto de anclaje estable. Debemos apuntar a un camino versionado de forma fija, que se parece a esto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.nvm/versions/node/v22.19.0/bin/node</code></pre> </div> </div> <div class="paragraph"> <p>Al próximo`nvm install 24`, este camino está muerto. Su`.zshenv`apuntará a una versión que ya no es la versión activa. Es una bomba de relojería.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>¿Por qué NVM hace eso?</strong>NVM funciona modificando dinámicamente el PATH en cada`nvm use`. Esto está diseñado para desarrolladores que cambian de versión a menudo, en un shell interactivo. El symlink`current`no estaba en las especificaciones iniciales — es un olvido de diseño que vamos a corregir nosotros mismos.</p> </div> </td> </tr> </table> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-vs-sdkman.svg" alt="nvm vs sdkman" width="1752" height="5676"> </div> </div> </div> <div class="sect2"> <h3 id="_la_solución_crear_el_symlink_current_para_nvm">La solución: crear el symlink <code>current</code> para NVM</h3> <div class="paragraph"> <p>Como NVM no lo hace, nosotros lo hacemos nosotros mismos. El principio es el mismo que SDKMAN — un enlace simbólico`current`siempre apunta a la versión activa. Lo creamos una vez y luego lo automatizamos para que se actualice solo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Créer le symlink initial ln -sfn "$HOME/.nvm/versions/node/v22.19.0" "$HOME/.nvm/current"</code></pre> </div> </div> <div class="paragraph"> <p>Ahora, en`.zshenv`, se utiliza :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$HOME/.nvm/current/bin</code></pre> </div> </div> <div class="paragraph"> <p>En lugar de :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ Chemin en dur — cassé au prochain changement de version $HOME/.nvm/versions/node/v22.19.0/bin</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_automatizar_la_actualización_del_enlace_simbólico">Automatizar la actualización del enlace simbólico</h3> <div class="paragraph"> <p>Un enlace simbólico no vale nada si no se actualiza. El enlace simbólico`current`debe actualizarse cuando se hace`nvm use` ou <code>nvm install</code>. La solución: un<strong>envoltorio</strong>— una función que envuelve el verdadero comando`nvm`y actualiza el enlace simbólico después de cada llamada.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># À la fin de .zshrc, APRÈS le chargement de NVM nvm use --lts --silent ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" _nvm() { command nvm "$@" local rc=$? ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" return $rc } alias nvm='_nvm'</code></pre> </div> </div> <div class="paragraph"> <p>¿Cómo funciona, en detalle :</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur participant "nvm wrapper ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur participant "nvm wrapper (_nvm)" as wrapper participant "nvm real (command nvm)" as realnvm participant "~/.nvm/current\n(symlink)" as symlink Développeur -> wrapper : nvm use 20 wrapper -> realnvm : command nvm use 20 realnvm --> wrapper : version activée wrapper -> symlink : ln -sfn .../v20.16.0 ~/.nvm/current wrapper --> Développeur : retour note right of symlink Toujours à jour ! Utilisé par .zshenv → accessible par OpenCode end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El wrapper`_nvm`llama al verdadero comando`nvm`, luego actualiza el enlace simbólico. El alias`nvm='_nvm'`hace que al teclear`nvm`, se pasa por el wrapper. Y al iniciar el shell, hacemos lo mismo después`nvm use --lts`.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>`nvm_version_path`es una función interna de NVM que resuelve el camino completo de una versión. Evita tener que reconstruir el camino manualmente.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tabla_resumen_de_los_caminos">Tabla resumen de los caminos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de pasar a las trampas, un resumen visual de la transformación. A la izquierda, lo que tenías (todo en`.zshrc`, invisible para el agente). A la derecha, lo que tienes ahora (los caminos esenciales en`.zshenv`, visibles por todas partes).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Herramienta</th> <th class="tableblock halign-left valign-top">Antes (.zshrc solo)</th> <th class="tableblock halign-left valign-top">Después (.zshenv + symlink)</th> <th class="tableblock halign-left valign-top">Visible por OpenCode?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps</code>(gh, vscode)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH no exportado en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/apps`en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sdkman-init.sh`sourced en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/java/current/bin`en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sdkman-init.sh`cargado en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/gradle/current/bin`en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(blank)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM Node</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`nvm use --lts`en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.nvm/current/bin`en .zshenv (symlink)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">pnpm</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$PNPM_HOME`en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$PNPM_HOME`en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output, as no French source text was provided for translation beyond the instructions themselves, which are not to be translated.)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JetBrains Toolbox</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Añadido automáticamente por Toolbox en .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.local/share/JetBrains/Toolbox/scripts`en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Python 3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`/usr/bin/python3`en PATH .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Explícitamente en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_trampas_y_mitigaciones">Trampas y mitigaciones</h2> <div class="sectionbody"> <div class="paragraph"> <p>No todo es perfecto con este enfoque. Aquí están los problemas que he encontrado, y cómo sortearlos.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">trampa</th> <th class="tableblock halign-left valign-top">Descripción</th> <th class="tableblock halign-left valign-top">Mitigación</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH duplicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Si .zshenv y .zshrc añaden el mismo camino, aparece dos veces</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`.zshenv`está obtenido<strong>antes</strong>.zshrc. Los dos se leen en un shell interactivo. El PATH puede duplicarse. Es cosmético, no funcional. Para evitarlo: solo pon en .zshenv los caminos <em>ausentes</em> del PATH por defecto.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM : versión hardcodeada en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Poner`~/.nvm/versions/node/v22.19.0/bin`en duro se vuelve falso al próximo`nvm install`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar el symlink`$HOME/.nvm/current/bin`+ el wrapper`_nvm`en .zshrc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN: source sdkman-init.sh en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lento, frágil, inútil en un shell no interactivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar los symlinks`candidates/<tool>/current/bin`directamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias faltante después de la modificación</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El wrapper`nvm='_nvm'`en .zshrc solo tiene efecto después de recargar</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reiniciar el shell o`source ~/.zshrc`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode no ve los cambios</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El agente ya ha lanzado sus sub-shells con el antiguo .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reiniciar OpenCode después de modificar .zshenv</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv demasiado cargado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Poner funciones pesadas o inicializaciones interactivas en .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv = variables de entorno + solo PATH. No`source`, sin funciones pesadas, sin prompts.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas">Lecciones aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>.zshrc` es interactivo, <code>.zshenv</code> es universal</strong>— Si una variable debe existir en <em>todos</em> los shells (agentes IA, cron, scripts, IDE), va a ir en`.zshenv`. El salón es cómodo, pero el vestíbulo es el único lugar donde todo el mundo pasa.</p> </li> <li> <p><strong>Los gestores de versiones no son iguales</strong>— SDKMAN crea enlaces simbólicos`current`Por diseño. NVM no. Hay que cubrir esta falta manualmente. Es una lección importante: antes de configurar su PATH, verifique si su gestor ofrece un punto de anclaje estable.</p> </li> <li> <p><strong>No sourcer los init scripts en .zshenv</strong>—<code>sdkman-init.sh</code> et `nvm.sh`están diseñados para un shell interactivo. Son lentos y frágiles en un contexto no interactivo. Los symlinks`current`son suficientes y son instantáneos.</p> </li> <li> <p><strong>Siempre probar en un shell no interactivo</strong>—`zsh -c 'echo $PATH'`Simula exactamente lo que ve un agente. Es la prueba de validación. Sin esta prueba, no sabes si tu configuración funciona para los agentes.</p> </li> <li> <p><strong>El patrón wrapper es reutilizable</strong>— El mismo patrón`_nvm`+`alias nvm='_nvm'`se aplica a cualquier herramienta que modifica el PATH de forma dinámica sin dejar una traza estable. Es una herramienta más en tu caja de ideas.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE rectangle "antes" as avant { card "Shell interactivo : ✅ Shell no interactivo : ❌ ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "antes" as avant { card "Shell interactivo : ✅ Shell no interactivo : ❌ OpenCode : ❌ Cron : ❌ Scripts : ❌" as av1 #FDEDEC } rectangle "DESPUÉS" as apres { card "Shell interactivo : ✅\nShell no interactivo : ✅\nOpenCode : ✅\nCron : ✅\nScripts : ✅" as ap1 #E8F8E8 } avant --> apres : .zshenv +\nsymlink ~/.nvm/current @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificación_final">Verificación final</h2> <div class="sectionbody"> <div class="paragraph"> <p>Después de haber creado`.zshenv`y el symlink NVM, verifica que todo funcione — en ambos contextos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell interactif (votre terminal) gh --version && java -version && node --version</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif (simulation OpenCode) zsh -c 'gh --version && java -version && node --version'</code></pre> </div> </div> <div class="paragraph"> <p>Ambos deben funcionar. Si es así, su agente de IA verá las mismas herramientas que usted. Si no, vuelva al diagnóstico paso a paso — probablemente haya olvidado una ruta o el enlace simbólico NVM no esté actualizado.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Automatiza este test.</strong>Agregue esta verificación en un script de healthcheck que usted ejecuta después de cada actualización de sus herramientas. Uno`zsh -c 'which java && which node && which gh'`en CI, es un seguro contra las sorpresas.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p><em><em>_ Un shell no interactivo es como un invitado silencioso: solo lee lo que se muestra en la puerta de entrada. Si el PATH está en el salón, nunca lo verá. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_enlaces">Enlaces</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_documentación_oficial">Documentación oficial</h3> <div class="ulist"> <ul> <li> <p><a href="https://zsh.sourceforge.io/Doc/Release/Files.html">Documentación de Zsh : Archivos de inicio</a>— La referencia oficial sobre los archivos de inicialización de Zsh. Aquí es donde se explica todo, incluso si se olvida a menudo.</p> </li> <li> <p><a href="https://opencode.ai/docs/config/">OpenCode : configuración</a>— Cómo configurar OpenCode y su entorno de ejecución</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_herramientas_mencionadas">Herramientas mencionadas</h3> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nvm-sh/nvm">NVM en GitHub</a>— Node Version Manager. Administrador de versiones Node.js.</p> </li> <li> <p><a href="https://sdkman.io">SDKMAN — sitio oficial</a>— SDKMAN! El gestor de versiones para la JVM (Java, Kotlin, Gradle…​)</p> </li> <li> <p><a href="https://sdkman.io/install">SDKMAN : instalación</a>— Guía de instalación de SDKMAN.</p> </li> <li> <p><a href="https://cli.github.com">gh` — CLI de GitHub</a>— La herramienta de línea de comandos de GitHub, indispensable para todo desarrollador.</p> </li> <li> <p><a href="https://gradle.org">Gradle — sitio oficial</a>— El sistema de compilación que instalamos vía SDKMAN</p> </li> <li> <p><a href="https://pnpm.io">pnpm — sitio oficial</a>— El gestor de paquetes de Node.js rápido y que ahorra espacio.</p> </li> <li> <p><a href="https://www.jetbrains.com/toolbox-app/">JetBrains Toolbox</a>— El gestor de IDE de JetBrains, que agrega sus scripts al PATH.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_para_ir_más_lejos">Para ir más lejos</h3> <div class="ulist"> <ul> <li> <p><a href="https://blog.andy2003.org/posts/2022/zsh-dotfiles/">Zsh dotfiles: una guía completa</a>— Artículo detallado sobre la gestión de los dotfiles Zsh.</p> </li> <li> <p><a href="https://wiki.archlinux.org/title/Zsh">Zsh en ArchWiki</a>— Una de las mejores documentaciones comunitarias sobre Zsh.</p> </li> <li> <p><a href="https://github.com/nvm-sh/nvm/issues">NVM problemas GitHub</a>— Para ver las discusiones alrededor del symlink`current`y problemas de PATH.</p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com//blog/2026/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/2026/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_diagramas_siempre_atrasados_respecto_al_código">El problema: diagramas siempre atrasados respecto al código</a></li> <li><a href="#_la_solución_un_pipeline_determinista_knowledge_graph_plantuml">La solución: un pipeline determinista Knowledge Graph → PlantUML</a></li> <li><a href="#_paso_1_instalar_graphify_y_extraer_el_knowledge_graph">Paso 1: Instalar Graphify y extraer el Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_instalación">Instalación</a></li> <li><a href="#_configurar_las_exclusiones">Configurar las exclusiones</a></li> <li><a href="#_extraer_el_knowledge_graph">Extraer el Knowledge Graph</a></li> </ul> </li> <li><a href="#_paso_2_el_plugin_gradle_transforma_el_knowledge_graph_en_plantuml">Paso 2: El plugin Gradle transforma el Knowledge Graph en PlantUML</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_del_pipeline">Arquitectura del pipeline</a></li> <li><a href="#_los_componentes_internos">Los componentes internos</a></li> <li><a href="#_reglas_de_renderizado">Reglas de renderizado</a></li> </ul> </li> <li><a href="#_paso_3_uso_diario">Paso 3: Uso diario</a> <ul class="sectlevel2"> <li><a href="#_diagrama_completo">Diagrama completo</a></li> <li><a href="#_filtrar_por_comunidad">Filtrar por comunidad</a></li> <li><a href="#_filtrar_por_tipo_de_arista">Filtrar por tipo de arista</a></li> <li><a href="#_filtrar_por_tipo_de_nodo_y_confianza">Filtrar por tipo de nodo y confianza</a></li> <li><a href="#_directorio_de_salida_personalizado">Directorio de salida personalizado</a></li> <li><a href="#_referencia_completa_de_las_propiedades">Referencia completa de las propiedades</a></li> </ul> </li> <li><a href="#_el_pipeline_completo_en_un_workflow_gradle">El pipeline completo en un workflow Gradle</a> <ul class="sectlevel2"> <li><a href="#_tipo_de_flujo_de_trabajo">tipo de flujo de trabajo</a></li> <li><a href="#_integración_en_el_ciclo_de_desarrollo">Integración en el ciclo de desarrollo</a></li> <li><a href="#_actualización_incremental">Actualización incremental</a></li> </ul> </li> <li><a href="#_el_dogfooding_el_plugin_se_auto_documenta">El dogfooding: el plugin se auto-documenta</a></li> <li><a href="#_por_qué_es_determinista_y_por_qué_importa">Por qué es determinista (y por qué importa)</a></li> <li><a href="#_diagramas_del_pipeline_mismo">Diagramas del pipeline mismo</a></li> <li><a href="#_integración_en_la_gobernanza_del_proyecto">Integración en la gobernanza del proyecto</a></li> <li><a href="#_puestra_en_marcha_lista_de_verificación_en_5_minutos">Puestra en marcha: lista de verificación en 5 minutos</a></li> <li><a href="#_trampas_y_mitigaciones">Trampas y mitigaciones</a></li> <li><a href="#_lo_que_se_obtiene_al_final">Lo que se obtiene al final</a></li> <li><a href="#_enlaces">Enlaces</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>Tu base de código crece. Las dependencias entre módulos se multiplican. La documentación de la arquitectura se vuelve obsoleta incluso antes de ser escrita. ¿Y si tu build de Gradle pudiera <em>automáticamente</em> generar diagramas actualizados a partir de la estructura real del código? Eso es exactamente lo que hace el pipeline Graphify + PlantUML Gradle Plugin :`graphify . --no-viz`extrae el Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`lo convierte en diagramas PlantUML. Cero LLM, cero manual, 100% determinista.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_diagramas_siempre_atrasados_respecto_al_código">El problema: diagramas siempre atrasados respecto al código</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo proyecto que supera varios miles de líneas conoce este síndrome:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Se dibuja un diagrama de arquitectura al inicio del proyecto</p> </li> <li> <p>El código evoluciona, las dependencias cambian</p> </li> <li> <p>El diagrama se convierte en una mentira decorativa</p> </li> <li> <p>Nadie lo actualiza porque es tedioso</p> </li> <li> <p>Los recién llegados se basan en ello y cometen errores</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-diagrammes-obsoletes.svg" alt="probleme diagrammes obsoletes" width="824" height="418"> </div> </div> <div class="paragraph"> <p>La pregunta no es <em>¿se necesitan diagramas?</em> — todo el mundo sabe que sí. La pregunta es :<strong>¿Quién los mantiene al día?</strong></p> </div> <div class="paragraph"> <p>La respuesta: nadie. A menos que sea automático.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_un_pipeline_determinista_knowledge_graph_plantuml">La solución: un pipeline determinista Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>El principio es simple : en lugar de dibujar los diagramas a mano, nosotros los<strong>genera desde la estructura real del código</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify (pip install graphifyy)" as Graphify collections "graphify-out/graph.json (Grafo del Conocimiento)" as KGJSON component "Plugin Gradle PlantUML (generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "KnowledgeGraphRenderer" as Renderer component "PlantumlService (validación + renderizado PNG)" as PS collections "diagrams/knowledge-graph/\n(.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : extrait la structure\ndu code source Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : code PlantUML\ndéterministe Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Pipeline DÉTERMINISTE Aucun appel LLM Résultat reproductible end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Dos comandos. Eso es todo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>¿El resultado? Archivos`.puml` et <code>.png`en`diagrams/knowledge-graph/</code>, versionados en Git, siempre actualizados con el código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_1_instalar_graphify_y_extraer_el_knowledge_graph">Paso 1: Instalar Graphify y extraer el Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_instalación">Instalación</h3> <div class="paragraph"> <p>Graphify es una herramienta de Python que analiza tu código base y construye un grafo de conocimientos estructurado:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_configurar_las_exclusiones">Configurar las exclusiones</h3> <div class="paragraph"> <p>Crear un archivo`.graphifyignore`en la raíz del proyecto para excluir los archivos que no forman parte de la lógica de negocio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_extraer_el_knowledge_graph">Extraer el Knowledge Graph</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>La bandera`--no-viz`Salta la generación de HTML (inútil en un pipeline Gradle). El resultado es un archivo`graphify-out/graph.json`conteniendo :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Nudos</strong>: clases, funciones, archivos — con su tipo y comunidad</p> </li> <li> <p><strong>Aristas</strong>: relaciones entre nodos (EXTRACTED desde el código, INFERRED por el LLM)</p> </li> <li> <p><strong>Comunidades</strong>: agrupaciones automáticas de nodos vinculados</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Ejemplo de estructura`graph.json`</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>El código fuente (<code>.kt</code>, <code>.java</code>) es analizado localmente por tree-sitter,<strong>sin apelación LLM</strong>. Sólo los archivos de documentación(<code>.adoc</code>, <code>.md</code>) requieren una llamada LLM para la extracción semántica. Entonces`--update`en el código Kotlin es casi instantáneo.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_2_el_plugin_gradle_transforma_el_knowledge_graph_en_plantuml">Paso 2: El plugin Gradle transforma el Knowledge Graph en PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitectura_del_pipeline">Arquitectura del pipeline</h3> <div class="paragraph"> <p>El plugin`com.cheroliv.plantuml`integra una tarea`generateKnowledgeGraphDiagram`que transforma`graph.json`en diagramas PlantUML de manera<strong>totalmente determinista</strong>:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1109" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_los_componentes_internos">Los componentes internos</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Componente</th> <th class="tableblock halign-left valign-top">Rol</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parsear`graph.json`— admite 3 formatos: graphify nativo (<code>nodes</code>+<code>links</code>), legacy (<code>communities</code>), flat. Resuelve los IDs numéricos en etiquetas.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforma determinísticamente un`KnowledgeGraph`en código PlantUML. Grupos por tipo, comunidades en paquetes, leyenda automática.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tarea Gradle que orquesta: parse → render → validate → PNG. Configurable vía propiedades Gradle.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelos de datos:`KnowledgeGraph`, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validación sintáctica + renderizado PNG (reutilizado por todas las tareas del plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_reglas_de_renderizado">Reglas de renderizado</h3> <div class="paragraph"> <p>El renderer aplica convenciones visuales deterministes:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Tipo de arista</th> <th class="tableblock halign-left valign-top">Notación PlantUML</th> <th class="tableblock halign-left valign-top">Significado</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">extraído</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(línea continua, negra)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación extraída del código fuente (certidumbre)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DEDUCIDO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(línea punteada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación inferida por el LLM (puntuación de confianza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ambiguo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(línea roja punteada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación ambigua (por verificar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Las comunidades se representan como paquetes PlantUML con una paleta de colores automática.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_3_uso_diario">Paso 3: Uso diario</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_completo">Diagrama completo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Sortie : <code>diagrams/knowledge-graph/knowledge-graph-full.puml</code> + <code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_comunidad">Filtrar por comunidad</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_tipo_de_arista">Filtrar por tipo de arista</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_tipo_de_nodo_y_confianza">Filtrar por tipo de nodo y confianza</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_directorio_de_salida_personalizado">Directorio de salida personalizado</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_referencia_completa_de_las_propiedades">Referencia completa de las propiedades</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Propiedad</th> <th class="tableblock halign-left valign-top">Defecto</th> <th class="tableblock halign-left valign-top">Descripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(todas)_</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar las comunidades por nombre (coincidencia de subcadena)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(todos)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de aristas separados por comas :`EXTRACTED`, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Umbral mínimo de confianza para las aristas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(ilimitado)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Número máximo de nodos a mostrar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(todos)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de nodos separados por comas (ej.<code>class</code>, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directorio de salida para los archivos`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_pipeline_completo_en_un_workflow_gradle">El pipeline completo en un workflow Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tipo_de_flujo_de_trabajo">tipo de flujo de trabajo</h3> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet.svg" alt="workflow complet" width="618" height="714"> </div> </div> </div> <div class="sect2"> <h3 id="_integración_en_el_ciclo_de_desarrollo">Integración en el ciclo de desarrollo</h3> <div class="paragraph"> <p>El pipeline se integra naturalmente en las etapas clave del desarrollo :</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE state "Desarrollo" as dev state "Extracción\ngraphify . --no-viz" as extract state "Generación ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE state "Desarrollo" as dev state "Extracción\ngraphify . --no-viz" as extract state "Generación ./gradlew generateKnowledgeGraphDiagram" as generate state "Commit diagramas versionados" as commit [*] --> dev dev --> extract : Code modifié extract --> generate : graph.json à jour generate --> commit : .puml + .png générés commit --> dev : Diagrammes dans le repo note right of extract Quasi instantané sur du code Kotlin (tree-sitter, pas de LLM) end note note right of generate Déterministe Pas de LLM Résultat reproductible end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_actualización_incremental">Actualización incremental</h3> <div class="paragraph"> <p>Cuando el código cambia, no se reconstruye todo el grafo desde cero:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update`Reextrae solo los archivos modificados (detectados por SHA256 en`graphify-out/cache/</code>). En código Kotlin, es casi instantáneo porque tree-sitter trabaja localmente sin una llamada al LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_dogfooding_el_plugin_se_auto_documenta">El dogfooding: el plugin se auto-documenta</h2> <div class="sectionbody"> <div class="paragraph"> <p>El plugin PlantUML existe para transformar los prompts en diagramas. También puede transformar el Knowledge Graph de su <em>propre</em> codebase en diagramas de documentación. Es <em>dogfooding</em> : el plugin consume su propio servicio.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal (usuario → diagramas)" as normal { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal (usuario → diagramas)" as normal { [Fichier .prompt] as prompt [LlmService\n+ ApiKeyPool] as llm1 [ProcessPlantumlPromptsTask] as task1 [Diagramme PNG] as out1 prompt --> task1 task1 --> llm1 llm1 --> out1 } package "Pipeline Knowledge Graph\n(determinista, sin LLM)" as kg { [graphify-out/graph.json] as kgjson [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantumlService] as ps [Diagramme PNG\n(documentation du plugin)] as out2 kgjson --> parser parser --> renderer renderer --> ps ps --> out2 } package "Pipeline Dogfooding (LLM → documentación del plugin)" as dogfood { [GraphifyPromptAdapter] as gpa [Fichiers .prompt\nauto-générés] as auto_prompt [LlmService\n+ ApiKeyPool] as llm2 [ProcessPlantumlPromptsTask] as task2 [Diagramme PNG\n(documentation LLM)] as out3 kgjson --> gpa gpa --> auto_prompt auto_prompt --> task2 task2 --> llm2 llm2 --> out3 } note "Igual LlmService, igual ApiKeyPool, Igual PlantumlService — CERO duplicación" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>Tareas Gradle asociadas :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Tarea</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Descripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforma`graph.json`en PlantUML (determinista)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">genera`.prompt`desde el grafo, los trata mediante LLM (dogfooding)</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_es_determinista_y_por_qué_importa">Por qué es determinista (y por qué importa)</h2> <div class="sectionbody"> <div class="paragraph"> <p>El punto clave del pipeline`generateKnowledgeGraphDiagram`:<strong>No llama a ningún LLM</strong>. La transformación`graph.json`→ PlantUML es una función pura.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 16) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline DETERMINISTA\n(generateKnowledgeGraphDiagram)" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "Pipeline LLM ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline DETERMINISTA\n(generateKnowledgeGraphDiagram)" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "Pipeline LLM (processPlantumlPrompts)" as llm { [.prompt] as prompt [LlmService] as llmSvc [ChatModel] as model [PlantUML code] as puml2 prompt --> llmSvc llmSvc --> model : API call model --> puml2 : réponse non-déterministe } note bottom of det Même entrée → même sortie Pas de latence réseau Pas de coût en tokens Reproductible en CI end note note bottom of llm Même entrée → sortie variable Latence réseau (1-5s) Coût en tokens Nécessite une clave API end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Los beneficios concretos :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ventaja</th> <th class="tableblock halign-left valign-top">Impacto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reproducibilidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Incluso`graph.json`→ mismo diagrama. Exactamente. Cada vez.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo cero</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sin llamada LLM = sin tokens = sin factura API.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero latencia</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render tarda ~100ms, no 1-5 segundos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatible con CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No se necesita una clave API. No hay pruebas inestables debido a una respuesta de LLM variable.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">versionable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`generado es texto. Podemos lo`diff</code>, el revisor en PR, versionarlo en Git.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagramas_del_pipeline_mismo">Diagramas del pipeline mismo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para cerrar el bucle, aquí está el diagrama del pipeline tal como sería generado por el plugin:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1806" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integración_en_la_gobernanza_del_proyecto">Integración en la gobernanza del proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>En nuestro proyecto, este pipeline se integra en una estrategia de gestión de contexto EAGER/LAZY para el agente IA. El Knowledge Graph reemplaza la documentación de arquitectura manual por un grafo estructurado, consultable y autoactualizado.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 11) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(siempre cargado)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Estrategia ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(siempre cargado)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Estrategia (a petición)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify\n(consultas dirigidas)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML\n(auto-generado)" as puml { [generateKnowledgeGraphDiagram] as kgTask [generateDiagramDocs] as ddTask [Diagrammes PNG] as diagrams } Agent --> eager : Lit en début de session Agent ..> lazy_strat : Charge si type détecté Agent ..> lazy_graph : Query si besoin structurel kgTask --> diagrams : Déterministe ddTask --> diagrams : Via LLM note right of gr Condensé du Knowledge Graph God nodes + communautés Remplace ECOSYSTEM_OVERVIEW (225 lignes → 50 lignes) end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El matrimonio de los dos sistemas es complementario:</p> </div> <div class="ulist"> <ul> <li> <p><strong>La estrategia gestiona el CUÁNDO y el CÓMO</strong>— gobernanza, flujo de trabajo, archivo</p> </li> <li> <p><strong>Graphify gestiona el QUOI y el OÙ</strong>— estructura del código, relaciones, consultas específicas</p> </li> </ul> </div> <div class="paragraph"> <p><em>__</em> La estrategia de sesión gestiona el<strong>CUANDO</strong> et le <strong>CÓMO</strong>(gouvernance, workflow, seuils), Graphify gestiona el<strong>QUÉ</strong> et le <strong>dónde</strong>(estructura del código, relaciones, consultas dirigidas). El pipeline PlantUML gestiona el<strong>CON QUÉ</strong>(diagramas deterministas, versionados, siempre actualizados) (Empty)</p> </div> </div> </div> <div class="sect1"> <h2 id="_puestra_en_marcha_lista_de_verificación_en_5_minutos">Puestra en marcha: lista de verificación en 5 minutos</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">(No output, as the text to translate is empty)</th> <th class="tableblock halign-left valign-top">Etapa</th> <th class="tableblock halign-left valign-top">Pedido</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Instalar Graphify</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configurar las exclusiones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crear`.graphifyignore`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extraer el Knowledge Graph</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Generar los diagramas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Committer los resultados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trampas_y_mitigaciones">Trampas y mitigaciones</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Trampa</th> <th class="tableblock halign-left valign-top">Descripción</th> <th class="tableblock halign-left valign-top">Mitigación</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo muy denso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un proyecto grande genera cientos de nodos ilegibles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">usar`-Pplantuml.kg.maxNodes=30`y filtrar por comunidad</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Exclusiones demasiado amplias</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Demasiados archivos en`.graphifyignore`reduce el valor del grafo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comenzar por excluir solo credentials y build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dirección de las flechas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Las aristas INFERRED pueden tener una dirección ambigua</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar por`-Pplantuml.kg.edgeTypes=EXTRACTED`para las relaciones ciertas únicamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo obsoleto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El código cambia pero el grafo no se reconstruye</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar`graphify . --update`régulièrement o el hook git`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo actualizado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Las actualizaciones incrementales son casi gratuitas (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sólo las docs (<code>.adoc</code>) consumen tokens LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lo_que_se_obtiene_al_final">Lo que se obtiene al final</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Diagramas dibujados a mano\nSiempre obsoletos\nNadie los actualiza" as av1 #FDEDEC } rectangle "Después" as apres { card "Diagramas generados automáticamente Siempre actualizado con el código ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Diagramas dibujados a mano\nSiempre obsoletos\nNadie los actualiza" as av1 #FDEDEC } rectangle "Después" as apres { card "Diagramas generados automáticamente Siempre actualizado con el código Versionados en Git Deterministas y reproducibles" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>Los beneficios concretos :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Beneficio</th> <th class="tableblock halign-left valign-top">Detalle</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentación siempre actualizada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los diagramas reflejan el código actual, no una instantánea manual</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero esfuerzo de mantenimiento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los diagramas se regeneran en cada build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reducción de la deuda técnica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No es necesario mantener los diagramas a mano</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexto visual para los nuevos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un nuevo desarrollador entiende la arquitectura mirando los diagramas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ajuste fino potencial</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los pares (subgrafo → diagrama) son ejemplos de entrenamiento de IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validación automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`verifica cada diagrama generado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Onboarding rápido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5 diagramas = vista completa de la arquitectura</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ El que tiene un _por qué</em> puede soportar todos los <em>cómo</em>. </em>__</p> </div> <div class="paragraph"> <p>El <em>por qué</em>: diagramas siempre actualizados. El <em>cómo</em>: dos comandos en un pipeline Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_enlaces">Enlaces</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify en GitHub</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">Plugin Gradle de PlantUML</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">Los mejores trucos del comando fg</a>— artículo anterior sobre el flujo de trabajo del terminal</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/pilot-batch/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/pilot-batch/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_los_diagramas_siempre_están_por_detrás_del_código">El problema: los diagramas siempre están por detrás del código</a></li> <li><a href="#_la_solución_un_pipeline_determinista_knowledge_graph_plantuml">La solución: un pipeline determinista Knowledge Graph → PlantUML</a></li> <li><a href="#_paso_1_instalar_graphify_y_extraer_el_knowledge_graph">Paso 1: Instalar Graphify y extraer el Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_instalación">Instalación</a></li> <li><a href="#_configurar_las_exclusiones">Configurar las exclusiones</a></li> <li><a href="#_extraer_el_knowledge_graph">Extraer el Knowledge Graph</a></li> </ul> </li> <li><a href="#_paso_2_el_plugin_gradle_transforma_el_knowledge_graph_en_plantuml">Paso 2 : El plugin Gradle transforma el Knowledge Graph en PlantUML</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_del_pipeline">Arquitectura del pipeline</a></li> <li><a href="#_los_componentes_internos">Los componentes internos</a></li> <li><a href="#_reglas_de_renderizado">Reglas de renderizado</a></li> </ul> </li> <li><a href="#_paso_3_uso_diario">Paso 3: Uso diario</a> <ul class="sectlevel2"> <li><a href="#_diagrama_completo">diagrama completo</a></li> <li><a href="#_filtrar_por_comunidad">Filtrar por comunidad</a></li> <li><a href="#_filtrar_por_tipo_de_arista">Filtrar por tipo de arista</a></li> <li><a href="#_filtrar_por_tipo_de_nodo_y_confianza">Filtrar por tipo de nodo y confianza</a></li> <li><a href="#_directorio_de_salida_personalizado">Directorio de salida personalizado</a></li> <li><a href="#_referencia_completa_de_las_propiedades">Referencia completa de las propiedades</a></li> </ul> </li> <li><a href="#_el_pipeline_completo_en_un_flujo_de_trabajo_gradle">El pipeline completo en un flujo de trabajo Gradle</a> <ul class="sectlevel2"> <li><a href="#_tipo_de_flujo_de_trabajo">Tipo de flujo de trabajo</a></li> <li><a href="#_integración_en_el_ciclo_de_desarrollo">Integración en el ciclo de desarrollo</a></li> <li><a href="#_actualización_incremental">Actualización incremental</a></li> </ul> </li> <li><a href="#_el_dogfooding_el_plugin_se_documenta_a_sí_mismo">El dogfooding : el plugin se documenta a sí mismo</a></li> <li><a href="#_por_qué_es_determinista_y_por_qué_importa">¿Por qué es determinista (y por qué importa)?</a></li> <li><a href="#_diagramas_del_propio_pipeline">Diagramas del propio pipeline</a></li> <li><a href="#_integración_en_la_gobernanza_del_proyecto">Integración en la gobernanza del proyecto</a></li> <li><a href="#_preparación_checklist_en_5_minutos">Preparación: checklist en 5 minutos</a></li> <li><a href="#_trampas_y_mitigaciones">Trampas y mitigaciones</a></li> <li><a href="#_lo_que_se_obtiene_al_final">Lo que se obtiene al final</a></li> <li><a href="#_enlaces">enlaces</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>Tu base de código crece. Las dependencias entre módulos se multiplican. La documentación de la arquitectura se vuelve obsoleta antes incluso de estar escrita. ¿Y si tu build de Gradle pudiera <em>automáticamente</em> generar diagramas actualizados a partir de la estructura real del código? Eso es exactamente lo que hace el pipeline Graphify + Plugin Gradle PlantUML :`graphify . --no-viz`extrae el Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`lo transforma en diagramas PlantUML. Cero LLM, cero manual, 100% determinista.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[ ]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_los_diagramas_siempre_están_por_detrás_del_código">El problema: los diagramas siempre están por detrás del código</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo proyecto que supera algunos miles de líneas conoce este síndrome:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Se dibuja un diagrama de arquitectura al inicio del proyecto</p> </li> <li> <p>El código evoluciona, las dependencias cambian</p> </li> <li> <p>El diagrama se convierte en una mentira decorativa</p> </li> <li> <p>Nadie lo actualiza porque es tedioso</p> </li> <li> <p>Los recién llegados se basan en ello y cometen errores</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-diagrammes-obsoletes.svg" alt="probleme diagrammes obsoletes" width="824" height="418"> </div> </div> <div class="paragraph"> <p>La pregunta no es <em>¿es necesario tener diagramas?</em> — todo el mundo sabe que sí. La pregunta es :<strong>¿Quién los mantiene actualizados?</strong></p> </div> <div class="paragraph"> <p>La respuesta : nadie. Excepto si es automático.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_un_pipeline_determinista_knowledge_graph_plantuml">La solución: un pipeline determinista Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>El principio es simple : en lugar de dibujar los diagramas a mano, los<strong>genera desde la estructura real del código</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 11) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify\n(pip install graphifyy)" as Graphify collections "graphify-out/graph.json\n(Grafo de Conocimientos)" as KGJSON component "Complemento Gradle PlantUML\n(generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "Renderizador de KnowledgeGraph" as Renderer component "PlantumlService ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify\n(pip install graphifyy)" as Graphify collections "graphify-out/graph.json\n(Grafo de Conocimientos)" as KGJSON component "Complemento Gradle PlantUML\n(generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "Renderizador de KnowledgeGraph" as Renderer component "PlantumlService (validación + renderizado PNG)" as PS collections "diagrams/knowledge-graph/\n(.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : extrait la structure\ndu code source Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : code PlantUML\ndéterministe Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Pipeline DÉTERMINISTE Aucun appel LLM Résultat reproductible end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Dos comandos. Eso es todo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>¿El resultado? Archivos`.puml` et <code>.png`en`diagrams/knowledge-graph/</code>, versionados en Git, siempre actualizados con el código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_1_instalar_graphify_y_extraer_el_knowledge_graph">Paso 1: Instalar Graphify y extraer el Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_instalación">Instalación</h3> <div class="paragraph"> <p>Graphify es una herramienta de Python que analiza su codebase y construye un grafo de conocimiento estructurado:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_configurar_las_exclusiones">Configurar las exclusiones</h3> <div class="paragraph"> <p>Crear un archivo`.graphifyignore`en la raíz del proyecto para excluir los archivos que no forman parte de la lógica de negocio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_extraer_el_knowledge_graph">Extraer el Knowledge Graph</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>La bandera`--no-viz`Omite la generación HTML (inútil en un pipeline Gradle). El resultado es un archivo`graphify-out/graph.json`conteniendo :</p> </div> <div class="ulist"> <ul> <li> <p><strong>nudos</strong>: clases, funciones, archivos — con su tipo y comunidad</p> </li> <li> <p><strong>Aristas</strong>: relaciones entre nodos (EXTRACTED desde el código, INFERRED por el LLM)</p> </li> <li> <p><strong>Comunidades</strong>: agrupamientos automáticos de nodos vinculados</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Ejemplo de estructura`graph.json`</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>El código fuente (<code>.kt</code>, <code>.java</code>) se analiza localmente por tree-sitter,<strong>inapelable LLM</strong>. Sólo los archivos de documentación (<code>.adoc</code>, <code>.md</code>) requieren una llamada LLM para la extracción semántica. Así que`--update`sobre código Kotlin es casi instantáneo.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_2_el_plugin_gradle_transforma_el_knowledge_graph_en_plantuml">Paso 2 : El plugin Gradle transforma el Knowledge Graph en PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitectura_del_pipeline">Arquitectura del pipeline</h3> <div class="paragraph"> <p>El plugin`com.cheroliv.plantuml`incluye una tarea`generateKnowledgeGraphDiagram`que transforma`graph.json`en diagramas PlantUML de manera<strong>totalmente determinista</strong> :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1109" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_los_componentes_internos">Los componentes internos</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Componente</th> <th class="tableblock halign-left valign-top">rol</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Analizar`graph.json`— soporta 3 formatos : graphify nativo (<code>nodes</code>+<code>links</code>), legado (<code>communities</code>), plano. Resuelve los IDs numéricos en etiquetas.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforma deterministamente un`KnowledgeGraph`en código PlantUML. Grupos por tipo, comunidades en paquetes, leyenda automática.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tarea Gradle que orquesta: parse → render → validate → PNG. Configurable mediante propiedades Gradle.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelos de datos:`KnowledgeGraph`, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validación sintáctica + renderizado PNG (reutilizado por todas las tareas del plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_reglas_de_renderizado">Reglas de renderizado</h3> <div class="paragraph"> <p>El renderer aplica convenciones visuales deterministas:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Tipo de arista</th> <th class="tableblock halign-left valign-top">Notación PlantUML</th> <th class="tableblock halign-left valign-top">Significado</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">EXTRACTED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(línea continua, negro)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación extraída del código fuente (certeza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DEDUCIDO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(línea punteada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación inferida por el LLM (puntuación de confianza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBIGUOUS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(línea roja punteada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relación ambigua (por verificar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Las comunidades se representan como paquetes PlantUML con una paleta de colores automática.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_3_uso_diario">Paso 3: Uso diario</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_completo">diagrama completo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Salida :`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_comunidad">Filtrar por comunidad</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_tipo_de_arista">Filtrar por tipo de arista</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_tipo_de_nodo_y_confianza">Filtrar por tipo de nodo y confianza</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_directorio_de_salida_personalizado">Directorio de salida personalizado</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_referencia_completa_de_las_propiedades">Referencia completa de las propiedades</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Propiedad</th> <th class="tableblock halign-left valign-top">Defecto</th> <th class="tableblock halign-left valign-top">Descripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(todas)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar las comunidades por nombre (coincidencia de subcadena)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(todos)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de aristas separados por comas :`EXTRACTED`, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Umbral mínimo de confianza para las aristas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(ilimitado)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Número máximo de nodos a mostrar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(todos)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de nodos separados por comas (ej.<code>class</code>, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directorio de salida para los archivos`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_pipeline_completo_en_un_flujo_de_trabajo_gradle">El pipeline completo en un flujo de trabajo Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tipo_de_flujo_de_trabajo">Tipo de flujo de trabajo</h3> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet.svg" alt="workflow complet" width="618" height="714"> </div> </div> </div> <div class="sect2"> <h3 id="_integración_en_el_ciclo_de_desarrollo">Integración en el ciclo de desarrollo</h3> <div class="paragraph"> <p>El pipeline se integra naturalmente en las etapas clave del desarrollo:</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE state "Desarrollo" as dev state "Extracción\ngraphify . --no-viz" as extract state "Generación ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE state "Desarrollo" as dev state "Extracción\ngraphify . --no-viz" as extract state "Generación ./gradlew generateKnowledgeGraphDiagram" as generate state "Commit\ndiagramas versionados" as commit [*] --> dev dev --> extract : Code modifié extract --> generate : graph.json à jour generate --> commit : .puml + .png générés commit --> dev : Diagrammes dans le repo note right of extract Quasi instantané sur du code Kotlin (tree-sitter, pas de LLM) end note note right of generate Déterministe Pas de LLM Résultat reproductible end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_actualización_incremental">Actualización incremental</h3> <div class="paragraph"> <p>Cuando el código cambia, no se reconstruye todo el grafo desde cero:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update`reextrae únicamente los archivos modificados (detectados por SHA256 en`graphify-out/cache/</code>). En código Kotlin, es casi instantáneo porque tree-sitter trabaja localmente sin llamada a LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_dogfooding_el_plugin_se_documenta_a_sí_mismo">El dogfooding : el plugin se documenta a sí mismo</h2> <div class="sectionbody"> <div class="paragraph"> <p>El plugin PlantUML existe para transformar prompts en diagramas. También puede transformar el Knowledge Graph de su <em>propre</em> codebase en diagramas de documentación. Es <em>dogfooding</em>: el plugin consume su propio servicio.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal (usuario → diagramas)" as normal { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal (usuario → diagramas)" as normal { [Fichier .prompt] as prompt [LlmService\n+ ApiKeyPool] as llm1 [ProcessPlantumlPromptsTask] as task1 [Diagramme PNG] as out1 prompt --> task1 task1 --> llm1 llm1 --> out1 } package "Pipeline Knowledge Graph\n(determinista, sin LLM)" as kg { [graphify-out/graph.json] as kgjson [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantumlService] as ps [Diagramme PNG\n(documentation du plugin)] as out2 kgjson --> parser parser --> renderer renderer --> ps ps --> out2 } package "Pipeline Dogfooding\n(LLM → documentación del plugin)" as dogfood { [GraphifyPromptAdapter] as gpa [Fichiers .prompt\nauto-générés] as auto_prompt [LlmService\n+ ApiKeyPool] as llm2 [ProcessPlantumlPromptsTask] as task2 [Diagramme PNG\n(documentation LLM)] as out3 kgjson --> gpa gpa --> auto_prompt auto_prompt --> task2 task2 --> llm2 llm2 --> out3 } note "Incluso LlmService, incluso ApiKeyPool, incluso PlantumlService — CERO duplicación" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>Tareas Gradle asociadas :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">tarea</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Descripción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforma`graph.json`en PlantUML (determinista)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Genera de`.prompt`desde el grafo, los trata a través de LLM (dogfooding)</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_es_determinista_y_por_qué_importa">¿Por qué es determinista (y por qué importa)?</h2> <div class="sectionbody"> <div class="paragraph"> <p>El punto clave del pipeline`generateKnowledgeGraphDiagram`:<strong>Él no llama ningún LLM</strong>. La transformación`graph.json`PlantUML es una función pura.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline DETERMINISTA (generateKnowledgeGraphDiagram)" as det { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline DETERMINISTA (generateKnowledgeGraphDiagram)" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "Canalización LLM\n(procesarPlantumlPrompts)" as llm { [.prompt] as prompt [LlmService] as llmSvc [ChatModel] as model [PlantUML code] as puml2 prompt --> llmSvc llmSvc --> model : API call model --> puml2 : réponse non-déterministe } note bottom of det Même entrée → même sortie Pas de latence réseau Pas de coût en tokens Reproductible en CI end note note bottom of llm Même entrée → sortie variable Latence réseau (1-5s) Coût en tokens Nécessite une clave API end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Los beneficios concretos:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ventaja</th> <th class="tableblock halign-left valign-top">Impacto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reproducibilidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">incluso`graph.json`→ mismo diagrama. Exactamente. Todas las veces.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo cero</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sin llamada LLM = sin tokens = sin factura API</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero latencia</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render tarda ~100ms, no 1-5 segundos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatible con CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No se necesita una clave API. No hay prueba inestable debido a una respuesta variable del LLM.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Versionable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`generado es texto. Podemos lo`diff</code>, el revisor en PR, versionarlo en Git</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagramas_del_propio_pipeline">Diagramas del propio pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para cerrar el ciclo, aquí tienes el diagrama del pipeline tal como sería generado por el plugin :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1750" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integración_en_la_gobernanza_del_proyecto">Integración en la gobernanza del proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>En nuestro proyecto, este pipeline se integra en una estrategia de gestión de contexto EAGER/LAZY para el agente IA. El Knowledge Graph reemplaza la documentación de arquitectura manual por un grafo estructurado, consultable y autoactualizado.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 16) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(siempre cargado)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Estrategia\n(a petición)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(siempre cargado)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Estrategia\n(a petición)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (consultas específicas)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML\n(generado automáticamente)" as puml { [generateKnowledgeGraphDiagram] as kgTask [generateDiagramDocs] as ddTask [Diagrammes PNG] as diagrams } Agent --> eager : Lit en début de session Agent ..> lazy_strat : Charge si type détecté Agent ..> lazy_graph : Query si besoin structurel kgTask --> diagrams : Déterministe ddTask --> diagrams : Via LLM note right of gr Condensé du Knowledge Graph God nodes + communautés Remplace ECOSYSTEM_OVERVIEW (225 lignes → 50 lignes) end note @enduml</pre> </div> </div> <div class="paragraph"> <p>El matrimonio de los dos sistemas es complementario :</p> </div> <div class="ulist"> <ul> <li> <p><strong>La estrategia gestiona el CUÁNDO y el CÓMO</strong>— gobernanza, workflow, archivado</p> </li> <li> <p><strong>Graphify gestiona el QUOI y el OÙ</strong>estructura del código, relaciones, consultas dirigidas</p> </li> </ul> </div> <div class="paragraph"> <p><em>__</em> La estrategia de sesión gestiona el<strong>CUANDO</strong> et le <strong>CÓMO</strong>(gobernanza, flujo de trabajo, umbrales), Graphify gestiona el<strong>qué</strong> et le <strong>DÓNDE</strong>(estructura del código, relaciones, consultas específicas). El pipeline PlantUML gestiona el<strong>CON QUÉ</strong>(diagramas deterministas, versionados, siempre actualizados). (No output needed because no source text provided.)</p> </div> </div> </div> <div class="sect1"> <h2 id="_preparación_checklist_en_5_minutos">Preparación: checklist en 5 minutos</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Etapa</th> <th class="tableblock halign-left valign-top">Orden</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Instalar Graphify</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configurar las exclusiones</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crear`.graphifyignore`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extraer el Knowledge Graph</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Generar los diagramas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confirmar los resultados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trampas_y_mitigaciones">Trampas y mitigaciones</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Trampa</th> <th class="tableblock halign-left valign-top">Descripción</th> <th class="tableblock halign-left valign-top">Mitigación</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo demasiado denso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un gran proyecto genera cientos de nodos ilegibles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar`-Pplantuml.kg.maxNodes=30`et filtrar por comunidad</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">exclusiones demasiado amplias</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Demasiados archivos en`.graphifyignore`reduce el valor del grafo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comenzar por excluir solo credentials y build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dirección de las flechas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Las aristas INFERRED pueden tener una dirección ambigua</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar por`-Pplantuml.kg.edgeTypes=EXTRACTED`Solo para las relaciones ciertas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo obsoleto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El código cambia pero el grafo no se reconstruye</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">usar`graphify . --update`regularmente o el hook git`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo actualizado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Las actualizaciones incrementales son prácticamente gratuitas (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sólo los docs (<code>.adoc</code>) consumen tokens LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lo_que_se_obtiene_al_final">Lo que se obtiene al final</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Diagramas dibujados a mano\nSiempre obsoletos\nNadie los actualiza" as av1 #FDEDEC } rectangle "DESPUÉS" as apres { card "Diagramas generados automáticamente Siempre actualizados con el código ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Diagramas dibujados a mano\nSiempre obsoletos\nNadie los actualiza" as av1 #FDEDEC } rectangle "DESPUÉS" as apres { card "Diagramas generados automáticamente Siempre actualizados con el código Versionados en Git Deterministas y reproducibles" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>Los beneficios concretos:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Beneficio</th> <th class="tableblock halign-left valign-top">Detalle</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentación siempre actualizada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los diagramas reflejan el código actual, no una instantánea manual</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero esfuerzo de mantenimiento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los diagramas se regeneran en cada compilación</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reducción de la deuda técnica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ya no es necesario mantener los diagramas a mano</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexto visual para los nuevos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un nuevo desarrollador comprende la arquitectura mirando los diagramas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">potencial de ajuste fino</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Los pares (subgrafo → diagrama) son ejemplos de entrenamiento IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validación automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`verifica cada diagrama generado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Onboarding rápido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5 diagramas = vista completa de la arquitectura</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>__</em> El que tiene un <em>por qué</em> puede soportar todos los <em>cómo</em>. </think></p> </div> <div class="paragraph"> <p>El <em>porqué</em> : diagramas siempre actualizados. El <em>cómo</em> : dos comandos en un pipeline de Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_enlaces">enlaces</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify en GitHub</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">PlantUML Gradle Plugin</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">Los super tips del comando fg</a>— artículo anterior sobre el flujo de trabajo terminal</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0104_fg_command_super_tips_post.html Sat, 18 Apr 2026 00:00:00 +0000 blog/2026/0104_fg_command_super_tips_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_el_problema_un_terminal_ocupado">El problema: un terminal ocupado</a></li> <li><a href="#_los_tres_comandos_indispensables">Los tres comandos indispensables</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_suspender_sigtstp">Ctrl+Z — Suspender (SIGTSTP)</a></li> <li><a href="#_fg_traer_al_primer_plano">fg — Traer al primer plano</a></li> <li><a href="#_bg_reanudar_en_segundo_plano">bg — Reanudar en segundo plano</a></li> <li><a href="#_jobs_listar_los_trabajos_del_shell">jobs — Listar los trabajos del shell</a></li> </ul> </li> <li><a href="#_escenario_1_el_build_largo">Escenario 1: El build largo</a> <ul class="sectlevel2"> <li><a href="#_paso_a_paso">Paso a paso</a></li> </ul> </li> <li><a href="#_escenario_2_el_editor_olvidado">Escenario 2: El editor olvidado</a></li> <li><a href="#_escenario_3_el_proceso_opencode_suspendido">Escenario 3: El proceso opencode suspendido</a></li> <li><a href="#_escenario_4_gestionar_varios_trabajos_simultáneamente">Escenario 4: Gestionar varios trabajos simultáneamente</a> <ul class="sectlevel2"> <li><a href="#_resumen_de_los_comandos_de_trabajos">Resumen de los comandos de trabajos</a></li> </ul> </li> <li><a href="#_diferencias_entre_fg_bg_ctrlz_ctrlc_y">Diferencias entre fg, bg, Ctrl+Z, Ctrl+C y &</a></li> <li><a href="#_el_ciclo_de_vida_completo_de_un_trabajo">El ciclo de vida completo de un trabajo</a></li> <li><a href="#_consejos_avanzados">Consejos avanzados</a> <ul class="sectlevel2"> <li><a href="#_fg_con_el_trabajo_más_reciente_y_la_alternancia">fg con el trabajo más reciente y la alternancia</a></li> <li><a href="#_matar_un_trabajo_de_forma_limpia">matar un trabajo de forma limpia</a></li> <li><a href="#_désown_desanclar_del_shell">désown : desanclar del shell</a></li> <li><a href="#_combinar_con_nohup_para_procesos_largos">Combinar con nohup para procesos largos</a></li> </ul> </li> <li><a href="#_trampas_y_errores_comunes">Trampas y errores comunes</a> <ul class="sectlevel2"> <li><a href="#_confundir_ctrlz_y_ctrlc">Confundir Ctrl+Z y Ctrl+C</a></li> <li><a href="#_los_trabajos_son_locales_al_shell">Los trabajos son locales al shell</a></li> <li><a href="#_los_trabajos_no_sobreviven_al_cierre_del_shell">Los trabajos no sobreviven al cierre del shell</a></li> <li><a href="#_los_procesos_interactivos_y_fg">Los procesos interactivos y fg</a></li> </ul> </li> <li><a href="#_diagrama_resumido">Diagrama resumido</a></li> <li><a href="#_por_qué_fg_está_subestimado">¿Por qué fg está subestimado</a></li> <li><a href="#_memoria_técnica_las_señales">Memoria técnica: las señales</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 10 minutes</div> <p>Lanzas`./gradlew build`, el terminal está bloqueado durante 3 minutos, y necesitas hacer otra cosa <em>mientras esperas</em>? No es necesario abrir una nueva pestaña.`Ctrl+Z`suspende el proceso,`fg`Lo lleva exactamente donde lo dejaste. Es el tip de Unix más subestimado del día a día de un desarrollador.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_un_terminal_ocupado">El problema: un terminal ocupado</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo desarrollador ha conhecido esta situación:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building...</code></pre> </div> </div> <div class="paragraph"> <p>El terminal está bloqueado. No puedes escribir ningún comando. Y necesitas consultar un archivo, lanzar un`git status`, o comprobar un puerto ocupado.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Terminal" as term participant "Gradle ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Terminal" as term participant "Gradle ( proceso )" as gradle dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> term : Occupe le terminal\n(pas de prompt) dev -> term : veut taper une commande term --> dev : ❌ Terminal bloqué note right of dev Le développeur est paralysé pendant toute la durée du build end note @enduml</pre> </div> </div> <div class="paragraph"> <p>La mayoría de los desarrolladores abren una nueva terminal. Pero existe una solución más elegante, más rápida y nativa: la gestión de los trabajos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_los_tres_comandos_indispensables">Los tres comandos indispensables</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_suspender_sigtstp">Ctrl+Z — Suspender (SIGTSTP)</h3> <div class="paragraph"> <p>`Ctrl+Z`envía la señal`SIGTSTP`al proceso en primer plano. El proceso es<strong>suspendido</strong>— no matado — y el terminal recupera su prompt.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $</code></pre> </div> </div> <div class="paragraph"> <p>El número entre corchetes`[1]`es el<strong>número de trabajo</strong>. Le `+`indica el trabajo por defecto.</p> </div> </div> <div class="sect2"> <h3 id="_fg_traer_al_primer_plano">fg — Traer al primer plano</h3> <div class="paragraph"> <p>`fg`Lleva el trabajo suspendido al primer plano. El proceso continúa exactamente donde se había detenido.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg ./gradlew build > Building... (reprend où il en était)</code></pre> </div> </div> <div class="paragraph"> <p>Con un número de trabajo específico :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg %2</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_bg_reanudar_en_segundo_plano">bg — Reanudar en segundo plano</h3> <div class="paragraph"> <p>`bg`reanuda el proceso <em>sin</em> bloquear el terminal. Ideal para las builds largas.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ bg [1]+ ./gradlew build & $</code></pre> </div> </div> <div class="paragraph"> <p>Le `&`al final significa que el proceso se ejecuta en segundo plano.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_listar_los_trabajos_del_shell">jobs — Listar los trabajos del shell</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim README.md [2]+ En cours ./gradlew build</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primer plano\n(terminal bloqueado)" as fg #LightCoral state "Suspendido ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primer plano\n(terminal bloqueado)" as fg #LightCoral state "Suspendido (Ctrl+Z)" as stopped #LightYellow state "Fondo\n(bg)" as bg_ #LightGreen [*] --> fg : Lance une commande fg --> stopped : Ctrl+Z\n(SIGTSTP) stopped --> fg : fg\nreprend en avant-plan stopped --> bg_ : bg\nreprend en arrière-plan bg_ --> fg : fg\nramène en avant-plan fg --> [*] : Commande terminée note right of stopped Le processus est figé mais _pas_ tué end note note left of bg_ Le terminal est libre le build continue end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_escenario_1_el_build_largo">Escenario 1: El build largo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Es el caso de uso más común. Ejecutas una compilación de Gradle, el terminal queda bloqueado y necesitas hacer otra cosa.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "Terminal" as term participant "Gradle" as gradle database "Estado ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "Terminal" as term participant "Gradle" as gradle database "Estado proceso" as state dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> state : En cours (FG) dev -> term : Ctrl+Z term -> state : Suspendu (job [1]) term --> dev : Prompt libre $ dev -> term : git status term --> dev : working tree clean dev -> term : fg term -> state : Reprend (FG) gradle --> dev : Build réussi ✓ note right of state Le processus Gradle n'a jamais été tué Il reprend exactement où il s'était arrêté end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_paso_a_paso">Paso a paso</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $ git status On branch main nothing to commit, working tree clean $ fg ./gradlew build > Building... BUILD SUCCESSFUL in 2m 34s</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_escenario_2_el_editor_olvidado">Escenario 2: El editor olvidado</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estás en`vim`, necesitas consultar otro archivo <em>sin</em> salir`vim`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, en mode commande : :shell $ cat /path/to/other/file.txt $ exit # Retour dans vim</code></pre> </div> </div> <div class="paragraph"> <p>Pero es pesado. Con`Ctrl+Z`, es inmediato :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, n'importe quel moment : Ctrl+Z [1]+ Stoppé vim README.md $ cat /path/to/other/file.txt # ... lire le fichier ... $ fg vim README.md # Retour exact là où on en était, curseur en place</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/vim-suspend.svg" alt="vim suspend" width="420" height="510"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_escenario_3_el_proceso_opencode_suspendido">Escenario 3: El proceso opencode suspendido</h2> <div class="sectionbody"> <div class="paragraph"> <p>Es el escenario que motivó este artículo. Usted utiliza`opencode`(herramienta CLI para controlar un LLM en tu código), y el proceso está suspendido.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam componentStyle rectangle actor Développeur as dev participant "opencode ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam componentStyle rectangle actor Développeur as dev participant "opencode (LLM agente)" as agent participant "Shell" as shell participant "git" as git dev -> agent : Session active agent -> agent : Tour de parole\ndu LLM en cours note over agent Ctrl+Z arrive en plein milieu d'une analyse de code end note dev -> agent : Ctrl+Z agent -> shell : Suspendu (job [1]) dev -> git : git diff git --> dev : changements visibles dev -> shell : fg shell -> agent : Reprend (job [1]) agent --> dev : Reprend exactement\nl'analyse en cours note right of agent Aucune perte de contexte Le LLM reprend sa réponse exactement où il en était end note @enduml</pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode # ... session en cours, LLM analyse le code ... ^Z [1]+ Stoppé opencode $ git diff HEAD~1 # vérifier les changements récents $ fg opencode # Le LLM reprend là où il s'était arrêté</code></pre> </div> </div> <div class="paragraph"> <p>La ventaja es doble:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Sin pérdida de contexto</strong>: la sesión LLM, el historial de conversación, los archivos abiertos — todo está preservado</p> </li> <li> <p><strong>Sin reinicio</strong>: no es necesario volver a ejecutar opencode, recargar el contexto, volver a explicar el problema al LLM</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_escenario_4_gestionar_varios_trabajos_simultáneamente">Escenario 4: Gestionar varios trabajos simultáneamente</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et `bg`aceptan un número de trabajo para dirigirse a un proceso específico cuando varios están suspendidos.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim config.yml ^Z [1]+ Stoppé vim config.yml $ ./gradlew test ^Z [2]+ Stoppé ./gradlew test $ htop ^Z [3]+ Stoppé htop $ jobs [1] Stoppé vim config.yml [2]- Stoppé ./gradlew test [3]+ Stoppé htop $ fg %2 ./gradlew test # Le build reprend en avant-plan $ bg %3 [3] htop & # htop reprend en arrière-plan</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/multiple-jobs.svg" alt="multiple jobs" width="750" height="280"> </div> </div> <div class="sect2"> <h3 id="_resumen_de_los_comandos_de_trabajos">Resumen de los comandos de trabajos</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Orden</th> <th class="tableblock halign-left valign-top">Efecto</th> <th class="tableblock halign-left valign-top">Ejemplo</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suspenda el proceso en primer plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Envío de`SIGTSTP`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reanuda el trabajo predeterminado en primer plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> ou <code>fg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reanuda el trabajo n en primer plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reanuda el trabajo predeterminado en segundo plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code> ou <code>bg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reanuda el trabajo n en segundo plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Enumera los trabajos del shell actual</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code>(con PID)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Termina el trabajo n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %2</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_diferencias_entre_fg_bg_ctrlz_ctrlc_y">Diferencias entre fg, bg, Ctrl+Z, Ctrl+C y &</h2> <div class="sectionbody"> <div class="paragraph"> <p>Muchos desarrolladores confunden estos mecanismos. Aquí tienes una aclaración decisiva.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Suspende el proceso\n(todavía está en memoria)\nUtilizable con fg/bg" as c1 } rectangle "**Ctrl+C** SIGINT" as ctrlc #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Suspende el proceso\n(todavía está en memoria)\nUtilizable con fg/bg" as c1 } rectangle "**Ctrl+C** SIGINT" as ctrlc #LightCoral { card "Finaliza el proceso (sin posibilidad de retorno) Pérdida de todo el estado" as c2 } rectangle "** & \n(fondo)" as ampersand #LightGreen { card "Inicia directamente en segundo plano Terminal libre inmediatamente" as c3 } rectangle "**fg**\n(primer plano)" as fg_ #SkyBlue { card "Trae un trabajo suspendido en primer plano Terminal ocupado" as c4 } rectangle "**bg** (fondo)" as bg_ #Lavender { card "Reanuda un trabajo suspendido en segundo plano Terminal libre" as c5 } ctrlz -right-> fg_ : fg pour reprendre ctrlz -right-> bg_ : bg pour continuer\nen arrière-plan ctrlc -right-> c2 : Pas de retour\nprocessus tué note bottom of ctrlz Le processus est **figé** mais **pas tué** end note note bottom of ampersand Alternative : lancer ./gradlew build & directement en arrière-plan end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 33.3333%;"> <col style="width: 16.6666%;"> <col style="width: 33.3335%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Atajo/Comando</th> <th class="tableblock halign-left valign-top">Señal</th> <th class="tableblock halign-left valign-top">Efecto</th> <th class="tableblock halign-left valign-top">¿Volver atrás?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suspender el proceso (congelado, en memoria)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí :`fg` ou <code>bg</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mata el proceso (terminado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No: proceso destruido</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mata el proceso + core dump</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No : proceso destruido</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commande &</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lanza en segundo plano directamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`fg`para llevarlo al primer plano</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <code>Ctrl+Z`es<strong>no destructivo</strong>. El proceso está congelado tal cual, en memoria. Puede continuar inmediatamente con`fg</code>. Es un <em>pause</em>, no un <em>stop</em>. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_ciclo_de_vida_completo_de_un_trabajo">El ciclo de vida completo de un trabajo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title Ciclo de vida completo de un trabajo shell state "Inexistente" as none state "Primer plano\n(ocupa la terminal)" as foreground #LightCoral state "Suspendido ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title Ciclo de vida completo de un trabajo shell state "Inexistente" as none state "Primer plano\n(ocupa la terminal)" as foreground #LightCoral state "Suspendido (Ctrl+Z / SIGTSTP)" as suspended #LightYellow state "Fondo (bg o &)" as background #LightGreen state "Terminado (exit code 0)" as done #LightGray [*] --> none none --> foreground : tape une commande foreground --> suspended : Ctrl+Z foreground --> done : fin normale suspended --> foreground : fg suspended --> background : bg suspended --> done : kill %n background --> foreground : fg background --> done : fin normale\n(en arrière-plan) background --> suspended : Ctrl+Z\n(si fg puis Ctrl+Z) done --> [*] note right of suspended L'état suspendu est le pivot de tout le système de jobs end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_consejos_avanzados">Consejos avanzados</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg_con_el_trabajo_más_reciente_y_la_alternancia">fg con el trabajo más reciente y la alternancia</h3> <div class="paragraph"> <p><code>fg`Sin argumento trae el trabajo marcado.</code>+<code>(el más reciente). Pero también puedes usar</code>%-`Para apuntar al trabajo anterior</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim file1.txt ^Z [1]+ Stoppé vim file1.txt $ vim file2.txt ^Z [2]+ Stoppé vim file2.txt $ fg # ramène job [2] (le plus récent) $ fg %- # ramène job [1] (le précédent)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_matar_un_trabajo_de_forma_limpia">matar un trabajo de forma limpia</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim config.yml [2]+ Stoppé ./gradlew test $ kill %2 # envoie SIGTERM au job 2 $ kill -9 %1 # envoie SIGKILL au job 1 (force)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_désown_desanclar_del_shell">désown : desanclar del shell</h3> <div class="paragraph"> <p><code>disown`Elimina un trabajo de la tabla de trabajos del shell. El proceso sigue ejecutándose pero ya no puede ser recuperado con`fg</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build & [1] 12345 $ disown %1 # Le processus continue mais n'est plus lié au shell # Ça survives à la fermeture du terminal</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_combinar_con_nohup_para_procesos_largos">Combinar con nohup para procesos largos</h3> <div class="paragraph"> <p>Para que un proceso sobreviva al cierre del terminal :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Le build continue même si vous fermez le terminal</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "fg" as fg_ #SkyBlue { card "Trae el trabajo\nel más reciente (+)" as f1 card "Apunta a un trabajo específico : fg %n" as f2 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "fg" as fg_ #SkyBlue { card "Trae el trabajo\nel más reciente (+)" as f1 card "Apunta a un trabajo específico : fg %n" as f2 card "Alterna : fg %-" as f3 } rectangle "matar %n" as kill_ #LightCoral { card "SIGTERM (limpio)" as k1 card "SIGKILL -9 (fuerza)" as k2 } rectangle "renegar" as disown #Lavender { card "Desvincular del shell (sobrevive a la desconexión)" as d1 } rectangle "nohup + &" as nohup_ #LightGreen { card "Proceso inmunizado contra SIGHUP (sobrevive al cierre del terminal)" as n1 } fg_ -right-> kill_ : si faut\nterminer kill_ -right-> disown_ : ou détacher nohup_ -left-> fg_ : fg ramène en\navant-plan note bottom of disown_ Après disown, fg ne peut plus ramener le job end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trampas_y_errores_comunes">Trampas y errores comunes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_confundir_ctrlz_y_ctrlc">Confundir Ctrl+Z y Ctrl+C</h3> <div class="paragraph"> <p>Es el error más frecuente.`Ctrl+C`mata el proceso.`Ctrl+Z`lo suspende. Si lo presiona`Ctrl+C`por reflejo, todo el estado se pierde — archivos abiertos, sesiones LLM, builds en curso.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/ctrlz-vs-ctrlc.svg" alt="ctrlz vs ctrlc" width="1218" height="129"> </div> </div> </div> <div class="sect2"> <h3 id="_los_trabajos_son_locales_al_shell">Los trabajos son locales al shell</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et `bg`solo funcionan en el shell que lanzó los procesos. Si abre un nuevo terminal, no verá los trabajos del otro.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Terminal 1 $ vim file.txt ^Z [1]+ Stoppé vim file.txt # Terminal 2 (nouveau) $ jobs # (rien — les jobs sont locaux au shell)</code></pre> </div> </div> <div class="paragraph"> <p>Para ver los procesos system-wide, utilice`ps` ou <code>htop</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ps aux | grep vim</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_los_trabajos_no_sobreviven_al_cierre_del_shell">Los trabajos no sobreviven al cierre del shell</h3> <div class="paragraph"> <p>Si cierras el terminal, todos los trabajos suspendidos o en segundo plano son destruidos. Para que un proceso sobreviva, utilice`nohup`+<code>disown</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Fermer le terminal → le build continue</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_los_procesos_interactivos_y_fg">Los procesos interactivos y fg</h3> <div class="paragraph"> <p>Algunos programas interactivos no funcionan bien después de un`Ctrl+Z`+<code>fg</code>. Es raro pero ocurre :</p> </div> <div class="ulist"> <ul> <li> <p>Algunos programas que utilizan señales (vim, htop, less manejan bien`Ctrl+Z`)</p> </li> <li> <p>Los programas de red de larga duración (ssh, opencode) generalmente se recuperan correctamente</p> </li> <li> <p>Los programas que modifican el terminal (ncurses) pueden a veces dejar el terminal en un estado inesperado</p> </li> </ul> </div> <div class="paragraph"> <p>En caso de terminal corrupto después de un`fg`, escriba :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">reset</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrama_resumido">Diagrama resumido</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "fg — El consejo que cambia todo" rectangle "Problema" as problem #LightCoral { card "Terminal bloqueado por un proceso" as p1 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "fg — El consejo que cambia todo" rectangle "Problema" as problem #LightCoral { card "Terminal bloqueado por un proceso" as p1 card "Abrir un nuevo terminal = solución pesada" as p2 } rectangle "**Solución**" as solution #LightGreen { card "Ctrl+Z → suspender" as s1 card "fg → retoma" as s2 card "bg → en segundo plano" as s3 card "jobs → ver los suspendidos" as s4 } rectangle "Ventajas" as advantages #SkyBlue { card "Sin pérdida de contexto" as a1 card "No reinicio" as a2 card "Un solo terminal basta" as a3 } problem -right-> solution : "La solución nativa\nUnix desde hace 40 años" solution -right-> advantages : "Resultado" note bottom of advantages fg n'est pas un tips obscur C'est un mécanisme fondamental du shell Unix end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_fg_está_subestimado">¿Por qué fg está subestimado</h2> <div class="sectionbody"> <div class="paragraph"> <p>La mayoría de los desarrolladores modernos descubren`fg`tarde, o incluso nunca. Algunas razones :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Los IDE ocultan la terminal</strong>: VS Code ofrece un terminal integrado, pero las pestañas múltiples hacen`fg`menos necesario en apariencia</p> </li> <li> <p><strong>Las herramientas gráficas reemplazan a la CLI</strong>: los gestores de archivos, los monitores del sistema, los clientes gráficos de Git</p> </li> <li> <p><strong>tmux y screen</strong>: estos multiplexores resuelven el mismo problema de manera diferente, pero`fg`es más simple y siempre disponible</p> </li> </ol> </div> <div class="paragraph"> <p>Pero,`fg`es :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>universal</strong>: presente en todos los shells POSIX (bash, zsh, fish…​)</p> </li> <li> <p><strong>Sin dependencia</strong>: no es necesario instalar tmux o screen</p> </li> <li> <p><strong>Instantáneo</strong>: dos golpes (<code>Ctrl+Z`luego`fg</code>) para suspender y reanudar</p> </li> <li> <p>**Preservador de contexto</p> </li> </ol> </div> <div class="paragraph"> <p>Wait that’s wrong: Should be "Preservador de contexto". Let’s output exactly that.</p> </div> <div class="paragraph"> <p></think></p> </div> <div class="paragraph"> <p>Preservador de contexto**: el estado del proceso está intacto</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "¿Por qué fg está subestimado?" as why #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "¿Por qué fg está subestimado?" as why #LightCoral { card "IDE con terminal\nmultipestañas" as w1 card "Herramientas gráficas que sustituyen la CLI" as w2 card "tmux/screen resuelven el problema de otra manera" as w3 } rectangle "¿Por qué fg es superior?" as superior #LightGreen { card "Universal: bash,\nzsh, fish, sh..." as s1 card "Sin dependencia: Sin instalación" as s2 card "Dos pulsaciones:\nCtrl+Z luego fg" as s3 card "Contexto preservado:\ncero pérdida de estado" as s4 } why -right-> superior : "La simplicidad siempre gana" @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_memoria_técnica_las_señales">Memoria técnica: las señales</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para los curiosos, aquí están las señales implicadas:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 14.2857%;"> <col style="width: 28.5714%;"> <col style="width: 28.5714%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">señal</th> <th class="tableblock halign-left valign-top">Nombre</th> <th class="tableblock halign-left valign-top">Enviado por</th> <th class="tableblock halign-left valign-top">Efecto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Interrupción — termina el proceso</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sale con volcado de núcleo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">18</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parada interactiva — suspende el proceso</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">19</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGCONT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code>/<code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Continúa — reanuda un proceso suspendido</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTERM</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">terminación limpia</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGKILL</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill -9 %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Finalización forzada (imposible de interceptar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>El flujo completo:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signal-flow.svg" alt="signal flow" width="425" height="525"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>`fg`No es un consejo oscuro — es un mecanismo fundamental del shell Unix, disponible desde los años 70. El hecho de que la mayoría de los desarrolladores lo ignoren es un síntoma de nuestra época: los IDE y los multiplexores nos han alejado de lo básico.</p> </div> <div class="paragraph"> <p>Pero cuando estás en un servidor SSH, en una terminal mínima, o simplemente estás utilizando`opencode`y que el LLM está en pleno trabajo —<code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, `jobs`son tus mejores amigos.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z suspend, fg reanuda. Es la pausa-reproducción del terminal. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code>— sección JOB CONTROL</p> </li> <li> <p><code>man signal</code>— lista de las señales POSIX</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Manual de referencia de Bash — Control de trabajos</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 señal — señales Linux</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">Guía avanzada de scripting de Bash — Control de trabajos</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0103_vscode_local_install_custom_fonts_post.html Fri, 17 Apr 2026 00:00:00 +0000 blog/2026/0103_vscode_local_install_custom_fonts_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_visión_general_del_recorrido">Visión general del recorrido</a></li> <li><a href="#_el_porqué_vs_code_en_el_hogar">El Porqué: VS Code en el hogar</a> <ul class="sectlevel2"> <li><a href="#_el_problema_con_la_instalación_del_sistema">El problema con la instalación del sistema</a></li> <li><a href="#_la_solución_una_instalación_local">La solución: una instalación local</a></li> <li><a href="#_ventajas_concretas">Ventajas concretas</a></li> </ul> </li> <li><a href="#_personalizar_la_fuente_del_menú_principal">Personalizar la fuente del menú principal</a> <ul class="sectlevel2"> <li><a href="#_la_constatación">La constatación</a></li> <li><a href="#_la_técnica_parche_css_directo">La técnica : parche CSS directo</a></li> <li><a href="#_eliminar_la_advertencia_de_integridad">Eliminar la advertencia de integridad</a></li> </ul> </li> <li><a href="#_personalizar_la_fuente_del_panel_explorador_el_combate">Personalizar la fuente del panel Explorador — el combate</a> <ul class="sectlevel2"> <li><a href="#_intento_1_un_parámetro_que_no_existe">Intento 1 : un parámetro que no existe</a></li> <li><a href="#_intento_2_la_extensión_custom_css_and_js_loader">Intento 2: la extensión Custom CSS and JS Loader</a></li> <li><a href="#_la_trampa_hay_que_activar_la_extensión_cada_vez">La trampa: hay que activar la extensión cada vez</a></li> <li><a href="#_intento_3_las_líneas_se_superponen">Intento 3: las líneas se superponen</a></li> <li><a href="#_la_solución_zoom_sobre_el_contenedor_padre">La solución: <code>zoom</code> sobre el contenedor padre</a></li> <li><a href="#_resumen_de_los_selectores_y_lo_que_funciona">Resumen de los selectores y lo que funciona</a></li> </ul> </li> <li><a href="#_el_script_de_actualización_automática">El script de actualización automática</a> <ul class="sectlevel2"> <li><a href="#_el_problema">El problema</a></li> <li><a href="#_el_script_vscode_update_sh">El script `vscode-update.sh</a></li> </ul> </li> <li><a href="#_archivos_involucrados_visión_general">Archivos involucrados — visión general</a></li> <li><a href="#_lecciones_aprendidas">Lecciones aprendidas</a> <ul class="sectlevel2"> <li><a href="#_instalar_en_el_home_libera_todo">Instalar en el home libera todo</a></li> <li><a href="#_zoom_font_size_para_los_componentes_de_lista">zoom` > <code>font-size</code> para los componentes de lista</a></li> <li><a href="#_la_extensión_custom_css_requiere_una_activación_explícita">La extensión Custom CSS requiere una activación explícita</a></li> <li><a href="#_un_script_de_actualización_es_indispensable">Un script de actualización es indispensable.</a></li> </ul> </li> <li><a href="#_referencias_rápidas">Referencias rápidas</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 8 minutes</div> <p>¿Por qué instalar VS Code en`/opt`o via`apt`cuando se puede colocarlo en su casa y convertir su IDE en un terreno de juego sin nunca teclear`sudo`? He aquí el relato de una instalación local seguida de una lucha acharnada para ampliar las fuentes del menú y del explorador de archivos.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_visión_general_del_recorrido">Visión general del recorrido</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur as dev actor "opencode ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur as dev actor "opencode + LLM" as agent package "Home Usuario (~)" #LightGreen { package "~/apps/" { component "VS Code (tarball)" as vscode #SkyBlue component "vscode-update.sh" as script #LightYellow } package "~/.config/Code/" { component "settings.json" as settings #Lavender } package "~/.vscode-custom-css/" { component "custom.css\n(zoom: 1.25)" as customcss #Lavender } } cloud "code.visualstudio.com" as download dev --> vscode : Télécharge & installe dev --> script : Lance mise à jour script --> download : wget dernière version script --> vscode : Remplace + re-patch CSS agent --> settings : Écrit config agent --> customcss : Écrit zoom CSS agent --> vscode : Patch workbench CSS note right of vscode Installation dans le home = contrôle total sans sudo end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_porqué_vs_code_en_el_hogar">El Porqué: VS Code en el hogar</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_problema_con_la_instalación_del_sistema">El problema con la instalación del sistema</h3> <div class="paragraph"> <p>VS Code instalado via`apt`, <code>dnf`o en</code>/opt`bloquea los archivos de la aplicación detrás de los derechos root. Cualquier modificación del CSS nativo, de`product.json`o del directorio de instalación requiere`sudo`.</p> </div> <div class="paragraph"> <p>Sin embargo, cuando se utiliza<strong>opencode</strong>(herramienta CLI para pilotar un LLM en su código), el agente necesita poder:</p> </div> <div class="ulist"> <ul> <li> <p>Escribir en los archivos de configuración`~/.config/Code/User/settings.json`) — eso, ya está en el home</p> </li> <li> <p>Modificar los assets del IDE (CSS del workbench,<code>product.json</code>) para las personalizaciones avanzadas — esto está bloqueado sin sudo</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_la_solución_una_instalación_local">La solución: una instalación local</h3> <div class="paragraph"> <p>Descargamos el archivo tarball oficial y lo descomprimimos directamente en`~/apps/`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/apps cd ~/apps wget "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" -O vscode.tar.gz tar -xzf vscode.tar.gz rm vscode.tar.gz</code></pre> </div> </div> <div class="paragraph"> <p>El binario se encuentra entonces en`~/apps/VSCode-linux-x64/bin/code`. Ninguno`sudo`no es necesario para leer, modificar o reemplazar cualquier archivo bajo`~/apps/VSCode-linux-x64/`.</p> </div> </div> <div class="sect2"> <h3 id="_ventajas_concretas">Ventajas concretas</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 12) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Instalación del Sistema\n(/opt, apt, dnf)" #LightCoral { card "VS Code propiedad de root" { [CSS du workbench : sudo requis] [product.json : sudo requis] [Dossier d'install : non modifiable] } } rectangle "Instalación Home ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "Instalación del Sistema\n(/opt, apt, dnf)" #LightCoral { card "VS Code propiedad de root" { [CSS du workbench : sudo requis] [product.json : sudo requis] [Dossier d'install : non modifiable] } } rectangle "Instalación Home (~/apps)" #LightGreen { card "VS Code propiedad del usuario" { [CSS du workbench : libre] [product.json : libre] [Dossier d'install : libre] [Script update maison] } } "Instalación del Sistema\n(/opt, apt, dnf)" -right-> "Instalación Home (~/apps)" : **Non, merci**\nJe prends le home note bottom of "Instalación Home (~/apps)" L'agent opencode+LLM peut modifier les fichiers de l'IDE sans aucune élévation de privilèges end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ventaja</th> <th class="tableblock halign-left valign-top">Detalle</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sin sudo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos los archivos del IDE pertenecen al usuario</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Modificación directa del CSS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Se puede parchear`workbench.desktop.main.css`sin elevación de privilegios</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Script de actualización casera</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un simple script shell descarga, reemplaza y repacha automáticamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Aislamiento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La instalación del sistema no está contaminada; rollback = eliminar la carpeta</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_personalizar_la_fuente_del_menú_principal">Personalizar la fuente del menú principal</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_constatación">La constatación</h3> <div class="paragraph"> <p>La fuente predeterminada del menú principal (Archivo, Editar, Ver…​) y de los menús desplegables es demasiado pequeña. VS Code no ofrece ninguna opción para cambiarla.</p> </div> </div> <div class="sect2"> <h3 id="_la_técnica_parche_css_directo">La técnica : parche CSS directo</h3> <div class="paragraph"> <p>Se añade CSS al final del archivo`workbench.desktop.main.css`:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/menubar-patch-sequence.svg" alt="menubar patch sequence" width="675" height="599"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">CSS_FILE="$HOME/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css" cat >> "$CSS_FILE" << 'EOF' .menubar-menu-title{font-size:23px!important} .menubar>.menubar-menu-button{font-size:23px!important} .monaco-menu-option{font-size:22px!important;line-height:34px!important} .monaco-menu .action-label:not(.codicon){font-size:22px!important} .menubar-menu-items-holder .monaco-menu .action-item .action-label{font-size:22px!important} EOF</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_eliminar_la_advertencia_de_integridad">Eliminar la advertencia de integridad</h3> <div class="paragraph"> <p>VS Code detecta los cambios en sus archivos y muestra un banner "Your installation is corrupt". Para evitarlo, se eliminan los checksums de`product.json`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">import json product_json = "$HOME/apps/VSCode-linux-x64/resources/app/product.json" with open(product_json, 'r') as f: data = json.load(f) data.pop('checksums', None) with open(product_json, 'w') as f: json.dump(data, f, indent=2)</code></pre> </div> </div> <div class="paragraph"> <p>Tras el reinicio, no hay más advertencias y los menús son finalmente legibles.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_personalizar_la_fuente_del_panel_explorador_el_combate">Personalizar la fuente del panel Explorador — el combate</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_intento_1_un_parámetro_que_no_existe">Intento 1 : un parámetro que no existe</h3> <div class="paragraph"> <p>Primero intentamos el parámetro nativo`workbench.tree.fontSize`en`settings.json`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "workbench.tree.fontSize": 20 }</code></pre> </div> </div> <div class="paragraph"> <p>Resultado:<strong>ningún efecto</strong>Este ajuste no existe en VS Code. La prueba de que los parámetros no reconocidos se ignoran silenciosamente.</p> </div> </div> <div class="sect2"> <h3 id="_intento_2_la_extensión_custom_css_and_js_loader">Intento 2: la extensión Custom CSS and JS Loader</h3> <div class="paragraph"> <p>Se instala la extensión`be5invis.vscode-custom-css`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/apps/VSCode-linux-x64/bin/code --install-extension be5invis.vscode-custom-css</code></pre> </div> </div> <div class="paragraph"> <p>Se crea un archivo CSS en`~/.vscode-custom-css/custom.css`con selectores que se dirigen a los elementos del explorador :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-tree-rows .monaco-tree-row, .sidebar .monaco-list-row, .explorer-viewlet .monaco-list-row, .monaco-list-row .monaco-icon-label { font-size: 22px !important; line-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>Y se referencia este archivo en los ajustes:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "vscode_custom_css.imports": [ "file:///home/user/.vscode-custom-css/custom.css" ] }</code></pre> </div> </div> <div class="paragraph"> <p>Resultado :<strong>los cambios no se aplican</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_la_trampa_hay_que_activar_la_extensión_cada_vez">La trampa: hay que activar la extensión cada vez</h3> <div class="paragraph"> <p>La documentación de la extensión es discreta en este punto crucial: después de cada modificación del CSS personalizado, hay que<strong>imperativamente</strong>ejecutar el comando desde la paleta:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>Ctrl+Shift+P</code>→ teclear<strong>Habilitar CSS y JS personalizados</strong></p> </li> <li> <p>VS Code solicita un reinicio → aceptar</p> </li> </ol> </div> <div class="paragraph"> <p>Sin este paso, el CSS nunca se inyecta en el IDE.</p> </div> </div> <div class="sect2"> <h3 id="_intento_3_las_líneas_se_superponen">Intento 3: las líneas se superponen</h3> <div class="paragraph"> <p>Incluso con`font-size: 22px` et <code>line-height: 36px</code>, las letras con descendente (g, p, f, b) sobresalen de las líneas vecinas. Se intenta añadir`height` et <code>min-height</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-list-row { height: 36px !important; min-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>Resultado:<strong>ningún cambio</strong>. VS Code calcula las alturas de líneas en JavaScript y anula los valores CSS.</p> </div> </div> <div class="sect2"> <h3 id="_la_solución_zoom_sobre_el_contenedor_padre">La solución: <code>zoom</code> sobre el contenedor padre</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Intento 1 Parámetro inexistente" #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "Intento 1 Parámetro inexistente" #LightCoral { card "workbench.tree.fontSize" as t1 { [VS Code ignore le paramètre] } } rectangle "Intento 2 CSS personalizado + tamaño de fuente" #LightYellow { card ".monaco-list-row { font-size: 22px }" as t2 { [Texte plus grand\nmais lignes superposées] } } rectangle "Intento 3 font-size + line-height + height" #LightYellow { card "height: 36px !important" as t3 { [VS Code override\npar JavaScript] [Aucun effet] } } rectangle "Solution zoom en el contenedor padre" #LightGreen { card ".monaco-list-rows { zoom: 1.25 }" as t4 { [Texte + espacement\nproportionnels] [Layout JS respecté] [✓ Résultat conforme] } } t1 -down-> t2 : Pas de paramètre ?\nOn essaie le CSS t2 -down-> t3 : Lignes superposées ?\nOn force la hauteur t3 -down-> t4 : Override JS ?\nOn utilise zoom @enduml</pre> </div> </div> <div class="paragraph"> <p>En lugar de luchar contra el layout JavaScript, se utiliza la propiedad`zoom`en el contenedor de las líneas :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.explorer-viewlet .monaco-list-rows, .sidebar .monaco-list-rows { zoom: 1.25; }</code></pre> </div> </div> <div class="paragraph"> <p>`zoom`agrandiza uniformemente la renderización del contenedor — texto y espaciado — sin romper el layout calculado por el motor JavaScript de VS Code. El factor 1.25 corresponde aproximadamente a un paso de 13px a 16px.</p> </div> <div class="paragraph"> <p>Resultado :<strong>los nombres de archivos son finalmente legibles, las líneas correctamente espaciadas</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_resumen_de_los_selectores_y_lo_que_funciona">Resumen de los selectores y lo que funciona</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Enfoque</th> <th class="tableblock halign-left valign-top">CSS</th> <th class="tableblock halign-left valign-top">Resultado</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size`sobre</code>.monaco-list-row`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size: 22px !important</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Texto más grande pero líneas superpuestas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height</code>+<code>height`sobre</code>.monaco-list-row`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height: 36px; height: 36px</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sin efecto (override JS)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom`sobre</code>.monaco-list-rows`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom: 1.25</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Exitoso — texto + espaciado proporcional</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_el_script_de_actualización_automática">El script de actualización automática</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 27) ] @startuml skinparam backgroundColor #FEFEFE autonumber actor "Desarrollador\no cron" as dev participant "vscode-update.sh" as script participant "vscode tarball\n(code.visualstudio.com)" as remote participant "~/apps/\nVSCode-linux-x64/" as local participant "~/apps/\nvscode-backup" as backup participant "workbench\n.desktop.main.css" as css participant "product.json" as product dev -> script : ./vscode-update.sh script -> local : Lire version courante script -> remote : wget dernière version script -> script : Comparer versions alt Version identique script --> dev : "¡Ya está actualizado!" else Nouvelle version script -> backup : Sauvegarder installation courante\n(horodatée) script -> local : rm -rf ancienne installation script -> local : mv nouvelle installation script -> css : Ajouter patch CSS\n(menubar 23px, dropdown 22px) script -> product : Supprimer checksums\n(python3) script --> dev : "Actualización completa 1.xx.yy → 1.zz.ww" ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE autonumber actor "Desarrollador\no cron" as dev participant "vscode-update.sh" as script participant "vscode tarball\n(code.visualstudio.com)" as remote participant "~/apps/\nVSCode-linux-x64/" as local participant "~/apps/\nvscode-backup" as backup participant "workbench\n.desktop.main.css" as css participant "product.json" as product dev -> script : ./vscode-update.sh script -> local : Lire version courante script -> remote : wget dernière version script -> script : Comparer versions alt Version identique script --> dev : "¡Ya está actualizado!" else Nouvelle version script -> backup : Sauvegarder installation courante\n(horodatée) script -> local : rm -rf ancienne installation script -> local : mv nouvelle installation script -> css : Ajouter patch CSS\n(menubar 23px, dropdown 22px) script -> product : Supprimer checksums\n(python3) script --> dev : "Actualización completa 1.xx.yy → 1.zz.ww" end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_el_problema">El problema</h3> <div class="paragraph"> <p>Cuando VS Code se actualiza, reemplaza la carpeta de instalación y<strong>elimina todos los parches CSS</strong>. Hay que volver a aplicar los cambios manualmente cada vez.</p> </div> </div> <div class="sect2"> <h3 id="_el_script_vscode_update_sh">El script `vscode-update.sh</h3> <div class="paragraph"> <p>Se crea`~/apps/vscode-update.sh`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">#!/bin/bash set -e VSCODE_DIR="$HOME/apps/VSCode-linux-x64" BACKUP_DIR="$HOME/apps/vscode-backup" TEMP_DIR="/tmp/vscode-update" MENUBAR_FONT_SIZE="23px" DROPDOWN_FONT_SIZE="22px" echo "=== VS Code Local Updater ===" CURRENT_VERSION=$("$VSCODE_DIR/bin/code" --version 2>/dev/null | head -1) echo "Current version: $CURRENT_VERSION" echo "Downloading latest VS Code..." mkdir -p "$TEMP_DIR" wget -q "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" \ -O "$TEMP_DIR/vscode.tar.gz" echo "Extracting..." mkdir -p "$TEMP_DIR/extracted" tar -xzf "$TEMP_DIR/vscode.tar.gz" -C "$TEMP_DIR/extracted" NEW_VERSION=$("$TEMP_DIR/extracted/VSCode-linux-x64/bin/code" \ --version 2>/dev/null | head -1) echo "New version: $NEW_VERSION" if [ "$CURRENT_VERSION" = "$NEW_VERSION" ]; then echo "Already up to date!" rm -rf "$TEMP_DIR" exit 0 fi echo "Backing up current installation..." mkdir -p "$BACKUP_DIR" cp -r "$VSCODE_DIR" "$BACKUP_DIR/VSCode-linux-x64-$(date +%Y%m%d-%H%M%S)" echo "Updating..." rm -rf "$VSCODE_DIR" mv "$TEMP_DIR/extracted/VSCode-linux-x64" "$VSCODE_DIR" rm -rf "$TEMP_DIR" CSS_FILE="$VSCODE_DIR/resources/app/out/vs/workbench/workbench.desktop.main.css" echo "Re-applying custom CSS patch \ (menubar=${MENUBAR_FONT_SIZE}, dropdown=${DROPDOWN_FONT_SIZE})..." cat >> "$CSS_FILE" << CSSEOF .menubar-menu-title{font-size:${MENUBAR_FONT_SIZE}!important}\ .menubar>.menubar-menu-button{font-size:${MENUBAR_FONT_SIZE}!important}\ .monaco-menu-option{font-size:${DROPDOWN_FONT_SIZE}!important;\ line-height:34px!important}\ .monaco-menu .action-label:not(.codicon)\ {font-size:${DROPDOWN_FONT_SIZE}!important}\ .menubar-menu-items-holder .monaco-menu .action-item .action-label\ {font-size:${DROPDOWN_FONT_SIZE}!important} CSSEOF PRODUCT_JSON="$VSCODE_DIR/resources/app/product.json" if [ -f "$PRODUCT_JSON" ]; then echo "Removing checksums to prevent integrity warning..." python3 -c " import json with open('$PRODUCT_JSON','r') as f: data=json.load(f) data.pop('checksums', None) with open('$PRODUCT_JSON','w') as f: json.dump(data,f,indent=2) print('Done.') " fi echo "=== Update complete: $CURRENT_VERSION -> $NEW_VERSION ==="</code></pre> </div> </div> <div class="paragraph"> <p>El script:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Descarga la última versión estable</p> </li> <li> <p>Comprueba si la versión difiere de la actual</p> </li> <li> <p>Guardar la instalación actual (con marca de tiempo) en`~/apps/vscode-backup/`</p> </li> <li> <p>Reemplace la carpeta de instalación</p> </li> <li> <p><strong>Vuelva a aplicar</strong>el parche CSS del menú principal</p> </li> <li> <p><strong>Elimina los checksums</strong> de `product.json`para evitar la advertencia de integridad</p> </li> </ol> </div> <div class="paragraph"> <p>NOTA: Las personalizaciones del panel Explorer a través de la extensión Custom CSS y el archivo`~/.vscode-custom-css/custom.css`sobreviven a las actualizaciones porque viven fuera del directorio de instalación.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_archivos_involucrados_visión_general">Archivos involucrados — visión general</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Instalación VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Instalación VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { component "workbench.desktop\n.main.css" as css #LightCoral component "product.json" as product #LightCoral component "binario bin/code" as binary #LightCoral } rectangle "Configuración de usuario (~/.config/Code/)" #LightGreen { component "settings.json" as settings #LightGreen component "extensiones/" as extensions #LightGreen } rectangle "Customisation persistente\n(~/.vscode-custom-css/)" #SkyBlue { component "custom.css (zoom: 1.25)" as customcss #SkyBlue } rectangle "Automatización (~/apps/)" #LightYellow { component "vscode-update.sh" as script #LightYellow component "vscode-backup/" as backup #LightYellow } script ..> css : Re-patch après MAJ script ..> product : Supprime checksums\naprès MAJ settings --> customcss : Référence via\nvscode_custom_css.imports extensions ..> css : Custom CSS Loader\ninjecte custom.css note bottom of css **Ne survit pas** aux mises à jour Re-patché par le script end note note bottom of customcss **Survit** aux mises à jour Vit hors du dossier d'installation end note note bottom of settings **Survit** aux mises à jour Vit dans ~/.config/ end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">camino</th> <th class="tableblock halign-left valign-top">Rol</th> <th class="tableblock halign-left valign-top">¿Sobrevive a las actualizaciones?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Instalación del IDE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (reemplazada)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSS del área de trabajo (menú, listas desplegables)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (reparcheado por el script)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/product.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sumas de verificación de integridad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (re-limpieza por el script)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/vscode-update.sh</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Script de actualización automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.config/Code/User/settings.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parámetros de usuario (fontSize, custom CSS)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.vscode-custom-css/custom.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSS personalizado para el Explorer (zoom)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sí</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas">Lecciones aprendidas</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 rectangle "Instalación local en el home" as install #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 rectangle "Instalación local en el home" as install #LightGreen { card "No sudo\n modificar CSS/config" as i1 card "opencode+LLM puede\n modificar todo" as i2 card "Rollback = restaurar\n el backup marcado de tiempo" as i3 } rectangle "**Personalización CSS** zoom vs tamaño de fuente" as css #LightYellow { card "zoom > tamaño de fuente para la lista de componentes" as c1 card "Layout JS override height/line-height" as c2 card "Extension Custom CSS requiere activación manual (Ctrl+Shift+P)" as c3 } rectangle "**Automatización**\n script de actualización" as auto #LightCoral { card "Re-patch CSS después cada actualización" as a1 card "Eliminar checksums product.json" as a2 card "Copia de seguridad timestampada\n antes del reemplazo" as a3 } install -right-> css : ensuite css -right-> auto : enfin note top of install Contrôle total sans élévation de privilèges end note note top of auto Sans script, chaque MAJ efface les patches CSS end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_instalar_en_el_home_libera_todo">Instalar en el home libera todo</h3> <div class="paragraph"> <p>Una instalación local en`~/apps`da un control total sobre VS Code :</p> </div> <div class="ulist"> <ul> <li> <p>No`sudo`para modificar el CSS o la configuración</p> </li> <li> <p>El agente opencode+LLM puede escribir en los archivos de configuración y los assets del IDE</p> </li> <li> <p>Rollback trivial: restaurar la copia de seguridad con marca de tiempo</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_zoom_font_size_para_los_componentes_de_lista">zoom` > <code>font-size</code> para los componentes de lista</h3> <div class="paragraph"> <p>VS Code controla la altura de las líneas mediante JavaScript. Modificar`font-size`No poder tocar la altura asignada por el motor de layout da textos que se desbordan. La propiedad`zoom`sobre el contenedor padre agranda todo proporcionalmente y evita este problema.</p> </div> </div> <div class="sect2"> <h3 id="_la_extensión_custom_css_requiere_una_activación_explícita">La extensión Custom CSS requiere una activación explícita</h3> <div class="paragraph"> <p>No es un parámetro 'set and forget'. Cada modificación del archivo CSS custom requiere volver a ejecutar 'Enable Custom CSS and JS' desde la paleta de comandos`Ctrl+Shift+P`)</p> </div> </div> <div class="sect2"> <h3 id="_un_script_de_actualización_es_indispensable">Un script de actualización es indispensable.</h3> <div class="paragraph"> <p>Sin script, cada actualización de VS Code elimina los parches CSS del workbench. El script`vscode-update.sh`automatiza la descarga, el reemplazo, el re-patch y la limpieza de los checksums.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_referencias_rápidas">Referencias rápidas</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Descarga VS Code : <a href="https://code.visualstudio.com/Download" class="bare">https://code.visualstudio.com/Download</a></p> </li> <li> <p>Extensión Cargador de CSS y JS personalizado :`be5invis.vscode-custom-css`</p> </li> <li> <p>Issue VS Code solicitando un parámetro nativo para la fuente del Explorer:https://github.com/microsoft/vscode/issues/149[github.com/microsoft/vscode#149]</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2026/0102_migration_gradle_script_to_plugin_post.html Thu, 16 Apr 2026 00:00:00 +0000 blog/2026/0102_migration_gradle_script_to_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contexto_y_objetivo">Contexto y objetivo</a> <ul class="sectlevel2"> <li><a href="#_el_punto_de_partida">El punto de partida</a></li> <li><a href="#_el_objetivo">El objetivo</a></li> </ul> </li> <li><a href="#_el_primer_obstáculo_ruby_gems">El primer obstáculo: `ruby { gems() }</a> <ul class="sectlevel2"> <li><a href="#_lo_que_esconde_el_azúcar_sintáctico_groovy">Lo que esconde el azúcar sintáctico Groovy</a></li> <li><a href="#_descomposición_del_mecanismo">Descomposición del mecanismo</a></li> </ul> </li> <li><a href="#_la_solución_en_tres_partes">La solución en tres partes</a> <ul class="sectlevel2"> <li><a href="#_parte_1_el_repo_ivy_para_rubygems">Parte 1: el repo Ivy para rubygems</a></li> <li><a href="#_parte_2_la_dependencia_asciidoctorgems">Parte 2 : la dependencia asciidoctorGems</a></li> <li><a href="#_parte_3_settings_gradle_kts">Parte 3: settings.gradle.kts</a></li> </ul> </li> <li><a href="#_introspección_de_la_api_por_bytecodes">Introspección de la API por bytecodes</a> <ul class="sectlevel2"> <li><a href="#_por_qué_javap">¿Por qué <code>javap</code>?</a></li> <li><a href="#_jerarquía_de_la_tarea">Jerarquía de la tarea</a></li> <li><a href="#_descubrimiento_de_forkoptions">Descubrimiento de `forkOptions</a></li> <li><a href="#_la_api_de_javaforkoptions_grolifant">La API de JavaForkOptions (grolifant)</a></li> <li><a href="#_revealjsextension">RevealJSExtension</a></li> </ul> </li> <li><a href="#_configuración_del_toolchain_java">Configuración del toolchain Java</a> <ul class="sectlevel2"> <li><a href="#_el_problema_de_javatoolchainservice">El problema de JavaToolchainService</a></li> </ul> </li> <li><a href="#_detección_automática_docker">Detección automática Docker</a> <ul class="sectlevel2"> <li><a href="#_contexto">Contexto</a></li> <li><a href="#_estrategia">Estrategia</a></li> </ul> </li> <li><a href="#_resultado_final">Resultado final</a> <ul class="sectlevel2"> <li><a href="#_el_buildscript_consumidor">El buildscript consumidor</a></li> <li><a href="#_settings_gradle_kts">settings.gradle.kts</a></li> </ul> </li> <li><a href="#_resumen_de_las_trampas_y_soluciones">Resumen de las trampas y soluciones</a></li> <li><a href="#_método_de_investigación_leer_una_api_desconocida_con_javap">Método de investigación: leer una API desconocida con javap</a> <ul class="sectlevel2"> <li><a href="#_principio">Principio</a></li> <li><a href="#_paso_1_localizar_el_jar_en_el_caché_de_gradle">Paso 1 : localizar el jar en el caché de Gradle</a></li> <li><a href="#_paso_2_listar_las_clases_del_jar">Paso 2: listar las clases del jar</a></li> <li><a href="#_paso_3_inspeccionar_una_clase">Paso 3: inspeccionar una clase</a></li> <li><a href="#_paso_4_subir_la_jerarquía">Paso 4 : subir la jerarquía</a></li> <li><a href="#_paso_5_seguir_los_tipos_desconocidos">Paso 5: seguir los tipos desconocidos</a></li> <li><a href="#_paso_6_verificar_las_extensiones_del_proyecto">Paso 6: verificar las extensiones del proyecto</a></li> <li><a href="#_resumen_del_método">Resumen del método</a></li> </ul> </li> <li><a href="#_próximo_paso">Próximo paso</a></li> </ul> </div> <div class="sect1"> <h2 id="_contexto_y_objetivo">Contexto y objetivo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_punto_de_partida">El punto de partida</h3> <div class="paragraph"> <p>El proyecto`slider-gradle`genera presentaciones Reveal.js a partir de archivos AsciiDoc mediante el plugin Gradle`org.asciidoctor.jvm.revealjs`. La configuración de la tarea principal`asciidoctorRevealJs`vivía directamente en el buildscript raíz`build.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("org.asciidoctor.jvm.revealjs") } apply<slides.SlidesPlugin>() project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { repositories { ruby { gems() } } revealjs { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } revealjsOptions { // ... configuration complète } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_el_objetivo">El objetivo</h3> <div class="paragraph"> <p>Mover toda esta configuración a`buildSrc/src/main/kotlin/slides/SlidesPlugin.kt`para que el buildscript del consumidor se reduzca a :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>El plugin debe ser totalmente autónomo: aplica él mismo sus dependencias de plugins, configura sus repos, y gestiona sus gemas Ruby.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_el_primer_obstáculo_ruby_gems">El primer obstáculo: `ruby { gems() }</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lo_que_esconde_el_azúcar_sintáctico_groovy">Lo que esconde el azúcar sintáctico Groovy</h3> <div class="paragraph"> <p>La línea`repositories { ruby { gems() } }`es una extensión DSL Groovy disponible únicamente en el contexto de ejecución del buildscript. No existe como una API Kotlin estática accesible desde buildSrc.</p> </div> <div class="paragraph"> <p>Intentando llamarlo desde`SlidesPlugin.kt`, la compilación falla inmediatamente.</p> </div> </div> <div class="sect2"> <h3 id="_descomposición_del_mecanismo">Descomposición del mecanismo</h3> <div class="paragraph"> <p>Después del análisis del caché Gradle (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), se descubre en el archivo`ivy-3.1.0.xml`(Note: As the provided French text to translate was empty beyond the colon and formatting instructions, no translation output is generated per the requirement to output only the translated text of the given fragment.)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><artifact type='gem' url='https://rubygems.org/gems/asciidoctor-revealjs-3.1.0.gem' /></code></pre> </div> </div> <div class="paragraph"> <p>`ruby { gems() }`efectuaba en realidad<strong>tres operaciones distintas</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Registrar un repo Ivy apuntando a`https://rubygems.org/gems/`</p> </li> <li> <p>Excluir el grupo`rubygems`repositorios Maven para evitar los conflictos</p> </li> <li> <p>Guardar la gema en la configuración`asciidoctorGems`para que JRuby lo cargue en tiempo de ejecución</p> </li> </ol> </div> <div class="paragraph"> <p>Estas tres responsabilidades deben reproducirse por separado en Kotlin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_en_tres_partes">La solución en tres partes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_parte_1_el_repo_ivy_para_rubygems">Parte 1: el repo Ivy para rubygems</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } <i class="conum" data-value="1"></i><b>(1)</b> metadataSources { artifact() } content { includeGroup("rubygems") } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>La extensión`.gem`debe estar hardcodeada.<code>[ext]`resuelve por defecto en</code>.jar`, lo que provoca un error`Resource missing`.</td> </tr> </table> </div> <div class="paragraph"> <p>NOTA: El repo Ivy se declara directamente en`project.repositories`y no en un bloque`repositories { }`pues el receiver de este bloque no es el`RepositoryHandler`estándar de Gradle pero una API grolifant incompatible con la extensión`ivy`Kotlin DSL.</p> </div> </div> <div class="sect2"> <h3 id="_parte_2_la_dependencia_asciidoctorgems">Parte 2 : la dependencia asciidoctorGems</h3> <div class="paragraph"> <p>El plugin`org.asciidoctor.jvm.gems`debe aplicarse primero — crea la configuración`asciidoctorGems`y la tarea`asciidoctorGemsPrepare` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.plugins.apply("org.asciidoctor.jvm.gems") project.plugins.apply("org.asciidoctor.jvm.revealjs") <i class="conum" data-value="1"></i><b>(1)</b> project.dependencies { add("asciidoctorGems", "rubygems:asciidoctor-revealjs:3.1.0@gem") <i class="conum" data-value="2"></i><b>(2)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>El orden de aplicación es importante :`gems`antes`revealjs`. <2> El calificador`@gem`fuerza la extensión correcta sobre la dependencia.</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_parte_3_settings_gradle_kts">Parte 3: settings.gradle.kts</h3> <div class="paragraph"> <p>`dependencyResolutionManagement`dentro`settings.gradle.kts`debe permitir que los proyectos declaren sus propios repos:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) }</code></pre> </div> </div> <div class="paragraph"> <p>Sin esta línea, Gradle ignora los repos declarados en el plugin y la resolución de las gems falla.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_introspección_de_la_api_por_bytecodes">Introspección de la API por bytecodes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_por_qué_javap">¿Por qué <code>javap</code>?</h3> <div class="paragraph"> <p>El plugin`asciidoctor-gradle-jvm-slides`está en versión`4.0.0-alpha.1`. Su documentación es inexistente o incompleta. La única fuente fiable es la inspección directa de las clases compiladas.</p> </div> </div> <div class="sect2"> <h3 id="_jerarquía_de_la_tarea">Jerarquía de la tarea</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>Resultado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask implements org.asciidoctor.gradle.base.slides.SlidesToExportAware</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_descubrimiento_de_forkoptions">Descubrimiento de `forkOptions</h3> <div class="paragraph"> <p>Al inspeccionar`AbstractAsciidoctorTask`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm"</code></pre> </div> </div> <div class="paragraph"> <p>Se encuentra:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">final org.ysb33r.grolifant.api.v4.JavaForkOptions javaForkOptions; public void forkOptions(org.gradle.api.Action<org.ysb33r.grolifant.api.v4.JavaForkOptions>); public static final org.asciidoctor.gradle.base.process.ProcessMode JAVA_EXEC;</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_la_api_de_javaforkoptions_grolifant">La API de JavaForkOptions (grolifant)</h3> <div class="paragraph"> <p>`javaLauncher`no existe en esta tarea. La API real de`org.ysb33r.grolifant.api.v4.JavaForkOptions`python import sys</p> </div> <div class="paragraph"> <p>def main(): data = sys.stdin.read() if not data: return parts = data.split('’) for i in range(len(parts)): if i % 2 == 0: parts[i] = parts[i].replace(" :", ":") parts[i] = parts[i].replace("expose", "expone") sys.stdout.write(''.join(parts))</p> </div> <div class="paragraph"> <p>if <em>name</em> == '<em>main</em>': main()</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public void executable(java.lang.Object); <i class="conum" data-value="1"></i><b>(1)</b> public void setExecutable(java.lang.Object);</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>El método`executable(Object)`reemplaza la asignación`executable = …​`que no compila (`val`no puede ser reasignado).</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_revealjsextension">RevealJSExtension</h3> <div class="paragraph"> <p>`revealjs { }`no es un método de la tarea pero una<strong>extensión de proyecto</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension</code></pre> </div> </div> <div class="paragraph"> <p>Se accede vía :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_del_toolchain_java">Configuración del toolchain Java</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_problema_de_javatoolchainservice">El problema de JavaToolchainService</h3> <div class="paragraph"> <p>`JavaToolchainService`no es una extensión de proyecto. La siguiente llamada falla :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ERREUR : Extension of type 'JavaToolchainService' does not exist project.extensions.getByType<JavaToolchainService>()</code></pre> </div> </div> <div class="paragraph"> <p>La buena API es`serviceOf` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.gradle.kotlin.dsl.support.serviceOf project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_detección_automática_docker">Detección automática Docker</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto">Contexto</h3> <div class="paragraph"> <p>El plugin Asciidoctor/JRuby requiere Java 17. Kotlin 2.0.x en buildSrc no admite Java 25 (el analizador de versión falla al`"25.0.2"`). El daemon Gradle debe ejecutarse por tanto en Java 17 o debe usarse Docker.</p> </div> </div> <div class="sect2"> <h3 id="_estrategia">Estrategia</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Docker disponible → ejecución mediante contenedor`eclipse-temurin:17`(comportamiento por defecto)</p> </li> <li> <p>Docker ausente + Java 17 → ejecución local</p> </li> <li> <p>Docker ausente + Java > 17 → error explícito</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val isDockerAvailable = try { Runtime.getRuntime().exec(arrayOf("docker", "info")).waitFor() == 0 } catch (e: Exception) { false } val javaVersion = JavaVersion.current().majorVersion.toInt() when { isDockerAvailable -> project.tasks.register<Exec>(TASK_ASCIIDOCTOR_REVEALJS) { group = GROUP_TASK_SLIDER description = "Slider settings and generation (via Docker)" dependsOn(TASK_CLEAN_SLIDES_BUILD) finalizedBy(TASK_DASHBOARD_SLIDES_BUILD) commandLine( "docker", "run", "--rm", "-v", "${project.rootDir.absolutePath}:/workspace", "-v", "${System.getProperty("user.home")}/.gradle:/root/.gradle", "-w", "/workspace", "eclipse-temurin:17", "./gradlew", TASK_ASCIIDOCTOR_REVEALJS ) workingDir = project.rootDir } javaVersion == 17 -> { project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } metadataSources { artifact() } content { includeGroup("rubygems") } } project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } // ... reste de la configuration } } else -> error( "Docker est requis pour exécuter $TASK_ASCIIDOCTOR_REVEALJS " + "avec Java $javaVersion. Installez Docker ou utilisez Java 17." ) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_resultado_final">Resultado final</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_buildscript_consumidor">El buildscript consumidor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>Es todo. El plugin lleva toda la responsabilidad.</p> </div> </div> <div class="sect2"> <h3 id="_settings_gradle_kts">settings.gradle.kts</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">pluginManagement { repositories { mavenLocal() gradlePluginPortal() } } plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) } rootProject.name = "slider-gradle"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_resumen_de_las_trampas_y_soluciones">Resumen de las trampas y soluciones</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">problema</th> <th class="tableblock halign-left valign-top">causa</th> <th class="tableblock halign-left valign-top">Solución</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`ruby { gems() }`no disponible en Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensión DSL Groovy únicamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tres mecanismos separados : repo Ivy + exclusión Maven +<code>asciidoctorGems</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle busca un`.jar`en lugar de un`.gem`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`[ext]`resuelve en`jar`por defecto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">hardcodear`.gem`en el patrón Ivy + calificador`@gem`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ivy { }`no compila en`repositories { }</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Receptor grolifant incompatible con el DSL Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Llamada directa`project.repositories.ivy { }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`javaLauncher`no resuelto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Propiedad inexistente en`AsciidoctorJRevealJSTask`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>setInProcess("JAVA_EXEC")</code>+<code>forkOptions { executable(…​) }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`executable = …​`no compila</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">propiedad`val`en`JavaForkOptions`grolifant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Método`executable(Object)`en el lugar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>JavaToolchainService`no disponible vía`extensions</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Es un servicio Gradle, no una extensión</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.serviceOf<JavaToolchainService>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`revealjs { }`no resuelto en la tarea</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensión de proyecto, no método de tarea</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.extensions.getByType<RevealJSExtension>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">El build falla con Java 25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin 2.0.x no procesa las versiones Java de dos dígitos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detección Docker automática + fallback Java 17</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_método_de_investigación_leer_una_api_desconocida_con_javap">Método de investigación: leer una API desconocida con javap</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio">Principio</h3> <div class="paragraph"> <p>Cuando la documentación está ausente o incompleta, los bytecodes son la fuente de la verdad. <code>javap`es la herramienta estándar del JDK que descompila los archivos</code>.class`firmas Java legibles, sin requerir el código fuente.</p> </div> </div> <div class="sect2"> <h3 id="_paso_1_localizar_el_jar_en_el_caché_de_gradle">Paso 1 : localizar el jar en el caché de Gradle</h3> <div class="paragraph"> <p>Gradle descarga todas sus dependencias en`~/.gradle/caches/modules-2/files-2.1/`. La primera etapa consiste en encontrar el jar que contiene la clase a inspeccionar:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-slides*.jar" 2>/dev/null</code></pre> </div> </div> <div class="listingblock"> <div class="title">Resultado :</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">/home/user/.gradle/caches/modules-2/files-2.1/org.asciidoctor/ asciidoctor-gradle-jvm-slides/4.0.0-alpha.1/.../ asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_paso_2_listar_las_clases_del_jar">Paso 2: listar las clases del jar</h3> <div class="paragraph"> <p>Antes de inspeccionar una clase, se verifica que existe realmente en el jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jar tf asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar | grep -i "RevealJS\|revealjs"</code></pre> </div> </div> <div class="paragraph"> <p>Esto revela todas las clases disponibles : <code>AsciidoctorJRevealJSTask</code>, <code>RevealJSExtension</code>, <code>RevealJSOptions</code>, etc.</p> </div> </div> <div class="sect2"> <h3 id="_paso_3_inspeccionar_una_clase">Paso 3: inspeccionar una clase</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>La opción`-p`muestra todos los miembros, incluidos los privados. El resultado muestra inmediatamente la línea clave:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_paso_4_subir_la_jerarquía">Paso 4 : subir la jerarquía</h3> <div class="paragraph"> <p>La tarea extiende`AbstractAsciidoctorTask`. Lo inspeccionamos a su vez localizando primero su jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-[0-9]*.jar" 2>/dev/null javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm\|java"</code></pre> </div> </div> <div class="paragraph"> <p>Es allí donde se descubre`forkOptions`, <code>JAVA_EXEC</code>, et <code>javaForkOptions</code> de tipo`org.ysb33r.grolifant.api.v4.JavaForkOptions`.</p> </div> </div> <div class="sect2"> <h3 id="_paso_5_seguir_los_tipos_desconocidos">Paso 5: seguir los tipos desconocidos</h3> <div class="paragraph"> <p>`JavaForkOptions`es una clase grolifant desconocida. Localizamos su jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "grolifant*.jar" 2>/dev/null</code></pre> </div> </div> <div class="paragraph"> <p>Entonces lo inspeccionamos:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath grolifant40-legacy-api-2.0.0-alpha.6.jar \ org.ysb33r.grolifant.api.v4.JavaForkOptions</code></pre> </div> </div> <div class="paragraph"> <p>Se encuentra`executable(java.lang.Object)<code>— el método correcto para llamar, opuesto a`executable = …​`que no compila porque es una propiedad`val</code>.</p> </div> </div> <div class="sect2"> <h3 id="_paso_6_verificar_las_extensiones_del_proyecto">Paso 6: verificar las extensiones del proyecto</h3> <div class="paragraph"> <p>Para`revealjs { }`, la pregunta era: ¿es un método de la tarea? o una extensión de proyecto? La inspección de`AsciidoctorJRevealJSTask` no muestra ningún método`revealjs`. Entonces se inspecciona`RevealJSExtension` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension | head -5</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class RevealJSExtension implements groovy.lang.GroovyObject { public static final java.lang.String NAME;</code></pre> </div> </div> <div class="paragraph"> <p>La presencia de`NAME`confirma que es una extensión registrada en el proyecto, accesible mediante`project.extensions.getByType<RevealJSExtension>()`.</p> </div> </div> <div class="sect2"> <h3 id="_resumen_del_método">Resumen del método</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Etapa</th> <th class="tableblock halign-left valign-top">acción</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>find ~/.gradle/caches -name "*.jar"</code>— localizar el jar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jar tf jar.jar | grep NomClasse</code>— comprobar que la clase existe</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>javap -p -classpath jar.jar NomCompletClasse</code>— inspeccionar la clase</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Identificar`extends`y subir la jerarquía</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Seguir los tipos desconocidos en sus propios jar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Buscar`NAME`para identificar una extensión de proyecto</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Este método se aplica a cualquier plugin Gradle cuyo API no está documentada o cuya versión alfa ya no corresponde a la documentación existente.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_próximo_paso">Próximo paso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este plugin buildSrc se extraerá en un proyecto independiente publicado en el Portal de Plugins de Gradle o en Maven Local. El buildscript del consumidor será entonces:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("slides") version "1.0.0" }</code></pre> </div> </div> <div class="paragraph"> <p>Et <code>settings.gradle.kts`se reducirá al mínimo estricto sin referencia a`foojay-resolver-convention</code>, la provisión del JDK siendo gestionada por el propio plugin o documentada como requisito previo.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0101_jbake_portfolio_post.html Thu, 15 Jan 2026 00:00:00 +0000 blog/2026/0101_jbake_portfolio_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_visión_arquitectónica">Visión Arquitectónica</a> <ul class="sectlevel2"> <li><a href="#_principio_director">Principio director</a></li> <li><a href="#_elección_estratégica_asciidoc_para_el_portafolio">Elección estratégica: AsciiDoc para el portafolio</a></li> <li><a href="#_modelo_de_datos">Modelo de datos</a></li> </ul> </li> <li><a href="#_casos_de_uso_detallados">Casos de uso detallados</a> <ul class="sectlevel2"> <li><a href="#_uc1_añadir_un_elemento_al_portafolio">UC1 : Añadir un elemento al portafolio</a> <ul class="sectlevel3"> <li><a href="#_flujo_nominal">Flujo nominal</a></li> <li><a href="#_plantilla_del_archivo_a_crear">Plantilla del archivo a crear</a></li> <li><a href="#_puntos_de_validación">Puntos de validación</a></li> </ul> </li> <li><a href="#_uc2_eliminar_un_elemento_del_portafolio">UC2 : Eliminar un elemento del portafolio</a> <ul class="sectlevel3"> <li><a href="#_flujo_nominal_2">Flujo nominal</a></li> <li><a href="#_estrategia_alternativa_archivado">Estrategia alternativa: archivado</a></li> <li><a href="#_limpieza_de_recursos">Limpieza de recursos</a></li> </ul> </li> <li><a href="#_uc3_establecer_como_no_publicado_borrador">UC3: Establecer como no publicado (borrador)</a> <ul class="sectlevel3"> <li><a href="#_flujo_nominal_3">flujo nominal</a></li> <li><a href="#_estados_posibles">Estados posibles</a></li> <li><a href="#_casos_de_uso_típicos">Casos de uso típicos</a></li> </ul> </li> </ul> </li> <li><a href="#_arquitectura_de_plantillas">Arquitectura de plantillas</a> <ul class="sectlevel2"> <li><a href="#_estrategia_de_plantillas_reutilizables">Estrategia de plantillas reutilizables</a></li> <li><a href="#_pattern_de_extracción_de_datos">Pattern de extracción de datos</a></li> <li><a href="#_convenciones_de_nomenclatura">Convenciones de nomenclatura</a></li> </ul> </li> <li><a href="#_flujo_de_publicación">Flujo de publicación</a> <ul class="sectlevel2"> <li><a href="#_pipeline_de_desarrollo">Pipeline de desarrollo</a></li> <li><a href="#_entornos">entornos</a></li> </ul> </li> <li><a href="#_extensibilidad">Extensibilidad</a> <ul class="sectlevel2"> <li><a href="#_agregado_de_nuevos_atributos">Agregado de nuevos atributos</a></li> <li><a href="#_categorización_avanzada">Categorización avanzada</a></li> </ul> </li> <li><a href="#_buenas_prácticas">Buenas Prácticas</a> <ul class="sectlevel2"> <li><a href="#_organización_de_los_archivos">Organización de los archivos</a></li> <li><a href="#_gestión_del_contenido">Gestión del contenido</a></li> <li><a href="#_rendimiento">Rendimiento</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div class="sect1"> <h2 id="_visión_arquitectónica">Visión Arquitectónica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_director">Principio director</h3> <div class="paragraph"> <p>La arquitectura se basa en el principio de <strong>separación de preocupaciones</strong> :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Contenido</strong> : archivos AsciiDoc estructurados con metadatos ricos</p> </li> <li> <p><strong>Presentación</strong> : plantillas Thymeleaf reutilizables</p> </li> <li> <p><strong>Datos</strong> : modelo extraído automáticamente por JBake desde los atributos AsciiDoc</p> </li> <li> <p><strong>Estilo</strong>: Bootstrap 5 para la coherencia visual</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_elección_estratégica_asciidoc_para_el_portafolio">Elección estratégica: AsciiDoc para el portafolio</h3> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Pourquoi AsciiDoc ?</caption> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Criterio</th> <th class="tableblock halign-left valign-top">Ventaja</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coherencia</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mismo formato que los artículos de blog</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metadatos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Atributos estructurados y extensibles (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">mantenibilidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Edición simple en texto, versionable Git</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Flexibilidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Puede contener contenido rico (tablas, código, imágenes)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Plantillado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake extrae automáticamente los atributos para Thymeleaf</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_modelo_de_datos">Modelo de datos</h3> <div class="paragraph"> <p>Cada proyecto portfolio es un documento AsciiDoc:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Metadatos de encabezado</strong> : información estructurada (cliente, duración, tecnologías, etc.)</p> </li> <li> <p><strong>Cuerpo del documento</strong> : descripción narrativa, desafíos, soluciones, resultados</p> </li> <li> <p><strong>Atributos personalizados</strong> : prefijados`project-*`para la extracción automática</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-91b342f03664ac564881f955c22ea7bf.png" alt="Diagram" width="386" height="811"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casos_de_uso_detallados">Casos de uso detallados</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_añadir_un_elemento_al_portafolio">UC1 : Añadir un elemento al portafolio</h3> <div class="sect3"> <h4 id="_flujo_nominal">Flujo nominal</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Editor ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Editor Texto" as editor participant "Archivo\nAsciiDoc" as file participant "JBake\nMotor" as jbake participant "Sitio\nEstatico" as site dev -> editor : Créer nouveau fichier activate editor editor -> file : portfolio/nouveau-projet.adoc activate file dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*) dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions) dev -> editor : Ajouter images dans assets/img/portfolio/ editor -> file : Sauvegarder deactivate editor dev -> jbake : Lancer build (jbake -b) activate jbake jbake -> file : Lire et parser jbake -> jbake : Extraire métadonnées jbake -> jbake : Convertir AsciiDoc → HTML jbake -> jbake : Appliquer template project.html jbake -> jbake : Ajouter à la liste portfolio.html jbake -> site : Générer pages statiques deactivate jbake dev -> site : Vérifier résultat activate site site --> dev : Afficher projet deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_plantilla_del_archivo_a_crear">Plantilla del archivo a crear</h4> <div class="paragraph"> <p>El desarrollador crea`content/portfolio/nom-projet.adoc`con una estructura estandarizada:</p> </div> <div class="ulist"> <ul> <li> <p>Encabezado con todos los atributos requeridos</p> </li> <li> <p>Secciones normalizadas (Contexto, Desafíos, Soluciones, Resultados)</p> </li> <li> <p>Nomenclatura coherente de las imágenes</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_puntos_de_validación">Puntos de validación</h4> <div class="ulist"> <ul> <li> <p>Los atributos obligatorios están presentes(<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>Las imágenes referenciadas existen en`assets/img/portfolio/`</p> </li> <li> <p>La compilación de JBake se ejecuta sin errores</p> </li> <li> <p>El proyecto aparece en la página portfolio</p> </li> <li> <p>La página individual del proyecto se muestra correctamente</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_eliminar_un_elemento_del_portafolio">UC2 : Eliminar un elemento del portafolio</h3> <div class="sect3"> <h4 id="_flujo_nominal_2">Flujo nominal</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Sistema\nArchivos" as fs participant "JBake ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Sistema\nArchivos" as fs participant "JBake Motor" as jbake participant "Sitio\nEstático" as site database "Cache JBake" as cache dev -> fs : Supprimer portfolio/projet-ancien.adoc activate fs fs --> dev : Fichier supprimé deactivate fs dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-* activate fs fs --> dev : Images supprimées deactivate fs dev -> cache : Nettoyer cache JBake activate cache cache --> dev : Cache vidé deactivate cache dev -> jbake : Rebuild complet (jbake -b) activate jbake jbake -> jbake : Scanner content/portfolio/ jbake -> jbake : Projet absent → non généré jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé) jbake -> site : Déployer nouveau build deactivate jbake dev -> site : Vérifier activate site site --> dev : Projet absent de la liste deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_estrategia_alternativa_archivado">Estrategia alternativa: archivado</h4> <div class="paragraph"> <p>En lugar de eliminar definitivamente, posibilidad de crear una carpeta`content/portfolio/archive/`:</p> </div> <div class="ulist"> <ul> <li> <p>Mover el archivo en lugar de eliminarlo</p> </li> <li> <p>Permite restaurar fácilmente</p> </li> <li> <p>Mantén el historial de Git más claro</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_limpieza_de_recursos">Limpieza de recursos</h4> <div class="ulist"> <ul> <li> <p>Comprobar las imágenes huérfanas en`assets/img/portfolio/`</p> </li> <li> <p>Eliminar las imágenes no referenciadas por otros proyectos</p> </li> <li> <p>Limpiar el caché de JBake para evitar referencias fantasma</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_establecer_como_no_publicado_borrador">UC3: Establecer como no publicado (borrador)</h3> <div class="sect3"> <h4 id="_flujo_nominal_3">flujo nominal</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Archivo\nAsciiDoc" as file participant "JBake\nMotor" as jbake participant "Sitio ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Archivo\nAsciiDoc" as file participant "JBake\nMotor" as jbake participant "Sitio Estatico" as site dev -> file : Ouvrir portfolio/projet.adoc activate file dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft file --> dev : Sauvegardé deactivate file dev -> jbake : Rebuild (jbake -b) activate jbake jbake -> file : Parser le fichier jbake -> jbake : Détecter status=draft jbake -> jbake : Exclure de published_projects jbake -> jbake : Ne pas créer page publique note right Le projet existe toujours mais n'est pas publié end note jbake -> site : Générer site (sans ce projet) deactivate jbake dev -> site : Vérifier portfolio activate site site --> dev : Projet absent de la liste publique deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_estados_posibles">Estados posibles</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-a4b71e9dbf30083d131223257db47469.png" alt="Diagram" width="556" height="448"> </div> </div> </div> <div class="sect3"> <h4 id="_casos_de_uso_típicos">Casos de uso típicos</h4> <div class="ulist"> <ul> <li> <p><strong>Proyecto en curso de redacción</strong> : crear en borrador, publicar cuando esté listo</p> </li> <li> <p><strong>Proyecto confidencial temporalmente</strong> : pasar a borrador mientras se llega al acuerdo con el cliente</p> </li> <li> <p><strong>Actualización importante</strong>: pasar a borrador, modificar, republicar</p> </li> <li> <p><strong>A/B testing</strong> : duplicar en borrador, probar, publicar la mejor versión</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_de_plantillas">Arquitectura de plantillas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrategia_de_plantillas_reutilizables">Estrategia de plantillas reutilizables</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-2a5390886476a8f48c132117e89fcce6.png" alt="Diagram" width="881" height="350"> </div> </div> </div> <div class="sect2"> <h3 id="_pattern_de_extracción_de_datos">Pattern de extracción de datos</h3> <div class="paragraph"> <p>JBake transforma automáticamente los atributos de AsciiDoc en propiedades accesibles en Thymeleaf :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-c4bc3390189a01932c5f0c0f08260fd0.png" alt="Diagram" width="891" height="347"> </div> </div> </div> <div class="sect2"> <h3 id="_convenciones_de_nomenclatura">Convenciones de nomenclatura</h3> <div class="ulist"> <ul> <li> <p><strong>Atributos del proyecto</strong> : prefijo`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>Archivos</strong> : kebab-case (ej:`ecommerce-platform.adoc`)</p> </li> <li> <p><strong>Imágenes</strong> : prefijo nombre-proyecto (ej:`ecommerce-platform-thumb.jpg`)</p> </li> <li> <p><strong>Plantillas</strong> : nombre funcional (ej:)<code>project-card.html</code>, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_flujo_de_publicación">Flujo de publicación</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pipeline_de_desarrollo">Pipeline de desarrollo</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-e380f6590c1ae87c37f44f79ac940cb5.png" alt="Diagram" width="386" height="811"> </div> </div> </div> <div class="sect2"> <h3 id="_entornos">entornos</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Entorno</th> <th class="tableblock halign-left valign-top">Uso</th> <th class="tableblock halign-left valign-top">Estado aceptado</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Local</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Desarrollo y preview</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">borrador, publicado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">puesta en escena</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validación de preproducción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">publicado únicamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Producción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sitio público</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">publicado únicamente</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_extensibilidad">Extensibilidad</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_agregado_de_nuevos_atributos">Agregado de nuevos atributos</h3> <div class="paragraph"> <p>Para enriquecer el modelo de datos, simplemente agregar nuevos atributos prefijados`project-*` :</p> </div> <div class="ulist"> <ul> <li> <p><code>project-awards</code>: Premios y reconocimientos</p> </li> <li> <p>`project-testimonial`Citación del cliente</p> </li> <li> <p>`project-team-size`Tamaño del equipo</p> </li> <li> <p>`project-budget-range`Rango presupuestario</p> </li> </ul> </div> <div class="paragraph"> <p>Estos atributos se vuelven automáticamente disponibles en las plantillas sin modificar el motor JBake.</p> </div> </div> <div class="sect2"> <h3 id="_categorización_avanzada">Categorización avanzada</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-715b7fa02e4000e3ca120493ed040922.png" alt="Diagram" width="561" height="259"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas">Buenas Prácticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_organización_de_los_archivos">Organización de los archivos</h3> <div class="ulist"> <ul> <li> <p><strong>Archivo = proyecto</strong> : evitar mezclar varios proyectos</p> </li> <li> <p><strong>Imágenes en carpeta dedicada</strong><code>assets/img/portfolio/nom-projet/</code></p> </li> <li> <p><strong>Nomenclatura coherente</strong> : facilita la búsqueda y el mantenimiento</p> </li> <li> <p><strong>Versioning Git</strong> : seguimiento completo de las modificaciones</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_gestión_del_contenido">Gestión del contenido</h3> <div class="ulist"> <ul> <li> <p><strong>Estado borrador por defecto</strong>: publicar solo cuando esté listo</p> </li> <li> <p><strong>revisión antes de la publicación</strong>: validación de calidad y confidencialidad</p> </li> <li> <p><strong>Metadatos completos</strong> : completar todos los campos pertinentes</p> </li> <li> <p><strong>Contenido narrativo rico</strong>: no limitarse a los metadatos</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_rendimiento">Rendimiento</h3> <div class="ulist"> <ul> <li> <p><strong>Optimizar imágenes</strong> : compresión antes del commit</p> </li> <li> <p><strong>Paginación si es necesario</strong> : si >20 proyectos</p> </li> <li> <p><strong>Carga diferida</strong> : imágenes de las galerías cargadas bajo demanda</p> </li> <li> <p><strong>Caché del navegador</strong>: encabezados adecuados para activos</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta arquitectura permite:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Facilidad de uso</strong>: agregar un proyecto = crear un archivo de texto</p> </li> <li> <p><strong>Flexibilidad</strong> : extensible mediante nuevos atributos</p> </li> <li> <p><strong>Mantenibilidad</strong> : separación contenido/presentación</p> </li> <li> <p><strong>Trazabilidad</strong> : control de versiones Git completo</p> </li> <li> <p><strong>Automatización</strong> : build y despliegue continuo posibles</p> </li> </ul> </div> <div class="paragraph"> <p>La elección de AsciiDoc garantiza la coherencia con el resto del sitio mientras ofrece la riqueza de los metadatos necesarios para un portafolio profesional.</p> </div> </div> </div> https://cheroliv.com//blog/2026/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/2026/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>En lugar de elegir entre la simplicidad de Supabase y la potencia de Spring Boot, ¿por qué no combinar las dos? Descubre una arquitectura híbrida que aprovecha lo mejor de cada tecnología.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_falso_dilema_de_la_arquitectura_moderna">El Falso Dilema de la Arquitectura Moderna</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando se construye una aplicación moderna con un frontend estático, a menudo nos encontramos frente a una elección binaria</p> </div> <div class="ulist"> <ul> <li> <p><strong>Apostar todo en una solución Backend-as-a-Service</strong>(Supabase, Firebase) - simple pero limitada</p> </li> <li> <p><strong>Construir un backend completo</strong>(Spring Boot, Node.js) - potente pero complejo</p> </li> </ul> </div> <div class="paragraph"> <p>Esta elección es un falso dilema. La arquitectura híbrida propone una tercera vía: <strong>utilizar cada tecnología donde sobresale</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_visión_arquitectónica">Visión Arquitectónica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_arquitectura_tradicional_monolítica">La Arquitectura Tradicional: Monolítica</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1758" height="5652"> </div> </div> <div class="paragraph"> <p>En este enfoque, incluso las operaciones más simples (lectura de un artículo, creación de un comentario) deben pasar por su backend. Paga el costo de la complejidad desde el primer día.</p> </div> </div> <div class="sect2"> <h3 id="_la_arquitectura_baas_todo_delegado">La Arquitectura BaaS: Todo Delegado</h3> <div class="imageblock"> <div class="content"> <img src="baas-architecture.svg" alt="baas architecture" width="504" height="432"> </div> </div> <div class="paragraph"> <p>Por el contrario, delegar todo a un BaaS es atractivo al principio, pero muestra rápidamente sus límites cuando la lógica de negocio se complica.</p> </div> </div> <div class="sect2"> <h3 id="_la_arquitectura_híbrida_separación_de_responsabilidades">La Arquitectura Híbrida: Separación de Responsabilidades</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1637" height="479"> </div> </div> <div class="paragraph"> <p>La arquitectura híbrida separa claramente las responsabilidades según la complejidad y la naturaleza de las operaciones.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_principios_de_diseño">Principios de Diseño</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_1_empezar_de_forma_simple_evolucionar_inteligentemente">Principio 1: Empezar de forma simple, evolucionar inteligentemente</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 14) ] @startuml skinparam backgroundColor #FEFEFE rectangle "**Fase 1 : MVP**" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "Fase 2: Crecimiento" #LightYellow { component "JBake + Supabase ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "**Fase 1 : MVP**" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "Fase 2: Crecimiento" #LightYellow { component "JBake + Supabase + Spring Boot (opcional)" as growth note right ✓ Logique métier émerge ✓ Premiers jobs planifiés ✓ Intégrations tierces end note } rectangle "Fase 3 : Escala" #LightCoral { component "Arquitectura Completa" as scale note right ✓ Orchestration complexe ✓ Performances optimisées ✓ Cache distribué end note } mvp -down-> growth : Quand la complexité\nle justifie growth -down-> scale : Optimisation\ncontinue @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>No construyas Spring Boot si no lo necesitas.</strong>Empieza con Supabase, agrega Spring Boot cuando la complejidad lo justifique.</p> </div> </div> <div class="sect2"> <h3 id="_principio_2_separación_por_naturaleza_de_operación">Principio 2 : Separación por naturaleza de operación</h3> <div class="imageblock"> <div class="content"> <img src="operation-types.svg" alt="operation types" width="1266" height="241"> </div> </div> </div> <div class="sect2"> <h3 id="_principio_3_una_única_fuente_de_verdad">Principio 3: Una única fuente de verdad</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1783" height="5700"> </div> </div> <div class="paragraph"> <p>Al compartir la misma instancia de PostgreSQL, Supabase y Spring Boot trabajan con los mismos datos sin una sincronización compleja.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orquestración_de_los_flujos">Orquestración de los flujos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flujo_1_autenticación_centralizada">Flujo 1 : Autenticación Centralizada</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1079" height="950"> </div> </div> <div class="paragraph"> <p><strong>Punto clave</strong>: Un solo proceso de autenticación, un solo JWT, utilizable en todas partes.</p> </div> </div> <div class="sect2"> <h3 id="_flujo_2_orquestación_de_un_proceso_de_negocio_complejo">Flujo 2: Orquestación de un Proceso de Negocio Complejo</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1301" height="990"> </div> </div> <div class="paragraph"> <p><strong>Lo que Spring Boot aporta</strong>: Orquestación fiable de procesos complejos que involucran varios sistemas con garantía transaccional.</p> </div> </div> <div class="sect2"> <h3 id="_flujo_3_trabajos_planificados_y_sincronizaciones">Flujo 3 : Trabajos Planificados y Sincronizaciones</h3> <div class="imageblock"> <div class="content"> <img src="scheduled-jobs.svg" alt="scheduled jobs" width="1054" height="912"> </div> </div> <div class="paragraph"> <p><strong>Lo que Spring Boot aporta</strong>: Trabajos programados confiables con gestión de estado, reintento automático y ejecución garantizada.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matriz_de_decisión">Matriz de Decisión</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_cuándo_utilizar_supabase">¿Cuándo utilizar Supabase ?</h3> <div class="imageblock"> <div class="content"> <img src="supabase-decision.svg" alt="supabase decision" width="1030" height="445"> </div> </div> </div> <div class="sect2"> <h3 id="_cuándo_usar_spring_boot">¿Cuándo usar Spring Boot?</h3> <div class="imageblock"> <div class="content"> <img src="springboot-decision.svg" alt="springboot decision" width="1142" height="485"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ejemplos_de_arquitectura_por_tipo_de_proyecto">Ejemplos de Arquitectura por Tipo de Proyecto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portafolio">Blog / Portafolio</h3> <div class="imageblock"> <div class="content"> <img src="blog-architecture.svg" alt="blog architecture" width="1328" height="242"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>: 100% Supabase basta con creces.</p> </div> </div> <div class="sect2"> <h3 id="_aplicación_saas">Aplicación SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1769" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>: Arquitectura híbrida necesaria. Supabase para lo esencial, Spring Boot para la parte crítica (pagos, facturación).</p> </div> </div> <div class="sect2"> <h3 id="_e_commerce">e-commerce</h3> <div class="imageblock"> <div class="content"> <img src="ecommerce-architecture.svg" alt="ecommerce architecture" width="1758" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>Spring Boot indispensable. Supabase solo para auth y catálogo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estrategia_de_migración_progresiva">Estrategia de migración progresiva</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="migration-strategy.svg" alt="migration strategy" width="2050" height="954"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_costos_y_consideraciones_operacionales">Costos y Consideraciones Operacionales</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estructura_de_costos">Estructura de costos</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE package "Costos Mensuales Estimados" { rectangle "Fase MVP (0-1000 users)" #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE package "Costos Mensuales Estimados" { rectangle "Fase MVP (0-1000 users)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase de Crecimiento (1k-10k usuarios)" #LightYellow { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot (Cloud Run): 20-50€] [PostgreSQL (si séparé): 0-30€] note bottom: **Total: 20-80€/mois** } rectangle "Fase de Escalada\n(10k-100k usuarios)" #LightCoral { [JBake (Netlify Pro): 19€] [Supabase Pro: 25€] [Spring Boot (instances multiples): 100-300€] [Redis Cache: 20-50€] [Monitoring: 20€] note bottom: **Total: 184-414€/mois** } } note right of "Fase de Escalada\n(10k-100k usuarios)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilidades_operativas">Responsabilidades Operativas</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1773" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_equilibrio_perfecto">Conclusión: El Equilibrio Perfecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida Supabase + Spring Boot no es un compromiso, es una<strong>sinergia</strong>.</p> </div> <div class="paragraph"> <p>.</p> </div> <div class="sect2"> <h3 id="_los_principios_a_tener_en_cuenta">Los principios a tener en cuenta</h3> <div class="imageblock"> <div class="content"> <img src="key-principles.svg" alt="key principles" width="581" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_cuándo_elegir_esta_arquitectura">¿Cuándo elegir esta arquitectura?</h3> <div class="paragraph"> <p><strong>✅ Esta arquitectura es ideal si :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Quieres iniciar rápidamente (MVP en días, no en meses)</p> </li> <li> <p>Anticipas un crecimiento de la complejidad del negocio</p> </li> <li> <p>Quieres minimizar los costos iniciales</p> </li> <li> <p>Le gusta PostgreSQL y quiere una única fuente de verdad</p> </li> <li> <p>Tú aprecias Kotlin y las corutinas para el código de negocio</p> </li> <li> <p>Quieres evitar el vendor lock-in total</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�❌ Esta arquitectura NO es adecuada si :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Tu proyecto es simple y seguirá siéndolo (blog personal → 100% Supabase basta)</p> </li> <li> <p>Ya tienes una pila de backend establecida que dominas</p> </li> <li> <p>Prefiere un monolito tradicional</p> </li> <li> <p>Necesitas .NET, Python u otro lenguaje backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_visión_de_conjunto_final">Visión de Conjunto Final</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 35) ] @startuml skinparam backgroundColor #FEFEFE package "Arquitectura Híbrida Completa" { actor "Usuarios" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend sencillo (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negocio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE package "Arquitectura Híbrida Completa" { actor "Usuarios" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend sencillo (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negocio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL Fuente Única de la Verdad" as db #LightGray users --> [JBake / GitHub Pages] [JBake / GitHub Pages] --> [Auth OAuth2] [JBake / GitHub Pages] --> [CRUD APIs] [JBake / GitHub Pages] --> [Storage] [JBake / GitHub Pages] --> [Realtime] [JBake / GitHub Pages] --> [Orchestration] [Auth OAuth2] --> db [CRUD APIs] --> db [Orchestration] --> db [Jobs Planifiés] --> db [Intégrations] --> db } note bottom of db **Une seule base, deux consommateurs** • Supabase pour le simple • Spring Boot pour le complexe • Aucune synchronisation requise end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_el_mejor_de_los_dos_mundos">El Mejor de los Dos Mundos</h3> <div class="paragraph"> <p>Esta arquitectura le da :</p> </div> <div class="paragraph"> <p><strong>🚀 La velocidad de Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Inicio en horas, no en semanas</p> </li> <li> <p>Autenticación OAuth2 en unos pocos clics</p> </li> <li> <p>APIs REST generados automáticamente</p> </li> <li> <p>Cero configuración del servidor</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💪 La potencia de Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin y Coroutines para código asíncrono elegante</p> </li> <li> <p>Orquestación de procesos de negocio complejos</p> </li> <li> <p>Trabajos programados fiables</p> </li> <li> <p>Transacciones ACID garantizadas</p> </li> <li> <p>Ecosistema Spring completo</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💰 La Economía Progresiva</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ para iniciar y validar</p> </li> <li> <p>Costos que siguen el crecimiento</p> </li> <li> <p>No sobreingeniería prematura</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 La Flexibilidad Arquitectónica</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migración progresiva sin reestructuración</p> </li> <li> <p>Adición de Spring Boot solo si es necesario</p> </li> <li> <p>Sin vendor lock-in total</p> </li> <li> <p>Arquitectura evolutiva</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recursos_técnicos">Recursos Técnicos</h3> <div class="paragraph"> <p><strong>Documentación Supabase:</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guía de autenticación</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Seguridad a nivel de fila</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">APIs generadas automáticamente</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentación de Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot con Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">Corrutinas y Spring</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">Servidor de recursos JWT</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Artículos Complementarios :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Seguridad de las APIs con JWT</p> </li> <li> <p>Optimización del rendimiento de PostgreSQL</p> </li> <li> <p>Patrones de migración progresiva</p> </li> <li> <p>Gestión de errores en arquitectura distribuida</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_casos_de_uso_reales">Casos de uso reales</h3> <div class="paragraph"> <p>Esta arquitectura híbrida se utiliza con éxito en :</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong>: Autenticación Supabase, facturación Spring Boot</p> </li> <li> <p><strong>Mercados</strong>: Catálogo Supabase, transacciones Spring Boot</p> </li> <li> <p><strong>Plataformas de contenido</strong>Artículos Supabase, analítica Spring Boot</p> </li> <li> <p><strong>Herramientas internas</strong>: CRUD Supabase, workflows Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_lista_de_arranque">Lista de arranque</h3> <div class="paragraph"> <p><strong>Fase 1 - Fundaciones (Semana 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Crear cuenta Supabase - [ ] Configurar proyecto PostgreSQL - [ ] Activar autenticación (Google, GitHub) - [ ] Definir esquema inicial - [ ] Configurar Row Level Security - [ ] Probar APIs desde JBake</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 2 - MVP (Semana 2-3)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Implementar páginas principales Integrar autenticación OAuth2 - [ ] Crear formularios CRUD - [ ] Configurar Storage para archivos - [ ] Desplegar en GitHub Pages - [ ] Probar en condiciones reales</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - Evolución (Según necesidades)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identificar necesidades de lógica compleja - [ ] Crear proyecto Spring Boot si es necesario - [ ] Configurar validación JWT Supabase - [ ] Conectar a PostgreSQL Supabase - [ ] Migrar funcionalidades complejas - [ ] Implementar trabajos programados - [ ] Desplegar Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_antipatrones_a_evitar">Antipatrones a Evitar</h3> <div class="paragraph"> <p><strong>�❌ No hacer :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Duplicar los datos entre Supabase y Spring Boot</p> </li> <li> <p>Crear dos bases de datos PostgreSQL separadas</p> </li> <li> <p>Codificar la autenticación usted mismo</p> </li> <li> <p>Utilizar Spring Boot para CRUD simple</p> </li> <li> <p>Sobrediseñar desde el principio</p> </li> <li> <p>Ignorar la seguridad a nivel de fila de Supabase</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Hacer mejor:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Compartir una única base de datos PostgreSQL</p> </li> <li> <p>Dejar que Supabase gestione la autenticación</p> </li> <li> <p>Utilizar Spring Boot solo para la complejidad</p> </li> <li> <p>Empezar simple, evolucionar gradualmente</p> </li> <li> <p>Aprovechar las fortalezas de cada tecnología</p> </li> <li> <p>Asegurar con RLS a nivel de base de datos</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_de_evolución">Perspectivas de Evolución</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_añadido_de_nuevas_capacidades">Añadido de Nuevas Capacidades</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1738" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_escalado_horizontal">Escalado horizontal</h3> <div class="paragraph"> <p>Cuando tu aplicación crece, la arquitectura híbrida escala naturalmente :</p> </div> <div class="paragraph"> <p><strong>Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Escala automáticamente hasta millones de operaciones</p> </li> <li> <p>Read replicas para rendimiento de lectura</p> </li> <li> <p>Recuperación en el punto de tiempo para seguridad</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Múltiples instancias detrás del balanceador de carga</p> </li> <li> <p>El diseño sin estado facilita el escalado horizontal</p> </li> <li> <p>Kubernetes para orquestación si es necesario</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Partitioning para tablas voluminosas</p> </li> <li> <p>Agrupamiento de conexiones (PgBouncer)</p> </li> <li> <p>Sharding si es realmente necesario (raro)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_testimonios_arquitectónicos">Testimonios Arquitectónicos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_usuarios">Startup SaaS (50k usuarios)</h3> <div class="paragraph"> <p><em><em>_ Empezamos con Supabase al 100%. Con 5k usuarios, añadimos Spring Boot únicamente para la facturación de Stripe y los informes mensuales. Un año después, el 80% de nuestras operaciones siguen pasando por Supabase. Spring Boot gestiona solo la parte crítica. Esta separación nos permitió escalar sin una reestructuración. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_plataforma_e_learning_10k_usuarios">Plataforma E-learning (10k usuarios)</h3> <div class="paragraph"> <p><em><em>_ La autenticación OAuth2 de Supabase nos ahorró 3 semanas de desarrollo. Las APIs autogeneradas gestionan todo nuestro catálogo de cursos. Spring Boot solo se utiliza para los certificados PDF y los correos de progreso. Arquitectura simple, mantenible, escalable. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_marketplace_b2b_3k_usuarios">Marketplace B2B (3k usuarios)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot gestiona las transacciones entre compradores y vendedores (crítico). Supabase gestiona todo lo demás: perfiles, mensajería en tiempo real, documentos. El hecho de que compartan la misma base de datos PostgreSQL nos evita toda sincronización compleja. Mejor elección arquitectónica que hemos hecho. </think> </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntesis_un_paradigma_arquitectónico_moderno">Síntesis: Un paradigma arquitectónico moderno</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida Supabase + Spring Boot representa un nuevo paradigma:<strong>la especialización arquitectónica</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 20) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Antiguo Paradigma" #LightCoral { card "Todo en el Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Nuevo Paradigma" #LightGreen { card "Supabase ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "Antiguo Paradigma" #LightCoral { card "Todo en el Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Nuevo Paradigma" #LightGreen { card "Supabase (Comodidad)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (Diferenciación)" { [Logique Métier] [Jobs] [Intégrations] } note bottom Complexité progressive ajoutée seulement si nécessaire end note } [Ancien Paradigme] -right-> [Nouveau Paradigme] : Évolution @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>El principio fundamental:</strong>No construyas lo que ya existe como servicio. Concéntrate en lo que diferencia tu aplicación.</p> </div> <div class="sect2"> <h3 id="_la_regla_del_8020">La regla del 80/20</h3> <div class="paragraph"> <p>En la mayoría de las aplicaciones :</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% de las operaciones</strong>son estándar CRUD → Supabase</p> </li> <li> <p><strong>20% de las operaciones</strong>nécessiten de la lógica de negocio → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>Esta regla natural justifica la arquitectura híbrida.</p> </div> <div class="imageblock"> <div class="content"> <img src="8020-rule.svg" alt="8020 rule" width="1739" height="5652"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_final">Conclusión Final</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida no es un compromiso técnico, es una<strong>decisión estratégica</strong>.</p> </div> <div class="paragraph"> <p><strong>Le permite :</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Iniciar rápidamente con un MVP funcional</p> </li> <li> <p>�✅ Validar tu mercado sin una gran inversión</p> </li> <li> <p>Evolucionar gradualmente cuando la complejidad lo exige</p> </li> <li> <p>Domina tus costos en cada etapa</p> </li> <li> <p>Exploitar lo mejor de cada tecnología</p> </li> <li> <p>✅ Evitar el sobreingeniería prematuro</p> </li> <li> <p>�✅ Mantener la flexibilidad para el futuro</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Ella representa :</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯<strong>Pragmatismo</strong>: Cada tecnología donde sobresale</p> </li> <li> <p>🚀<strong>Velocidad</strong>: Time-to-market mínimo</p> </li> <li> <p>�💰<strong>Economía</strong>Costos alineados con el valor</p> </li> <li> <p>�🔮<strong>Escalabilidad</strong>: Arquitectura que crece contigo</p> </li> <li> <p>�🛡️<strong>Robustez</strong>: Servicios probados y fiables</p> </li> </ul> </div> <div class="sect2"> <h3 id="_su_próximo_paso">Su Próximo Paso</h3> <div class="paragraph"> <p>Si esta arquitectura te habla, aquí está por dónde empezar:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Cree una cuenta Supabase</strong>(gratuito)</p> </li> <li> <p><strong>Define tu esquema de datos mínimo</strong></p> </li> <li> <p><strong>Configura la autenticación OAuth2</strong></p> </li> <li> <p><strong>Crea tu primera página JBake que consume la API</strong></p> </li> <li> <p><strong>Despliega en GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Tendrás un MVP funcional en<strong>unos días</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot llegará de forma natural cuando lo necesites. No antes.</p> </div> <hr> <div class="paragraph"> <p><strong>La arquitectura híbrida, es el arte de construir exactamente lo necesario, cuando es necesario.</strong></p> </div> <div class="paragraph"> <p><em>¡Buen desarrollo! 🚀</em></p> </div> <hr> <div class="paragraph"> <p><em>Comparte este artículo si crees que puede ayudar a otros desarrolladores a tomar las decisiones arquitectónicas correctas.</em></p> </div> </div> </div> </div> https://cheroliv.com//blog/pilot-batch/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/pilot-batch/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tiempo de lectura : 12 minutes</div> <p>En lugar de elegir entre la simplicidad de Supabase y la potencia de Spring Boot, ¿por qué no combinar ambos? Descubre una arquitectura híbrida que aproveche lo mejor de cada tecnología.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_el_falso_dilema_de_la_arquitectura_moderna">El Falso Dilema de la Arquitectura Moderna</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cuando se construye una aplicación moderna con un frontend estático, a menudo nos encontramos frente a una opción binaria:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Apostarlo todo a una solución Backend-as-a-Service</strong>(Supabase, Firebase) - simple pero limitada</p> </li> <li> <p><strong>Construir un backend completo</strong>(Spring Boot, Node.js) - poderoso pero complejo</p> </li> </ul> </div> <div class="paragraph"> <p>Esta elección es un falso dilema. La arquitectura híbrida propone una tercera vía: <strong>usar cada tecnología donde sobresale</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_visión_arquitectónica">Visión Arquitectónica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_arquitectura_tradicional_monolítica">La Arquitectura Tradicional: Monolítica</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1770" height="5652"> </div> </div> <div class="paragraph"> <p>En este enfoque, incluso las operaciones más simples (lectura de un artículo, creación de un comentario) deben transitar por tu backend. Pagas el costo de la complejidad desde el primer día.</p> </div> </div> <div class="sect2"> <h3 id="_la_arquitectura_baas_todo_delegado">La arquitectura BaaS : Todo delegado</h3> <div class="imageblock"> <div class="content"> <img src="baas-architecture.svg" alt="baas architecture" width="504" height="432"> </div> </div> <div class="paragraph"> <p>Al contrario, delegar todo a un BaaS resulta atractivo al principio, pero muestra rápidamente sus límites cuando la lógica de negocio se complica.</p> </div> </div> <div class="sect2"> <h3 id="_la_arquitectura_híbrida_separación_de_responsabilidades">La Arquitectura Híbrida: Separación de Responsabilidades</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1611" height="479"> </div> </div> <div class="paragraph"> <p>La arquitectura híbrida separa claramente las responsabilidades según la complejidad y la naturaleza de las operaciones.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_principios_de_diseño">Principios de Diseño</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_1_empezar_simple_evolucionar_inteligentemente">Principio 1: Empezar simple, evolucionar inteligentemente</h3> <div class="imageblock"> <div class="content"> <img src="evolution-phases.svg" alt="evolution phases" width="460" height="392"> </div> </div> <div class="paragraph"> <p><strong>No construyas Spring Boot si no lo necesitas.</strong>Empiece con Supabase, añada Spring Boot cuando la complejidad lo justifica.</p> </div> </div> <div class="sect2"> <h3 id="_principio_2_separación_por_naturaleza_de_la_operación">Principio 2 : Separación por naturaleza de la operación</h3> <div class="imageblock"> <div class="content"> <img src="operation-types.svg" alt="operation types" width="1266" height="241"> </div> </div> </div> <div class="sect2"> <h3 id="_principio_3_una_única_fuente_de_verdad">Principio 3 : Una única fuente de verdad</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1736" height="5700"> </div> </div> <div class="paragraph"> <p>Al compartir la misma instancia de PostgreSQL, Supabase y Spring Boot trabajan en los mismos datos sin sincronización compleja.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orquestación_de_los_flujos">Orquestación de los flujos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flujo_1_autenticación_centralizada">Flujo 1: Autenticación centralizada</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1079" height="950"> </div> </div> <div class="paragraph"> <p><strong>Punto clave</strong>Un solo proceso de autenticación, un solo JWT, utilizable en todas partes.</p> </div> </div> <div class="sect2"> <h3 id="_flujo_2_orquestación_de_un_proceso_de_negocio_complejo">Flujo 2: Orquestación de un proceso de negocio complejo</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1242" height="990"> </div> </div> <div class="paragraph"> <p><strong>Lo que Spring Boot aporta</strong>: Orquestación fiable de procesos complejos que involucran varios sistemas con garantía transaccional.</p> </div> </div> <div class="sect2"> <h3 id="_flujo_3_trabajos_programados_y_sincronizaciones">Flujo 3: Trabajos Programados y Sincronizaciones</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE participant "Scheduler ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE participant "Scheduler (Spring Boot)" as scheduler participant "Report Service" as report participant "PostgreSQL" as db participant "API externa" as api participant "Servicio de correo electrónico" as email participant "Supabase Storage" as storage == Job Quotidien : 2h00 == activate scheduler scheduler -> report : Déclenche génération rapport activate report report -> db : Récupère données\ndes dernières 24h db -> report : Dataset report -> report : Calculs & Agrégations report -> report : Génération PDF report -> storage : Upload PDF storage -> report : URL publique report -> email : Envoie aux admins\navec lien PDF deactivate report == Job Hebdomadaire : Dimanche 3h00 == scheduler -> report : Synchronisation externe activate report report -> api : Fetch données externes api -> report : Nouvelles données report -> db : Mise à jour tables report -> db : Nettoyage données obsolètes deactivate report == Job Mensuel : 1er du mois == scheduler -> report : Facturation activate report report -> db : Liste clients actifs report -> report : Calcul montants report -> api : Génération factures (Stripe) report -> email : Envoi factures deactivate report deactivate scheduler note right of scheduler **Impossible avec Supabase seul** Edge Functions non adaptées pour jobs longs et récurrents end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Lo que Spring Boot aporta</strong>: Trabajos programados fiables con gestión de estado, reintento automático y ejecución garantizada.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matriz_de_decisión">Matriz de Decisión</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_cuándo_usar_supabase">¿Cuándo usar Supabase?</h3> <div class="imageblock"> <div class="content"> <img src="supabase-decision.svg" alt="supabase decision" width="1030" height="445"> </div> </div> </div> <div class="sect2"> <h3 id="_cuándo_usar_spring_boot">¿Cuándo usar Spring Boot?</h3> <div class="imageblock"> <div class="content"> <img src="springboot-decision.svg" alt="springboot decision" width="1142" height="485"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ejemplos_de_arquitectura_por_tipo_de_proyecto">Ejemplos de Arquitectura por Tipo de Proyecto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portafolio">Blog / Portafolio</h3> <div class="imageblock"> <div class="content"> <img src="blog-architecture.svg" alt="blog architecture" width="1328" height="242"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>: 100% Supabase es más que suficiente.</p> </div> </div> <div class="sect2"> <h3 id="_aplicación_saas">Aplicación SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1784" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>: Arquitectura híbrida necesaria. Supabase para lo esencial, Spring Boot para la parte crítica (pagos, facturación).</p> </div> </div> <div class="sect2"> <h3 id="_ecommerce">e‑commerce</h3> <div class="imageblock"> <div class="content"> <img src="ecommerce-architecture.svg" alt="ecommerce architecture" width="1738" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Veredicto</strong>Spring Boot indispensable. Supabase solo para auth y catálogo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estrategia_de_migración_progresiva">Estrategia de Migración Progresiva</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="migration-strategy.svg" alt="migration strategy" width="2050" height="954"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_costos_y_consideraciones_operacionales">Costos y consideraciones operacionales</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estructura_de_costos">Estructura de Costos</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE package "Costos Mensuales Estimados" { rectangle "Fase MVP (0-1000 usuarios)" #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE package "Costos Mensuales Estimados" { rectangle "Fase MVP (0-1000 usuarios)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase Crecimiento\n(1k-10k usuarios)" #LightYellow { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot (Cloud Run): 20-50€] [PostgreSQL (si séparé): 0-30€] note bottom: **Total: 20-80€/mois** } rectangle "Escala de fase (10k-100k usuarios)" #LightCoral { [JBake (Netlify Pro): 19€] [Supabase Pro: 25€] [Spring Boot (instances multiples): 100-300€] [Redis Cache: 20-50€] [Monitoring: 20€] note bottom: **Total: 184-414€/mois** } } note right of "Escala de fase (10k-100k usuarios)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilidades_operativas">Responsabilidades Operativas</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1749" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_el_equilibrio_perfecto">Conclusión: El Equilibrio Perfecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida Supabase + Spring Boot no es un compromiso, es una<strong>sinergia</strong>.</p> </div> <div class="sect2"> <h3 id="_los_principios_a_retener">Los principios a retener</h3> <div class="imageblock"> <div class="content"> <img src="key-principles.svg" alt="key principles" width="581" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_cuándo_elegir_esta_arquitectura">¿Cuándo elegir esta arquitectura?</h3> <div class="paragraph"> <p><strong>✅ Esta arquitectura es ideal si:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Quieres arrancar rápidamente (MVP en días, no en meses)</p> </li> <li> <p>Anticipas un crecimiento de la complejidad del negocio</p> </li> <li> <p>Quieres minimizar los costos iniciales</p> </li> <li> <p>Te gusta PostgreSQL y quieres una única fuente de verdad</p> </li> <li> <p>Ustedes aprecian Kotlin y las Corrutinas para el código de negocio</p> </li> <li> <p>Quieres evitar el vendor lock-in total</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�❌ Esta arquitectura NO es adecuada si :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Tu proyecto es simple y lo seguirá siendo (blog personal → 100% Supabase es suficiente)</p> </li> <li> <p>Ya tienes una stack backend establecida que dominas</p> </li> <li> <p>Prefiere un monolito tradicional</p> </li> <li> <p>Necesitas .NET, Python, u otro lenguaje backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_visión_general_final">Visión General Final</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 35) ] @startuml skinparam backgroundColor #FEFEFE package "Arquitectura Híbrida Completa" { actor "Usuarios" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend simple (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negocio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE package "Arquitectura Híbrida Completa" { actor "Usuarios" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend simple (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negocio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL Fuente Única de Verdad" as db #LightGray users --> [JBake / GitHub Pages] [JBake / GitHub Pages] --> [Auth OAuth2] [JBake / GitHub Pages] --> [CRUD APIs] [JBake / GitHub Pages] --> [Storage] [JBake / GitHub Pages] --> [Realtime] [JBake / GitHub Pages] --> [Orchestration] [Auth OAuth2] --> db [CRUD APIs] --> db [Orchestration] --> db [Jobs Planifiés] --> db [Intégrations] --> db } note bottom of db **Une seule base, deux consommateurs** • Supabase pour le simple • Spring Boot pour le complexe • Aucune synchronisation requise end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_lo_mejor_de_los_dos_mundos">Lo mejor de los dos mundos</h3> <div class="paragraph"> <p>Esta arquitectura le da :</p> </div> <div class="paragraph"> <p><strong>🚀 La velocidad de Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Inicio en horas, no en semanas</p> </li> <li> <p>Autenticación OAuth2 en unos pocos clics</p> </li> <li> <p>APIs REST generados automáticamente</p> </li> <li> <p>Cero configuración de servidor</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💪 La potencia de Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin y Coroutines para código asíncrono elegante</p> </li> <li> <p>Orquestación de procesos de negocio complejos</p> </li> <li> <p>Trabajos programados confiables</p> </li> <li> <p>Transacciones ACID garantizadas</p> </li> <li> <p>Ecosistema Spring completo</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 La Economía Progresiva</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ para empezar y validar</p> </li> <li> <p>Costos que siguen el crecimiento</p> </li> <li> <p>No hay sobreingeniería prematura</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 La Flexibilidad Arquitectónica</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migración progresiva sin rediseño</p> </li> <li> <p>Añadir Spring Boot solo si es necesario</p> </li> <li> <p>Sin vendor lock-in total</p> </li> <li> <p>Arquitectura evolutiva</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recursos_técnicos">Recursos Técnicos</h3> <div class="paragraph"> <p><strong>Documentación Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guía de Autenticación</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Seguridad a nivel de fila</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">APIs generadas automáticamente</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentación Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot con Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">Coroutines y Spring</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">JWT Resource Server</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Artículos Complementarios :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Seguridad de las APIs con JWT</p> </li> <li> <p>Optimización del rendimiento de PostgreSQL</p> </li> <li> <p>Patrones de migración progresiva</p> </li> <li> <p>Manejo de errores en arquitectura distribuida</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_casos_de_uso_reales">Casos de uso reales</h3> <div class="paragraph"> <p>Esta arquitectura híbrida se utiliza con éxito en :</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong>Autenticación Supabase, facturación Spring Boot</p> </li> <li> <p><strong>marketplaces</strong>: Catálogo Supabase, transactions Spring Boot</p> </li> <li> <p><strong>Plataformas de contenido</strong>: Artículos Supabase, analítica Spring Boot</p> </li> <li> <p><strong>Herramientas internas</strong>CRUD Supabase, workflows Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_checklist_de_arranque">Checklist de Arranque</h3> <div class="paragraph"> <p><strong>Fase 1 - Fundamentos (Semana 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Crear cuenta Supabase - [ ] Configurar proyecto PostgreSQL - [ ] Activar Autenticación (Google, GitHub) - [ ] Definir esquema inicial - [ ] Configurar la seguridad a nivel de fila - [ ] Probar APIs desde JBake</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fase 2 - MVP (Semana 2-3)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Implementar páginas principales - [ ] Integrar autenticación OAuth2 - [ ] Crear formularios CRUD - [ ] Configurar Storage para archivos - [ ] Desplegar en GitHub Pages - [ ] Probar en condiciones reales</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - Evolución (Según necesidades)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identificar necesidades de lógica compleja - [ ] Crear proyecto Spring Boot si es necesario - [ ] Configurar validación JWT Supabase - [ ] Conectar a PostgreSQL Supabase - [ ] Migrar funcionalidades complejas - [ ] Implementar trabajos programados - [ ] Desplegar Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_antipatrones_a_evitar">Antipatrones a evitar</h3> <div class="paragraph"> <p><strong>No hacer:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Duplicar los datos entre Supabase y Spring Boot</p> </li> <li> <p>Crear dos bases de datos PostgreSQL separadas</p> </li> <li> <p>Codificar la autenticación usted mismo</p> </li> <li> <p>Usar Spring Boot para un CRUD sencillo</p> </li> <li> <p>sobrediseñar desde el principio</p> </li> <li> <p>Ignorar Row Level Security de Supabase</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ Hacer mejor :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Compartir una única base de datos PostgreSQL</p> </li> <li> <p>Dejar que Supabase gestione la autenticación</p> </li> <li> <p>Utilizar Spring Boot solo para la complejidad</p> </li> <li> <p>Empezar simple, evolucionar gradualmente</p> </li> <li> <p>Explotar las fortalezas de cada tecnología</p> </li> <li> <p>Asegurar con RLS a nivel de base de datos</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_de_evolución">Perspectivas de Evolución</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adición_de_nuevas_capacidades">Adición de Nuevas Capacidades</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1746" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_escalado_horizontal">Escalado Horizontal</h3> <div class="paragraph"> <p>Cuando su aplicación crece, la arquitectura híbrida escala naturalmente :</p> </div> <div class="paragraph"> <p><strong>Supabase:</strong></p> </div> <div class="ulist"> <ul> <li> <p>escala automáticamente hasta millones de operaciones</p> </li> <li> <p>Réplicas de lectura para rendimiento de lectura</p> </li> <li> <p>Point-in-time recovery para seguridad</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Múltiples instancias detrás de balanceador de carga</p> </li> <li> <p>Diseño sin estado facilita el escalado horizontal</p> </li> <li> <p>Kubernetes para orquestación si es necesario</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Particionamiento para tablas voluminosas</p> </li> <li> <p>Pooling de conexiones (PgBouncer)</p> </li> <li> <p>Sharding si realmente necesario (raro)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_testimonios_arquitectónicos">Testimonios arquitectónicos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_usuarios">Startup SaaS (50k usuarios)</h3> <div class="paragraph"> <p><em><em>_ Empezamos con Supabase al 100%. Con 5k usuarios, agregamos Spring Boot solo para la facturación de Stripe y los informes mensuales. Un año después, el 80% de nuestras operaciones sigue pasando por Supabase. Spring Boot gestiona solo la parte crítica. Esta separación nos permitió escalar sin rediseño. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_plataforma_e_learning_10k_usuarios">Plataforma E-learning (10k usuarios)</h3> <div class="paragraph"> <p><em><em>_ La autenticación OAuth2 de Supabase nos ha ahorrado 3 semanas de desarrollo. Las APIs autogeneradas gestionan todo nuestro catálogo de cursos. Spring Boot solo se utiliza para los certificados PDF y los correos de progreso. Arquitectura simple, mantenible y escalable. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_marketplace_b2b_3k_usuarios">Marketplace B2B (3k usuarios)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot gestiona las transacciones entre compradores y vendedores (crítica). Supabase gestiona todo lo demás: perfiles, mensajería en tiempo real, documentos. El hecho de que compartan la misma base de datos PostgreSQL nos evita cualquier sincronización compleja. Mejor elección arquitectónica que hayamos hecho. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntesis_un_paradigma_arquitectónico_moderno">Síntesis : Un Paradigma Arquitectónico Moderno</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida Supabase + Spring Boot representa un nuevo paradigma:<strong>la especialización arquitectónica</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 20) ] @startuml skinparam backgroundColor #FEFEFE rectangle "paradigma antiguo" #LightCoral { card "Todo en el Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Nuevo Paradigma" #LightGreen { card "Supabase ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "paradigma antiguo" #LightCoral { card "Todo en el Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Nuevo Paradigma" #LightGreen { card "Supabase (Comodidad)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (Diferenciación)" { [Logique Métier] [Jobs] [Intégrations] } note bottom Complexité progressive ajoutée seulement si nécessaire end note } [Ancien Paradigme] -right-> [Nouveau Paradigme] : Évolution @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>El principio fundamental :</strong>No construyas lo que ya existe como servicio. Concéntrate en lo que diferencia tu aplicación.</p> </div> <div class="sect2"> <h3 id="_la_regla_del_8020">La regla del 80/20</h3> <div class="paragraph"> <p>En la mayoría de las aplicaciones :</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% de las operaciones</strong>son CRUD estándar → Supabase</p> </li> <li> <p><strong>20% de las operaciones</strong>necesitan de la lógica de negocio → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>Esta regla natural justifica la arquitectura híbrida.</p> </div> <div class="imageblock"> <div class="content"> <img src="8020-rule.svg" alt="8020 rule" width="1739" height="5652"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_final">Conclusión Final</h2> <div class="sectionbody"> <div class="paragraph"> <p>La arquitectura híbrida no es un compromiso técnico, es una<strong>decisión estratégica</strong>.</p> </div> <div class="paragraph"> <p><strong>Le permite:</strong></p> </div> <div class="ulist"> <ul> <li> <p>�✅ Iniciar rápidamente con un MVP funcional</p> </li> <li> <p>✅ Validar su mercado sin una inversión pesada</p> </li> <li> <p>�✅ Evolucionar progresivamente cuando la complejidad lo exija</p> </li> <li> <p>�✅ Controlar tus costos en cada paso</p> </li> <li> <p>✅ Aprovechar lo mejor de cada tecnología</p> </li> <li> <p>�✅ Evitar la sobre-ingeniería prematura</p> </li> <li> <p>�✅ Conservar la flexibilidad para el futuro</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Ella representa :</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯<strong>Pragmatismo</strong>: Cada tecnología en la que destaca</p> </li> <li> <p>🚀<strong>velocidad</strong>: Tiempo de comercialización mínimo</p> </li> <li> <p>💰<strong>Economía</strong>Costos alineados con el valor</p> </li> <li> <p>🔮<strong>Escalabilidad</strong>Arquitectura que crece contigo</p> </li> <li> <p>�🛡️<strong>robustez</strong>Servicios probados y confiables</p> </li> </ul> </div> <div class="sect2"> <h3 id="_tu_próximo_paso">Tu próximo paso</h3> <div class="paragraph"> <p>Si esta arquitectura te habla, aquí tienes por dónde comenzar:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Crear una cuenta Supabase</strong>(gratuito)</p> </li> <li> <p><strong>Define tu esquema de datos mínimo</strong></p> </li> <li> <p><strong>Configura la autenticación OAuth2</strong></p> </li> <li> <p><strong>Cree su primera página JBake que consume la API</strong></p> </li> <li> <p><strong>Despliega en GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Tendrás un MVP funcional en<strong>unos días</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot llegará naturalmente cuando lo necesites. No antes.</p> </div> <hr> <div class="paragraph"> <p><strong>La arquitectura híbrida es el arte de construir exactamente lo que se necesita, cuando se necesita.</strong></p> </div> <div class="paragraph"> <p><em>Buen desarrollo ! 🚀</em></p> </div> <hr> <div class="paragraph"> <p><em>Comparte este artículo si crees que puede ayudar a otros desarrolladores a tomar las decisiones arquitectónicas correctas.</em></p> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0098_preloading_css_variable_post.html Sat, 15 Nov 2025 00:00:00 +0000 blog/2025/0098_preloading_css_variable_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_resumen">Resumen</a></li> <li><a href="#_el_problema_este_maldito_parpadeo_de_tema">El Problema : Este Maldito Parpadeo de Tema</a> <ul class="sectlevel2"> <li><a href="#_una_pesadilla_para_la_experiencia_de_usuario">Una pesadilla para la experiencia de usuario</a></li> <li><a href="#_el_fouc_un_viejo_problema_web">El FOUC: Un viejo problema web</a></li> <li><a href="#_impacto_en_la_percepción_de_calidad">Impacto en la Percepción de Calidad</a></li> <li><a href="#_análisis_técnico_del_problema">Análisis Técnico del Problema</a></li> </ul> </li> <li><a href="#_por_qué_un_script_clásico_no_es_suficiente">¿Por qué un Script Clásico no es suficiente?</a> <ul class="sectlevel2"> <li><a href="#_el_enfoque_intuitivo_pero_ineficaz">El Enfoque Intuitivo pero Ineficaz</a></li> <li><a href="#_entender_el_evento_domcontentloaded">Entender el evento DOMContentLoaded</a></li> <li><a href="#_el_problema_del_render_blocking">El problema del Render Blocking</a></li> <li><a href="#_visualización_del_problema">Visualización del Problema</a></li> <li><a href="#_los_intentos_de_solución_ineficaces">Los intentos de solución ineficaces</a></li> <li><a href="#_la_verdadera_solución_actuar_más_temprano">La Verdadera Solución : Actuar Más Temprano</a></li> </ul> </li> <li><a href="#_la_solución_la_carga_temprana_early_loading">La solución : La carga temprana (Early Loading)</a> <ul class="sectlevel2"> <li><a href="#_principio_fundamental">Principio Fundamental</a></li> <li><a href="#_por_qué_el_head_es_el_lugar_ideal">¿Por qué el <code><head></code> es el Lugar Ideal</a></li> <li><a href="#_arquitectura_de_la_solución_en_tres_capas">Arquitectura de la solución en tres capas</a></li> </ul> </li> <li><a href="#_paso_1_guardar_la_selección_del_usuario">Paso 1: Guardar la Selección del Usuario</a> <ul class="sectlevel2"> <li><a href="#_el_localstorage_tu_memoria_persistente">El localStorage : Tu Memoria Persistente</a></li> <li><a href="#_implementación_de_la_copia_de_seguridad_del_tema">Implementación de la copia de seguridad del tema</a></li> <li><a href="#_gestión_de_casos_de_error">Gestión de Casos de Error</a></li> <li><a href="#_estrategias_avanzadas_de_persistencia">Estrategias Avanzadas de Persistencia</a></li> </ul> </li> <li><a href="#_paso_2_el_script_de_precarga_dentro_del_head">Paso 2: El script de pre‑carga dentro del `<head></a> <ul class="sectlevel2"> <li><a href="#_el_corazón_de_la_solución">El Corazón de la Solución</a></li> <li><a href="#_anatomía_del_script_cada_línea_cuenta">Anatomía del Script: Cada Línea Cuenta</a></li> <li><a href="#_detección_de_la_preferencia_del_sistema_bonus">Detección de la Preferencia del Sistema (Bonus)</a></li> <li><a href="#_rendimiento_por_qué_este_script_es_rápido">Rendimiento: ¿Por qué este script es rápido?</a></li> <li><a href="#_colocación_óptima_en_el_head">Colocación Óptima en el `<head></a></li> </ul> </li> <li><a href="#_paso_3_el_poder_de_los_selectores_de_atributos_css">Paso 3: El poder de los selectores de atributos CSS</a> <ul class="sectlevel2"> <li><a href="#_el_sistema_de_tema_de_bootstrap_5">El Sistema de Tema de Bootstrap 5</a></li> <li><a href="#_estructura_css_para_un_sistema_de_tema">Estructura CSS para un Sistema de Tema</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_resumen">Resumen</h2> <div class="sectionbody"> <div class="paragraph"> <p>En este artículo técnico en profundidad, exploramos cómo implementar un selector de tema (light/dark) sin el desagradable efecto de parpadeo que ocurre durante la carga de la página. Analizamos en detalle el ciclo de renderizado del navegador, las causas profundas del FOUC (Flash of Unstyled Content), y proponemos una solución robusta basada en la pre-carga síncrona en el`<head>`. Esta técnica garantiza una experiencia de usuario fluida y profesional.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_este_maldito_parpadeo_de_tema">El Problema : Este Maldito Parpadeo de Tema</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_una_pesadilla_para_la_experiencia_de_usuario">Una pesadilla para la experiencia de usuario</h3> <div class="paragraph"> <p>Imagina la escena: has pasado horas diseñando un magnífico tema oscuro para tu aplicación web. Los colores están perfectamente equilibrados, el contraste es óptimo y tus usuarios adoran esta opción. Pero hay un problema embarazoso: cada vez que se recarga la página, durante una fracción de segundo, el tema claro predeterminado se muestra antes de que el tema oscuro tome el relevo.</p> </div> <div class="paragraph"> <p>Este "flash" visual, aunque breve (a veces menos de 100 ms), es inmediatamente perceptible por el ojo humano y crea una experiencia desagradable. Para los usuarios que han elegido el tema oscuro por razones de comodidad visual o accesibilidad, este parpadeo incluso puede ser doloroso, particularmente en un entorno poco iluminado.</p> </div> </div> <div class="sect2"> <h3 id="_el_fouc_un_viejo_problema_web">El FOUC: Un viejo problema web</h3> <div class="paragraph"> <p>Este fenómeno es una variante de lo que se conoce como "Flash of Unstyled Content" (FOUC), un problema clásico del desarrollo web que se remonta a los primeros días del CSS. El FOUC ocurre cuando el navegador muestra temporalmente contenido HTML sin sus estilos CSS aplicados, creando un destello de contenido sin estilo.</p> </div> <div class="paragraph"> <p>En nuestro caso específico, no hablamos de un contenido completamente sin estilo, sino más bien de un<strong>Destello del tema equivocado</strong>(FOWT) - el contenido está estilizado, pero con el tema equivocado. Esto es particularmente frustrante porque muestra que nuestra aplicación "olvida" la préférence del usuario en cada carga de página.</p> </div> </div> <div class="sect2"> <h3 id="_impacto_en_la_percepción_de_calidad">Impacto en la Percepción de Calidad</h3> <div class="paragraph"> <p>Este problema, aunque técnico, tiene importantes repercusiones en la percepción de la calidad de su aplicación :</p> </div> <div class="paragraph"> <p><strong>Falta de pulido</strong>: El parpadeo da la impresión de una aplicación inacabada o mal optimizada. Los usuarios suelen asociar estos pequeños defectos visuales con una falta de profesionalismo general.</p> </div> <div class="paragraph"> <p><strong>Ruptura de coherencia</strong>: La aplicación parece 'olvidar' las preferencias del usuario, creando una sensación de desincronización entre la interfaz y las expectativas.</p> </div> <div class="paragraph"> <p><strong>Fatiga visual</strong>Para los usuarios sensibles a la luz o que sufren de migrañas, este flash luminoso puede ser más que una simple molestia estética.</p> </div> <div class="paragraph"> <p><strong>Rendimiento percibido</strong>Irónicamente, incluso si tu sitio se carga rápidamente, este parpadeo puede dar la impresión de una aplicación lenta o poco receptiva.</p> </div> </div> <div class="sect2"> <h3 id="_análisis_técnico_del_problema">Análisis Técnico del Problema</h3> <div class="paragraph"> <p>Para entender cómo resolver este problema, primero hay que entender por qué ocurre. El parpadeo se produce debido a un desfase temporal entre tres eventos críticos en el ciclo de vida de una página web :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>El parseado inicial del HTML</strong>: El navegador lee y analiza la estructura de su página</p> </li> <li> <p><strong>La aplicación de los estilos CSS</strong>: El navegador aplica las reglas CSS y calcula el renderizado visual</p> </li> <li> <p><strong>La ejecución del JavaScript</strong>: Tu código que cambia el tema se ejecuta</p> </li> </ol> </div> <div class="paragraph"> <p>El problema ocurre cuando el evento n°3 (ejecución del JavaScript) llega después de que el navegador ya haya comenzado o terminado el evento n°2 (aplicación de estilos). En ese momento, el navegador ya ha tomado una decisión sobre qué tema mostrar, y tu código llega demasiado tarde para influir antes del primer renderizado.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_un_script_clásico_no_es_suficiente">¿Por qué un Script Clásico no es suficiente?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_enfoque_intuitivo_pero_ineficaz">El Enfoque Intuitivo pero Ineficaz</h3> <div class="paragraph"> <p>El enfoque más natural para un desarrollador sería colocar un script al final de nuestro`<body>`que verifica el tema preferido del usuario y lo aplica. Este enfoque sigue las mejores prácticas tradicionales de la web que recomiendan cargar los scripts al final de la página para no bloquear el renderizado.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// À la fin de <body> - L'APPROCHE INSUFFISANTE document.addEventListener('DOMContentLoaded', () => { const theme = localStorage.getItem('preferred-theme'); if (theme === 'dark') { document.documentElement.setAttribute('data-bs-theme', 'dark'); } });</code></pre> </div> </div> <div class="paragraph"> <p>Este enfoque parece lógico a primera vista. Esperamos a que el DOM esté listo, luego aplicamos el tema. ¿Simple, no? Desafortunadamente, esta simplicidad esconde un defecto fundamental relacionado con el tiempo del ciclo de renderizado del navegador.</p> </div> </div> <div class="sect2"> <h3 id="_entender_el_evento_domcontentloaded">Entender el evento DOMContentLoaded</h3> <div class="paragraph"> <p>El evento`DOMContentLoaded`se dispara cuando el documento HTML inicial ha sido completamente cargado y analizado por el navegador,<strong>sin esperar</strong>el final de la carga de las hojas de estilo, de las imágenes y de los submarcos. Es un punto importante de entender.</p> </div> <div class="paragraph"> <p>Esta es la secuencia típica de los eventos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>El navegador comienza a descargar el HTML</p> </li> <li> <p>Analiza el HTML mientras lo recibe.</p> </li> <li> <p>Él descubre las etiquetas`<link>`para los CSS y comienza a descargarlos</p> </li> <li> <p>Él descubre las etiquetas`<script>`y los ejecuta (según su tipo y atributos)</p> </li> <li> <p>Construye el DOM (Modelo de Objetos de Documento)</p> </li> <li> <p><strong>El evento <code>DOMContentLoaded</code> se dispara</strong></p> </li> <li> <p>Continúa aplicando los estilos y haciendo el layout</p> </li> <li> <p>El primer paint (visualización) se produce</p> </li> <li> <p>El evento`load`se dispara cuando todos los recursos están cargados</p> </li> </ol> </div> <div class="paragraph"> <p>¿El problema? Entre el paso 6 (DOMContentLoaded) y el paso 8 (primer paint), el navegador ya ha tomado decisiones sobre cómo mostrar la página. Si tu script de cambio de tema se ejecuta en el paso 6, ya es demasiado tarde para evitar una primera visualización con los estilos por defecto.</p> </div> </div> <div class="sect2"> <h3 id="_el_problema_del_render_blocking">El problema del Render Blocking</h3> <div class="paragraph"> <p>En realidad, el momento es aún más complejo. Los navegadores modernos utilizan técnicas de optimización sofisticadas para mejorar el rendimiento percibido. Tratan de hacer el primer pintado (First Contentful Paint) lo más rápidamente posible para que el usuario vea algo en la pantalla.</p> </div> <div class="paragraph"> <p>Los CSS son "render-blocking" por defecto, lo que significa que el navegador espera haber descargado y analizado las hojas de estilo antes de hacer la primera pintura. Es lógico: no queremos mostrar contenido sin estilo.</p> </div> <div class="paragraph"> <p>Pero aquí está la trampa: cuando el navegador aplica estos estilos CSS por primera vez, lo hace basándose en el estado actual del DOM. Si el atributo`data-bs-theme`aún no está definido en la etiqueta`<html>`, el navegador aplicará los estilos predeterminados (generalmente el tema claro).</p> </div> <div class="paragraph"> <p>Luego, cuando tu script se ejecuta y cambia este atributo, el navegador debe:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Recalcular todos los estilos afectados por este cambio</p> </li> <li> <p>Rehacer el layout si es necesario</p> </li> <li> <p>Repintar los elementos afectados</p> </li> </ol> </div> <div class="paragraph"> <p>Este proceso de recálculo y repintado es lo que causa el parpadeo visible.</p> </div> </div> <div class="sect2"> <h3 id="_visualización_del_problema">Visualización del Problema</h3> <div class="paragraph"> <p>Para comprender mejor esta secuencia problemática, examinemos un diagrama de secuencia detallado:</p> </div> <div id="diag-flux-incorrect" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 28) ] @startuml actor Utilisateur participant Navigateur participant "Analizador HTML" as Parser participant "CSSOM" as CSS participant "Script.js (fin del cuerpo)" as Script participant "Motor de renderizado" as Render Utilisateur -> Navigateur: Demande la page activate Navigateur Navigateur -> Parser: Parse le HTML activate Parser Parser -> CSS: Découvre et charge les CSS activate CSS Parser -> Parser: Construit le DOM Parser -> Navigateur: DOM Ready (DOMContentLoaded) deactivate Parser CSS -> CSS: Parse les feuilles de style CSS -> Render: CSSOM Ready deactivate CSS activate Render Render -> Render: Calcule les styles avec data-bs-theme=""note right: Tema por defecto (light) Render -> Navegador: Primer Pintura (Tema Claro) note right: El usuario ve el tema claro desactivar Render ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Utilisateur participant Navigateur participant "Analizador HTML" as Parser participant "CSSOM" as CSS participant "Script.js (fin del cuerpo)" as Script participant "Motor de renderizado" as Render Utilisateur -> Navigateur: Demande la page activate Navigateur Navigateur -> Parser: Parse le HTML activate Parser Parser -> CSS: Découvre et charge les CSS activate CSS Parser -> Parser: Construit le DOM Parser -> Navigateur: DOM Ready (DOMContentLoaded) deactivate Parser CSS -> CSS: Parse les feuilles de style CSS -> Render: CSSOM Ready deactivate CSS activate Render Render -> Render: Calcule les styles avec data-bs-theme=""note right: Tema por defecto (light) Render -> Navegador: Primer Pintura (Tema Claro) note right: El usuario ve el tema claro desactivar Render Navegador -> Script: Ejecuta el script activar Script Script -> Script: Lee localStorage Script -> Navegador: setAttribute('data-bs-theme', 'dark') desactivar Script activar Render Render -> Render: Recalcula los estilos con data-bs-theme="dark" note right: Thème sombre Render -> Navigateur: Repaint (Thème Sombre) note right: Clignotement visible deactivate Render deactivate Navigateur @enduml</pre> </div> </div> <div class="paragraph"> <p>Este diagrama ilustra claramente el problema: el primer paint ocurre antes de que nuestro script haya tenido la oportunidad de establecer el tema correcto. El repaint subsiguiente crea el parpadeo visible.</p> </div> </div> <div class="sect2"> <h3 id="_los_intentos_de_solución_ineficaces">Los intentos de solución ineficaces</h3> <div class="paragraph"> <p>Se han intentado varios enfoques para resolver este problema, pero la mayoría tiene sus propios inconvenientes:</p> </div> <div class="paragraph"> <p><strong>Enfoque 1: Ocultar el contenido hasta que se cargue</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">body { opacity: 0; transition: opacity 0.3s; } body.loaded { opacity: 1; }</code></pre> </div> </div> <div class="paragraph"> <p>Este enfoque oculta todo el contenido hasta que JavaScript haya definido el tema correcto. ¿El problema? Esto retrasa artificialmente la visualización del contenido, dando la impresión de un sitio más lento. Además, si JavaScript está desactivado, el usuario no ve nada en absoluto!</p> </div> <div class="paragraph"> <p><strong>Enfoque 2 : Utilizar un loader/spinner</strong></p> </div> <div class="paragraph"> <p>Similar al enfoque 1, pero con un spinner de carga. Esto oculta el problema pero no mejora el rendimiento real y agrega un retraso percibido innecesario.</p> </div> <div class="paragraph"> <p><strong>Enfoque 3: Predeterminado al tema oscuro</strong></p> </div> <div class="paragraph"> <p>Algunos desarrolladores definen el tema oscuro como predeterminado en el CSS. Esto evita el parpadeo para los usuarios del tema oscuro, pero crea el problema inverso para los usuarios del tema claro!</p> </div> <div class="paragraph"> <p>Ninguno de estos enfoques es satisfactorio porque tratan el síntoma en lugar de la causa raíz del problema.</p> </div> </div> <div class="sect2"> <h3 id="_la_verdadera_solución_actuar_más_temprano">La Verdadera Solución : Actuar Más Temprano</h3> <div class="paragraph"> <p>La clave para resolver este problema es darnos cuenta de que debemos definir el atributo`data-bs-theme` <strong>antes</strong>que el navegador no comience a aplicar los estilos CSS. Esto significa que nuestro script debe ejecutarse antes en el ciclo de vida de la página, y esto es exactamente lo que vamos a explorar en la siguiente sección.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_la_carga_temprana_early_loading">La solución : La carga temprana (Early Loading)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_fundamental">Principio Fundamental</h3> <div class="paragraph"> <p>La solución elegante a nuestro problema de parpadeo se basa en un principio simple pero poderoso:<strong>sincronizar el estado de la aplicación con el proceso de renderizado del navegador</strong>. En lugar de esperar a que la página se cargue para definir el tema, debemos definirlo<strong>mientras</strong>la carga, antes incluso de que se apliquen los estilos CSS.</p> </div> <div class="paragraph"> <p>Esta aproximación se llama "Early Loading" o "Synchronous Preloading" en el jerga del desarrollo web. La idea es ejecutar nuestra lógica de detección de tema lo más pronto posible en el ciclo de vida de la página, idealmente dentro de la etiqueta`<head>`, incluso antes de que el navegador comience a descargar los archivos CSS.</p> </div> </div> <div class="sect2"> <h3 id="_por_qué_el_head_es_el_lugar_ideal">¿Por qué el <code><head></code> es el Lugar Ideal</h3> <div class="paragraph"> <p>Le `<head>`Un documento HTML se procesa secuencialmente por el navegador, de arriba hacia abajo. Cada elemento se procesa en el orden en que aparece. Esta característica es crucial para nuestra solución.</p> </div> <div class="paragraph"> <p>Cuando el navegador encuentra una etiqueta`<script>`en el`<head>`sin los atributos`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Interrumpe el análisis del HTML</strong></p> </li> <li> <p><strong>Descarga el script</strong>(si externo) o la cama (si en línea)</p> </li> <li> <p><strong>Ejecuta inmediatamente el script</strong></p> </li> <li> <p><strong>Continúa el parsing del HTML</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Este comportamiento, a menudo considerado un problema de rendimiento (de ahí la recomendación habitual de colocar los scripts al final de la página), se convierte en nuestro aliado en este caso específico. Al colocar nuestro script de detección de tema al principio del`<head>`, nous garantissons qu’il s’exécute avant que le navigateur ne rencontre les balises`<link>`de nuestras hojas de estilo</p> </div> </div> <div class="sect2"> <h3 id="_arquitectura_de_la_solución_en_tres_capas">Arquitectura de la solución en tres capas</h3> <div class="paragraph"> <p>Nuestra solución completa consta de tres capas interdependientes, cada una desempeñando un papel específico :</p> </div> <div class="paragraph"> <p><strong>Capa 1 : Persistencia (localStorage)</strong> Esta capa es responsable de guardar y recuperar la elección del usuario entre sesiones.</p> </div> <div class="paragraph"> <p><strong>Capa 2 : Sincronización temprana (Script inline en <code><head></code>)</strong> Esta capa sincroniza el estado de la aplicación con el DOM antes del renderizado inicial.</p> </div> <div class="paragraph"> <p><strong>Capa 3: Estilos reactivos (CSS con selectores de atributos)</strong> Esta capa define los estilos visuales basados en el estado definido por la capa 2.</p> </div> <div class="paragraph"> <p>Exploremos ahora cada capa en detalle.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_1_guardar_la_selección_del_usuario">Paso 1: Guardar la Selección del Usuario</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_localstorage_tu_memoria_persistente">El localStorage : Tu Memoria Persistente</h3> <div class="paragraph"> <p>Le <code>localStorage`es una API de Web Storage que permite almacenar pares clave-valor en el navegador de forma persistente. A diferencia de las cookies, los datos del`localStorage</code>:</p> </div> <div class="ulist"> <ul> <li> <p>Nunca se envían automáticamente al servidor</p> </li> <li> <p>Tienen una capacidad de almacenamiento mayor (generalmente 5-10MB)</p> </li> <li> <p>No tienen fecha de expiración (persistente hasta su eliminación explícita)</p> </li> <li> <p>Están limitadas al protocolo y al dominio (Same-Origin Policy)</p> </li> </ul> </div> <div class="paragraph"> <p>Para nuestro caso de uso, el`localStorage`es perfecto porque :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>No necesitamos compartir esta información con el servidor</p> </li> <li> <p>Queremos que la preferencia persista indefinidamente</p> </li> <li> <p>El tamaño de almacenamiento requerido es mínimo (unos pocos bytes)</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_implementación_de_la_copia_de_seguridad_del_tema">Implementación de la copia de seguridad del tema</h3> <div class="paragraph"> <p>Así es como guardamos la elección del usuario cuando cambia de tema :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// Fonction complète pour changer le thème function setTheme(newTheme) { // Validation de l'entrée if (!['light', 'dark', 'auto'].includes(newTheme)) { console.error('Thème invalide:', newTheme); return; } try { // Sauvegarde dans localStorage localStorage.setItem('preferred-theme', newTheme); // Application immédiate dans le DOM document.documentElement.setAttribute('data-bs-theme', newTheme); // Dispatch d'un événement personnalisé pour notifier d'autres composants window.dispatchEvent(new CustomEvent('theme-changed', { detail: { theme: newTheme } })); console.log('Thème changé:', newTheme); } catch (error) { console.error('Erreur lors de la sauvegarde du thème:', error); // Fallback : on applique quand même le thème visuellement document.documentElement.setAttribute('data-bs-theme', newTheme); } } // Exemple d'utilisation avec un bouton document.getElementById('theme-toggle').addEventListener('click', () => { const currentTheme = document.documentElement.getAttribute('data-bs-theme') || 'light'; const newTheme = currentTheme === 'light' ? 'dark' : 'light'; setTheme(newTheme); });</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_gestión_de_casos_de_error">Gestión de Casos de Error</h3> <div class="paragraph"> <p>Es crucial gestionar los casos donde le`localStorage`no está disponible o accesible. Varios escenarios pueden impedir el acceso al`localStorage`:</p> </div> <div class="paragraph"> <p><strong>Navegación privada estricta</strong>Safari en modo de navegación privada lanza una excepción`QuotaExceededError`al intentar escribir en el`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Ajustes de privacidad</strong>: Algunos navegadores o extensiones de privacidad pueden bloquear el acceso al`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Limitaciones de dominio</strong> : Le `localStorage`no es accesible en el protocolo`file://`en algunos navegadores.</p> </div> <div class="paragraph"> <p><strong>Espacio de almacenamiento saturado</strong>Aunque raro, el espacio de almacenamiento puede estar completamente lleno.</p> </div> <div class="paragraph"> <p>Es por eso que nuestro código utiliza un bloque`try…​catch`para gestionar estos casos con elegancia, continuando de ofrecer la funcionalidad de cambio de tema incluso si la persistencia no está disponible.</p> </div> </div> <div class="sect2"> <h3 id="_estrategias_avanzadas_de_persistencia">Estrategias Avanzadas de Persistencia</h3> <div class="paragraph"> <p>Para aplicaciones más sofisticadas, puede considerar estrategias adicionales:</p> </div> <div class="paragraph"> <p><strong>Sincronización servidor (opcional)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">async function setTheme(newTheme) { // Sauvegarde locale immédiate localStorage.setItem('preferred-theme', newTheme); document.documentElement.setAttribute('data-bs-theme', newTheme); // Synchronisation serveur en arrière-plan (si l'utilisateur est connecté) if (userIsAuthenticated()) { try { await fetch('/api/user/preferences', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ theme: newTheme }) }); } catch (error) { console.warn('Échec de la synchronisation serveur:', error); // L'échec n'est pas critique car la préférence est déjà sauvegardée localement } } }</code></pre> </div> </div> <div class="paragraph"> <p>Este enfoque permite sincronizar las preferencias entre dispositivos para los usuarios conectados, manteniendo al mismo tiempo una capacidad de respuesta local inmediata.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_2_el_script_de_precarga_dentro_del_head">Paso 2: El script de pre‑carga dentro del `<head></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_corazón_de_la_solución">El Corazón de la Solución</h3> <div class="paragraph"> <p>Es aquí donde la magia opera realmente. Vamos a colocar un pequeño script.<strong>en línea</strong>directamente en nuestro`<head>`, antes de todas nuestras etiquetas`<link>`de hojas de estilo. Este script es voluntariamente minimalista, autónomo y diseñado para ejecutarse lo más rápido posible.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Mon Site Incroyable</title> <!-- ========================================== NOTRE SCRIPT MAGIQUE DE PRÉ-CHARGEMENT Ce script DOIT être le premier élément dans le <head> après les meta tags ========================================== --> <script> // IIFE pour ne pas polluer le scope global (function() { 'use strict'; try { // Lecture de la préférence sauvegardée const savedTheme = localStorage.getItem('preferred-theme'); // Si une préférence existe, on l'applique immédiatement if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); } // Optionnel : Détecter la préférence système si aucune sauvegarde else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } // Sinon, le thème par défaut du CSS sera utilisé (généralement 'light') } catch (error) { // En cas d'erreur (localStorage bloqué, etc.), on log discrètement // et on laisse le thème par défaut s'appliquer console.warn('Impossible de charger la préférence de thème:', error); } })(); </script> <!-- FIN DU SCRIPT MAGIQUE --> <!-- Les feuilles de style sont chargées APRÈS le script --> <link rel="stylesheet" href="css/bootstrap.min.css"> <link rel="stylesheet" href="css/styles.css"> <!-- Autres ressources du head --> <link rel="icon" href="favicon.ico"> </head> <body> <!-- Contenu de la page --> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_anatomía_del_script_cada_línea_cuenta">Anatomía del Script: Cada Línea Cuenta</h3> <div class="paragraph"> <p>Desglosemos este script línea por línea para comprender cada decisión de diseño:</p> </div> <div class="paragraph"> <p><strong>La IIFE (Expresión de Función Inmediatamente Invocada)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">(function() { // ... })();</code></pre> </div> </div> <div class="paragraph"> <p>Esta estructura crea una función que se ejecuta inmediatamente. ¿Por qué? Para aislar nuestras variables en un ámbito local y evitar de contaminar el ámbito global. Aunque solo utilicemos`const`(que tiene un ámbito de bloque), la IIFE es una buena práctica que deja nuestras intenciones claras y protege contra posibles conflictos de nombres.</p> </div> <div class="paragraph"> <p><strong>El Modo Estricto</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">'use strict';</code></pre> </div> </div> <div class="paragraph"> <p>Esta directiva activa el modo estricto de JavaScript, que: - Prohíbe el uso de variables no declaradas - Genera errores para las operaciones peligrosas - Mejora el rendimiento en algunos motores de JavaScript</p> </div> <div class="paragraph"> <p>Para un script crítico como este, queremos la máxima seguridad.</p> </div> <div class="paragraph"> <p><strong>El bloque try…​catch</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">try { // Code principal } catch (error) { console.warn('Impossible de charger la préférence de thème:', error); }</code></pre> </div> </div> <div class="paragraph"> <p>Este bloque es absolutamente crucial. Garantiza que si algo sale mal (localStorage bloqueado, error de sintaxis improbable, etc.), nuestro script no bloqueará la carga de toda la página. El uso de`console.warn`más que`console.error`indica que es un problema no crítico.</p> </div> <div class="paragraph"> <p><strong>La Lectura del localStorage</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">const savedTheme = localStorage.getItem('preferred-theme');</code></pre> </div> </div> <div class="paragraph"> <p>Esta línea puede lanzar una excepción en ciertos contextos (navegación privada estricta de Safari). Por eso está dentro de un bloque try…​catch.</p> </div> <div class="paragraph"> <p><strong>La Aplicación Condicional</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); }</code></pre> </div> </div> <div class="paragraph"> <p>Aplicamos el tema solo si hemos encontrado uno guardado. En caso contrario, dejamos que el CSS use su tema predeterminado. Este enfoque es más robusto que un valor predeterminado codificado de forma fija en JavaScript.</p> </div> </div> <div class="sect2"> <h3 id="_detección_de_la_preferencia_del_sistema_bonus">Detección de la Preferencia del Sistema (Bonus)</h3> <div class="paragraph"> <p>Una mejora opcional pero elegante consiste en detectar la preferencia de tema del sistema operativo del usuario si aún no ha hecho una elección explícita en tu aplicación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); }</code></pre> </div> </div> <div class="paragraph"> <p>Esta funcionalidad utiliza la Media Query`prefers-color-scheme`para consultar el sistema. En macOS, Windows 10+, iOS y Android moderno, esta consulta devuelve la preferencia del sistema del usuario.</p> </div> <div class="paragraph"> <p><strong>Ventajas :</strong> - Experiencia personalizada desde la primera visita Coherencia con el entorno del sistema del usuario - No se requiere almacenamiento para la primera visita</p> </div> <div class="paragraph"> <p><strong>Consideraciones :</strong> - No todos los navegadores admiten esta funcionalidad (pero el soporte es excelente desde 2020) - La verificación`window.matchMedia`garantiza la compatibilidad - El usuario siempre puede sobrescribir esta opción</p> </div> </div> <div class="sect2"> <h3 id="_rendimiento_por_qué_este_script_es_rápido">Rendimiento: ¿Por qué este script es rápido?</h3> <div class="paragraph"> <p>Nuestro script de pre-carga está diseñado para ser extremadamente rápido:</p> </div> <div class="paragraph"> <p><strong>Tamaño mínimo</strong>: Aproximadamente 300 bytes sin minificar, 200 bytes minificados. Es insignificante comparado con cualquier imagen o biblioteca JavaScript.</p> </div> <div class="paragraph"> <p><strong>Inline</strong>: No hay solicitud HTTP adicional. El script está en el HTML, por lo que está inmediatamente disponible.</p> </div> <div class="paragraph"> <p><strong>Operaciones síncronas simples</strong>: Lectura de una clave en el localStorage (operación ultra rápida) y modificación de un atributo DOM (operación nativa del navegador).</p> </div> <div class="paragraph"> <p><strong>Ninguna dependencia</strong>: Sin framework, sin librería, solo JavaScript vanilla. Sin tiempo de arranque, sin análisis de dependencias.</p> </div> <div class="paragraph"> <p><strong>Ejecución única</strong>: Este script se ejecuta una sola vez al cargar. No hay listeners de eventos, no hay bucles, no hay cálculos complejos.</p> </div> <div class="paragraph"> <p>En la práctica, en hardware moderno, este script se ejecuta en menos de 1 milisegundo, un tiempo imperceptible que no tiene ningún impacto en el rendimiento de carga de la página.</p> </div> </div> <div class="sect2"> <h3 id="_colocación_óptima_en_el_head">Colocación Óptima en el `<head></h3> <div class="paragraph"> <p>El orden de los elementos en el`<head>`es importante. Aquí está el orden recomendado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><head> <!-- 1. Métadonnées critiques --> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <!-- 2. Notre script de pré-chargement (IMMÉDIATEMENT après les meta) --> <script> (function() { /* notre code */ })(); </script> <!-- 3. Titre de la page --> <title>Mon Site</title> <!-- 4. Feuilles de style --> <link rel="stylesheet" href="styles.css"> <!-- 5. Autres ressources (fonts, favicons, etc.) --> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="icon" href="favicon.ico"> <!-- 6. Autres scripts avec defer ou async --> <script src="app.js" defer></script> </head></code></pre> </div> </div> <div class="paragraph"> <p>Esta orden garantiza que:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>El charset se define antes de cualquier procesamiento de texto</p> </li> <li> <p>Nuestro script se ejecuta antes de cargar los CSS</p> </li> <li> <p>Los CSS se cargan después y aplican directamente el tema correcto</p> </li> <li> <p>Los otros recursos no críticos se cargan al final</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_3_el_poder_de_los_selectores_de_atributos_css">Paso 3: El poder de los selectores de atributos CSS</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_sistema_de_tema_de_bootstrap_5">El Sistema de Tema de Bootstrap 5</h3> <div class="paragraph"> <p>Bootstrap 5 introdujo un sistema elegante de gestión de temas basado en las propiedades personalizadas CSS (variables CSS) y los selectores de atributos. Este sistema utiliza el atributo`data-bs-theme`sobre el elemento`<html>`para determinar qué conjunto de variables de color aplicar.</p> </div> <div class="paragraph"> <p>La belleza de este sistema reside en su simplicidad: en lugar de cargar diferentes hojas de estilo o de alternar clases en miles de elementos, simplemente cambiamos un atributo en un solo elemento, y el CSS se encarga del resto gracias a la cascada.</p> </div> </div> <div class="sect2"> <h3 id="_estructura_css_para_un_sistema_de_tema">Estructura CSS para un Sistema de Tema</h3> <div class="paragraph"> <p>Aquí tiene una estructura CSS completa para implementar un sistema de tema robusto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/** * SYSTÈME DE THÈME COMPLET * Utilise les Custom Properties CSS pour une maintenance facile */ /* ============================================ THÈME PAR DÉFAUT (LIGHT) Défini sur :root pour être le fallback ============================================ */ :root { /* Couleurs de base */ --color-primary: #0d6efd; --color-secondary: #6c757d; --color-success: #198754; --color-danger: #dc3545; --color-warning: #ffc107; --color-info: #0dcaf0; /* Couleurs de fond */ --bg-primary: #ffffff; --bg-secondary: #f8f9fa; --bg-tertiary: #e9ecef; /* Couleurs de texte */ --text-primary: #212529; --text-secondary: #6c757d; --text-tertiary: #adb5bd; /* Couleurs de bordure */ --border-color: #dee2e6; --border-color-subtle: #e9ecef; /* Couleurs d'ombre */ --shadow-sm: rgba(0, 0, 0, 0.075); --shadow-md: rgba(0, 0, 0, 0.15); --shadow-lg: rgba(0, 0, 0, 0.25</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html Fri, 7 Nov 2025 00:00:00 +0000 blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_el_problema_dependencia_al_gradlerunner">El Problema : Dependencia al GradleRunner</a> <ul class="sectlevel2"> <li><a href="#_contexto_del_desarrollo_de_plugin">Contexto del desarrollo de plugin</a></li> <li><a href="#_el_dilema_del_registro">El dilema del registro</a></li> <li><a href="#_las_falsas_buenas_ideas">Las Falsas Buenas Ideas</a></li> </ul> </li> <li><a href="#_la_solución_logger_independiente">La Solución : Logger Independiente</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_recomendada">Arquitectura Recomendada</a></li> <li><a href="#_flujo_de_ejecución">Flujo de ejecución</a></li> </ul> </li> <li><a href="#_implementación_completa">Implementación Completa</a> <ul class="sectlevel2"> <li><a href="#_dependencias_de_gradle">Dependencias de Gradle</a></li> <li><a href="#_configuración_logback">Configuración Logback</a></li> <li><a href="#_clase_de_prueba_completa">Clase de Prueba Completa</a></li> </ul> </li> <li><a href="#_esquema_de_registro_multinivel">Esquema de registro multinivel</a></li> <li><a href="#_buenas_prácticas">Buenas Prácticas</a> <ul class="sectlevel2"> <li><a href="#_estructura_de_logging_recomendada">Estructura de Logging recomendada</a></li> <li><a href="#_símbolos_visuales_para_la_legibilidad">Símbolos Visuales para la Legibilidad</a></li> <li><a href="#_extracción_de_información_de_la_salida">Extracción de Información de la Salida</a></li> </ul> </li> <li><a href="#_comparación_antesdespués">Comparación Antes/Después</a> <ul class="sectlevel2"> <li><a href="#_antes_enfoque_problemático">Antes : Enfoque problemático</a></li> <li><a href="#_después_enfoque_robusto">Después: Enfoque Robusto</a></li> </ul> </li> <li><a href="#_diagrama_resumen">Diagrama Resumen</a></li> <li><a href="#_trampas_a_evitar">Trampas a Evitar</a> <ul class="sectlevel2"> <li><a href="#_trampa_nº1_olvidar_forwardoutput">❌ Trampa nº1: Olvidar `.forwardOutput()</a></li> <li><a href="#_trampa_n2_logger_no_inicializado">❌ Trampa n°2 : Logger No Inicializado</a></li> <li><a href="#_trampa_n3_registro_excesivo">❌ Trampa n°3 : Registro excesivo</a></li> </ul> </li> <li><a href="#_resultados_y_métricas">Resultados y Métricas</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_recursos">Recursos</a></li> <li><a href="#_ir_más_lejos">Ir Más Lejos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante el desarrollo de un plugin Gradle, las pruebas funcionales son esenciales para validar el comportamiento del plugin en un entorno Gradle real. Sin embargo, surge rápidamente una pregunta crucial:<strong>¿cómo implementar un sistema de registro eficaz sin crear dependencias problemáticas con el <code>GradleRunner</code>?</strong></p> </div> <div class="paragraph"> <p>En este artículo, vamos a explorar:</p> </div> <div class="ulist"> <ul> <li> <p>La problemática del logging en las pruebas funcionales de Gradle</p> </li> <li> <p>La arquitectura de una solución robusta con SLF4J y Logback</p> </li> <li> <p>La implementación completa con ejemplos concretos</p> </li> <li> <p>Las buenas prácticas y trampas a evitar</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_dependencia_al_gradlerunner">El Problema : Dependencia al GradleRunner</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto_del_desarrollo_de_plugin">Contexto del desarrollo de plugin</h3> <div class="paragraph"> <p>Cuando se desarrolla un plugin Gradle, se suele utilizar el`GradleRunner`del <em>Gradle TestKit</em> para ejecutar compilaciones de prueba :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `test my plugin`() { val result = GradleRunner.create() .withProjectDir(projectDir) .withArguments("myTask") .build() // Comment logger efficacement ici ? }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_el_dilema_del_registro">El dilema del registro</h3> <div class="paragraph"> <p>El problema principal es el siguiente:<strong>el registro no debe depender de un objeto del que no estemos seguros de su inicialización</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-0f9ffc510974b04a7a390d9afffbc11a.png" alt="Diagram" width="451" height="262"> </div> </div> </div> <div class="sect2"> <h3 id="_las_falsas_buenas_ideas">Las Falsas Buenas Ideas</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>No hagas esto:</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ MAUVAIS: Tentative d'obtenir un logger du runner val runner = GradleRunner.create() val logger = runner.logger // N'existe pas ! // ❌ MAUVAIS: Logger partagé initialisé tardivement lateinit var logger: Logger @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) }</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_logger_independiente">La Solución : Logger Independiente</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitectura_recomendada">Arquitectura Recomendada</h3> <div class="paragraph"> <p>La solución consiste en utilizar un logger<strong>totalmente independiente</strong> du <code>GradleRunner</code>, inicializado a nivel de la clase de prueba.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-5f4dffc349e354b824ea2a88a17be05b.png" alt="Diagram" width="601" height="448"> </div> </div> </div> <div class="sect2"> <h3 id="_flujo_de_ejecución">Flujo de ejecución</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-69aa85b92387cf39f4470e736c481067.png" alt="Diagram" width="800" height="686"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implementación_completa">Implementación Completa</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dependencias_de_gradle">Dependencias de Gradle</h3> <div class="paragraph"> <p>Añade las dependencias necesarias en su`build.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Pour les tests fonctionnels testImplementation(gradleTestKit()) testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") // Pour le logging testImplementation("org.slf4j:slf4j-api:2.0.17") testRuntimeOnly("ch.qos.logback:logback-classic:1.4.14") // Pour les assertions testImplementation("org.assertj:assertj-core:3.27.6") } tasks.test { useJUnitPlatform() }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_configuración_logback">Configuración Logback</h3> <div class="paragraph"> <p>Cree el archivo`src/test/resources/logback-test.xml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- Appender console avec format lisible --> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <!-- Appender fichier pour conservation --> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>build/test-results/functional-tests.log</file> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern> </encoder> </appender> <!-- Logger pour vos tests --> <logger name="com.cheroliv.bakery" level="DEBUG"/> <!-- Réduire le bruit de Gradle --> <logger name="org.gradle" level="WARN"/> <!-- Configuration racine --> <root level="INFO"> <appender-ref ref="STDOUT"/> <appender-ref ref="FILE"/> </root> </configuration></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_clase_de_prueba_completa">Clase de Prueba Completa</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package com.cheroliv.bakery import org.gradle.testkit.runner.GradleRunner import org.gradle.testkit.runner.TaskOutcome import org.junit.jupiter.api.* import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS import org.junit.jupiter.api.io.TempDir import org.slf4j.Logger import org.slf4j.LoggerFactory import java.io.File import kotlin.test.assertEquals import kotlin.test.assertTrue @TestInstance(PER_CLASS) class BakeryPluginFunctionalTest { @field:TempDir lateinit var projectDir: File private val buildFile by lazy { projectDir.resolve("build.gradle.kts") } private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") } companion object { // ✓ Logger indépendant, initialisé au chargement de la classe private val logger: Logger = LoggerFactory.getLogger( BakeryPluginFunctionalTest::class.java ) @JvmStatic @BeforeAll fun globalSetup() { logger.info("═".repeat(60)) logger.info("DÉMARRAGE DE LA SUITE DE TESTS FONCTIONNELS") logger.info("═".repeat(60)) } @JvmStatic @AfterAll fun globalTeardown() { logger.info("═".repeat(60)) logger.info("FIN DE LA SUITE DE TESTS") logger.info("═".repeat(60)) } } @BeforeEach fun setup() { logger.info("─".repeat(60)) logger.info("Préparation de l'environnement de test") logger.debug("Répertoire de test: ${projectDir.absolutePath}") settingsFile.writeText(""" rootProject.name = "test-bakery-project" """.trimIndent()) logger.debug("✓ settings.gradle.kts créé") } @AfterEach fun teardown(testInfo: TestInfo) { logger.info("✓ Test terminé: ${testInfo.displayName}") logger.info("─".repeat(60)) } @Test fun `plugin can be applied successfully`() { logger.info("TEST: Application du plugin Bakery") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Fichier build.gradle.kts créé") logger.debug("Lancement du build Gradle...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() // ← Important : capture la sortie .withPluginClasspath() .withArguments("tasks", "--group=bakery", "--stacktrace") .withProjectDir(projectDir) .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // Analyse de la sortie logger.debug("Analyse de la sortie Gradle...") val outputLines = result.output.lines() logger.debug("Nombre de lignes capturées: ${outputLines.size}") // Validation val expectedTasks = listOf("bake", "printConfigPath", "printJBakeClasspath") logger.info("Vérification des tâches attendues:") expectedTasks.forEach { task -> val found = result.output.contains(task) logger.debug(" ${if (found) "✓" else "✗"} $task") assertTrue(found, "Task '$task' should be available") } logger.info("✓ Plugin appliqué avec succès - ${expectedTasks.size} tâches trouvées") } @Test fun `bake task executes and prints version`() { logger.info("TEST: Exécution de la tâche 'bake'") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Exécution de 'gradle bake'...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("bake", "--info") // --info pour plus de détails .withProjectDir(projectDir) .build() // Extraction d'informations depuis la sortie logger.debug("Recherche du message 'Baking site'...") val hasBakingMessage = result.output.contains("Baking site with Bakery Plugin!") logger.debug("Recherche de la version JBake...") val hasVersionMessage = result.output.contains("Using JBake version:") // Extraction de la version (si présente) val versionRegex = Regex("Using JBake version: (.+)") val versionMatch = versionRegex.find(result.output) if (versionMatch != null) { val version = versionMatch.groupValues[1] logger.info("Version JBake détectée: $version") } // Validation assertTrue(hasBakingMessage, "Message 'Baking site' attendu") assertTrue(hasVersionMessage, "Message de version attendu") assertEquals(TaskOutcome.SUCCESS, result.task(":bake")?.outcome) logger.info("✓ Tâche 'bake' exécutée avec succès") } @Test fun `analyze output with structured logging`() { logger.info("TEST: Analyse structurée de la sortie") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } task("diagnostics") { doLast { println("[DIAG] Project: ${'$'}{project.name}") println("[DIAG] Build dir: ${'$'}{project.buildDir}") println("[DIAG] Plugin applied: true") val config = configurations.findByName("jbakeRuntime") println("[DIAG] JBake config exists: ${'$'}{config != null}") if (config != null) { println("[DIAG] Dependencies count: ${'$'}{config.dependencies.size}") } } } """.trimIndent()) logger.debug("Exécution de la tâche diagnostics...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("diagnostics", "--quiet") .withProjectDir(projectDir) .build() // Analyse structurée logger.info("Extraction des informations de diagnostic:") val diagLines = result.output.lines() .filter { it.startsWith("[DIAG]") } logger.debug("Nombre de lignes de diagnostic: ${diagLines.size}") diagLines.forEach { line -> logger.info(" $line") // Analyse spécifique par type de ligne when { line.contains("Project:") -> { val projectName = line.substringAfter("Project:").trim() logger.debug(" → Nom du projet extrait: '$projectName'") } line.contains("Dependencies count:") -> { val count = line.substringAfter("count:").trim() logger.debug(" → Nombre de dépendances: $count") } } } assertTrue(diagLines.isNotEmpty(), "Des lignes de diagnostic devraient être présentes") logger.info("✓ Analyse structurée terminée - ${diagLines.size} lignes analysées") } @Test fun `test with error handling`() { logger.info("TEST: Gestion d'erreurs avec logging") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) try { logger.debug("Tentative d'exécution...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("printJBakeClasspath") .withProjectDir(projectDir) .build() val outcome = result.task(":printJBakeClasspath")?.outcome logger.info("Outcome: $outcome") if (outcome == TaskOutcome.SUCCESS) { logger.info("✓ Exécution réussie") } else { logger.warn("⚠ Outcome inattendu: $outcome") } assertEquals(TaskOutcome.SUCCESS, outcome) } catch (e: Exception) { logger.error("✗ Échec du test", e) logger.error("Type d'exception: ${e.javaClass.simpleName}") logger.error("Message: ${e.message}") // Log de la stack trace si nécessaire if (logger.isDebugEnabled) { logger.debug("Stack trace complète:", e) } throw e } } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esquema_de_registro_multinivel">Esquema de registro multinivel</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-bd34c3efbe3aca41d45c3c1729b4b518.png" alt="Diagram" width="314" height="911"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas">Buenas Prácticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estructura_de_logging_recomendada">Estructura de Logging recomendada</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `mon test`() { // 1. LOG: Début du test logger.info("TEST: Description du test") // 2. LOG: Préparation logger.debug("Préparation des fichiers...") buildFile.writeText("...") logger.debug("✓ Fichiers préparés") // 3. LOG: Exécution logger.debug("Lancement du build...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() .withArguments("task") .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // 4. LOG: Analyse logger.debug("Analyse des résultats...") // ... validations ... // 5. LOG: Conclusion logger.info("✓ Test réussi") }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_símbolos_visuales_para_la_legibilidad">Símbolos Visuales para la Legibilidad</h3> <div class="paragraph"> <p>Utilice símbolos Unicode para mejorar la legibilidad de los registros:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">logger.info("✓ Succès") logger.info("✗ Échec") logger.info("⚠ Attention") logger.info("→ Étape suivante") logger.info("═".repeat(60)) // Séparateur principal logger.info("─".repeat(60)) // Séparateur secondaire</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_extracción_de_información_de_la_salida">Extracción de Información de la Salida</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Recherche simple val hasMessage = result.output.contains("Expected message") // Extraction avec regex val versionRegex = Regex("Version: (.+)") val version = versionRegex.find(result.output)?.groupValues?.get(1) // Filtrage de lignes val errorLines = result.output.lines() .filter { it.contains("ERROR") } errorLines.forEach { logger.error("Gradle error: $it") }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparación_antesdespués">Comparación Antes/Después</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_antes_enfoque_problemático">Antes : Enfoque problemático</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { lateinit var logger: Logger // ❌ Initialisé tardivement @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) // ❌ Dépendance } @Test fun test() { val runner = GradleRunner.create() logger.info("Testing...") // ⚠ Peut échouer } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_después_enfoque_robusto">Después: Enfoque Robusto</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { companion object { private val logger = LoggerFactory.getLogger(...) // ✓ Indépendant } @Test fun test() { logger.info("TEST: Starting...") // ✓ Toujours disponible val result = GradleRunner.create() .forwardOutput() // ✓ Capture la sortie .build() logger.debug("Output: ${result.output}") // ✓ Analyse } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrama_resumen">Diagrama Resumen</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-317d0c9af1f6375fcc0408d48fce957b.png" alt="Diagram" width="1059" height="1345"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trampas_a_evitar">Trampas a Evitar</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_trampa_nº1_olvidar_forwardoutput">❌ Trampa nº1: Olvidar `.forwardOutput()</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: La sortie Gradle n'est pas capturée val result = GradleRunner.create() .withArguments("task") .build() // result.output sera vide !</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: La sortie est capturée val result = GradleRunner.create() .forwardOutput() // ✓ .withArguments("task") .build()</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_trampa_n2_logger_no_inicializado">❌ Trampa n°2 : Logger No Inicializado</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS class Test { lateinit var logger: Logger // Peut ne pas être initialisé }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON class Test { companion object { private val logger = LoggerFactory.getLogger(...) // Toujours initialisé } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_trampa_n3_registro_excesivo">❌ Trampa n°3 : Registro excesivo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: Trop de logs DEBUG en production logger.debug("Variable a = $a") logger.debug("Variable b = $b") logger.debug("Variable c = $c") // ... 100 lignes de logs</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: Logging ciblé logger.info("Traitement de ${items.size} éléments") logger.debug("Détails: ${items.take(5)}...") // Échantillon seulement</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_resultados_y_métricas">Resultados y Métricas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Con este enfoque, obtienes:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">métrico</th> <th class="tableblock halign-left valign-top">Antes</th> <th class="tableblock halign-left valign-top">Después</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Líneas de código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50 líneas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~80 líneas (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tiempo de depuración</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~30 minutos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5 min (-83%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Errores detectados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Básico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detallado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Mantenimiento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Difícil</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">simple</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Independencia</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌ Acoplada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✓ Independiente</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>La puesta en marcha de un sistema de registro robusto en las pruebas funcionales de los plugins de Gradle se basa en un principio simple :<strong>la independencia</strong>.</p> </div> <div class="paragraph"> <p>Puntos clave a tener en cuenta:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Logger independiente</strong>: Iniciado en un`companion object`</p> </li> <li> <p><strong>SLF4J + Logback</strong>: Stack probada y configurable</p> </li> <li> <p><strong>.forwardOutput()</strong>: Captura de la salida de Gradle</p> </li> <li> <p><strong>Logging estructurado</strong>: INFO para los pasos, DEBUG para los detalles</p> </li> <li> <p><strong>Análisis de salida</strong>: Extracción de información desde`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>Este enfoque garantiza pruebas<strong>mantenibles</strong>, <strong>depurables</strong> et <strong>robustos</strong>, manteniendo los principios de diseño sólidos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_recursos">Recursos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/test_kit.html">Gradle TestKit Documentation</a></p> </li> <li> <p><a href="https://www.slf4j.org/manual.html">Manual SLF4J</a></p> </li> <li> <p><a href="https://logback.qos.ch/manual/configuration.html">Logback Configuración</a></p> </li> <li> <p><a href="https://github.com/gradle/gradle/tree/master/subprojects/test-kit">Gradle TestKit código fuente</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_ir_más_lejos">Ir Más Lejos</h2> <div class="sectionbody"> <div class="paragraph"> <p>En un próximo artículo, exploraremos :</p> </div> <div class="ulist"> <ul> <li> <p>Integración continua con registro estructurado</p> </li> <li> <p>Los informes HTML de pruebas con registros integrados</p> </li> <li> <p>Depuración avanzada con JVM attach</p> </li> <li> <p>El rendimiento y las optimizaciones de registro</p> </li> </ul> </div> <div class="paragraph"> <p><em>Este artículo forma parte de la serie "Desarrollo de complementos Gradle" en mi blog técnico.</em></p> </div> </div> </div> https://cheroliv.com//blog/2025/0096_afficher-couleurs-asciidoc_post.html Sat, 1 Nov 2025 00:00:00 +0000 blog/2025/0096_afficher-couleurs-asciidoc_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_la_problemática">La problemática</a> <ul class="sectlevel2"> <li><a href="#_contexto_de_uso">Contexto de uso</a></li> <li><a href="#_los_enfoques_posibles">Los enfoques posibles</a> <ul class="sectlevel3"> <li><a href="#_opción_1_caracteres_unicode">Opción 1 : Caracteres Unicode</a></li> <li><a href="#_opción_2_imágenes_externas">Opción 2: Imágenes externas</a></li> <li><a href="#_opción_3_roles_css_personalizados">Opción 3: Roles CSS personalizados</a></li> <li><a href="#_opción_4_inyección_html_solución_adoptada">Opción 4: Inyección HTML (solución adoptada)</a></li> </ul> </li> </ul> </li> <li><a href="#_la_solución_inyección_html_con">La solución : Inyección HTML con </a> <ul class="sectlevel2"> <li><a href="#_principio_de_funcionamiento">Principio de funcionamiento</a></li> <li><a href="#_implementación">Implementación</a> <ul class="sectlevel3"> <li><a href="#_explicación_de_las_propiedades_css">Explicación de las propiedades CSS</a></li> </ul> </li> <li><a href="#_ejemplo_completo">Ejemplo completo</a></li> </ul> </li> <li><a href="#_optimizaciones_y_buenas_prácticas">Optimizaciones y buenas prácticas</a> <ul class="sectlevel2"> <li><a href="#_administrar_los_colores_claros">Administrar los colores claros</a></li> <li><a href="#_adaptar_el_tamaño_de_los_cuadrados">Adaptar el tamaño de los cuadrados</a></li> <li><a href="#_crear_variantes">Crear variantes</a> <ul class="sectlevel3"> <li><a href="#_círculo_coloreado">Círculo coloreado</a></li> <li><a href="#_cuadrado_con_borde_coloreado">Cuadrado con borde coloreado</a></li> </ul> </li> </ul> </li> <li><a href="#_arquitectura_de_la_solución">Arquitectura de la solución</a></li> <li><a href="#_ventajas_y_limitaciones">Ventajas y limitaciones</a> <ul class="sectlevel2"> <li><a href="#_ventajas">Ventajas</a></li> <li><a href="#_limitaciones">Limitaciones</a></li> <li><a href="#_mejora_de_la_accesibilidad">Mejora de la accesibilidad</a></li> </ul> </li> <li><a href="#_ejemplo_concreto_documentación_de_temas">Ejemplo concreto : Documentación de temas</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante la redacción de documentación técnica, especialmente para guías de estilo o especificaciones de interfaz de usuario, es frecuente tener que mostrar paletas de colores. AsciiDoc, aunque muy potente para la documentación, no ofrece una sintaxis nativa para mostrar muestras de color. Este artículo explora el problema y propone una solución elegante basada en la inyección HTML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_problemática">La problemática</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto_de_uso">Contexto de uso</h3> <div class="paragraph"> <p>Imagina que estás documentando las variables CSS de un tema de una aplicación web. Necesitas:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Listar los códigos de color hexadecimales</p> </li> <li> <p>Mostrar una vista previa visual de cada color</p> </li> <li> <p>Mantener la legibilidad del documento fuente</p> </li> <li> <p>Garantizar la compatibilidad con los generadores de sitios estáticos como JBake</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="use-case-diagram.svg" alt="use case diagram" width="1773" height="5616"> </div> </div> </div> <div class="sect2"> <h3 id="_los_enfoques_posibles">Los enfoques posibles</h3> <div class="paragraph"> <p>Se pueden considerar varias soluciones para mostrar colores en un documento AsciiDoc:</p> </div> <div class="imageblock"> <div class="content"> <img src="component-diagram.svg" alt="component diagram" width="1744" height="5688"> </div> </div> <div class="sect3"> <h4 id="_opción_1_caracteres_unicode">Opción 1 : Caracteres Unicode</h4> <div class="paragraph"> <p>El uso de caracteres Unicode como`■`(■) es simple pero limitada :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* ■ --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitations</strong> : No hay control sobre el color, depende de la fuente del sistema.</p> </div> </div> <div class="sect3"> <h4 id="_opción_2_imágenes_externas">Opción 2: Imágenes externas</h4> <div class="paragraph"> <p>Crear imágenes PNG o SVG para cada color :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* image:colors/violet.svg[width=16] --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p>Limitaciones: Mantenimiento pesado, multiplicación de archivos, falta de sincronización automática.</p> </div> </div> <div class="sect3"> <h4 id="_opción_3_roles_css_personalizados">Opción 3: Roles CSS personalizados</h4> <div class="paragraph"> <p>Definir clases CSS y aplicarlos mediante roles AsciiDoc :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* [.color-violet]##■## --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitaciones</strong> : Necesita una hoja de estilo externa, definición previa de todos los colores posibles.</p> </div> </div> <div class="sect3"> <h4 id="_opción_4_inyección_html_solución_adoptada">Opción 4: Inyección HTML (solución adoptada)</h4> <div class="paragraph"> <p>Utilizar la macro``para inyectar HTML con estilos en línea :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em; background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_inyección_html_con">La solución : Inyección HTML con </h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_de_funcionamiento">Principio de funcionamiento</h3> <div class="paragraph"> <p>La macro``d’AsciiDoc permite insertar contenido sin procesar que no será interpretado por el procesador AsciiDoc. Esto nos permite inyectar directamente HTML con estilos CSS en línea.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "Documento ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "Documento AsciiDoc" as doc participant "Procesador AsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML final" as html doc -> processor : Analyse document processor -> pass : Détecte pass:[] pass -> processor : Retourne HTML brut processor -> html : Insère sans transformation html -> html : Navigateur applique styles @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_implementación">Implementación</h3> <div class="paragraph"> <p>He aquí la estructura HTML para inyectar:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block; width:1em; height:1em; background:#7952b3; vertical-align:middle; margin-right:0.5em"> </span></code></pre> </div> </div> <div class="sect3"> <h4 id="_explicación_de_las_propiedades_css">Explicación de las propiedades CSS</h4> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Propiedad</th> <th class="tableblock halign-left valign-top">Función</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>display:inline-block</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite definir ancho/alto manteniéndose en el flujo en línea</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>width:1em; height:1em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tamaño del cuadrado relativo al tamaño de fuente (responsive)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>background:#7952b3</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El color a mostrar (variable según sus necesidades)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>vertical-align:middle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alinea el cuadrado con el texto adyacente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>margin-right:0.5em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Espaciado entre el cuadrado y el texto</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_ejemplo_completo">Ejemplo completo</h3> <div class="paragraph"> <p>Este es un ejemplo que documenta una paleta de tema :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">== Thème Clair * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)</code></pre> </div> </div> <div class="paragraph"> <p>Quién produce el siguiente render:</p> </div> <div class="paragraph"> <p><strong>Tema Claro</strong></p> </div> <div class="ulist"> <ul> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --bg-primary:`#f8f9fa`(blanco roto)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span> --text-primary:`#212529`(negro muy oscuro)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --accent-color:`#7952b3`(violeta Bootstrap)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span> --accent-hover:`#61428f`(violeta más oscuro)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --card-bg:`#ffffff`(blanco)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_optimizaciones_y_buenas_prácticas">Optimizaciones y buenas prácticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_administrar_los_colores_claros">Administrar los colores claros</h3> <div class="paragraph"> <p>Para los colores muy claros (blanco, gris muy claro), añada un borde para que sean visibles sobre fondo blanco:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block;width:1em;height:1em; background:#ffffff;border:1px solid #ccc; vertical-align:middle;margin-right:0.5em"></span></code></pre> </div> </div> <div class="paragraph"> <p>El borde gris (<code>border:1px solid #ccc</code>) permite delimitar el cuadrado blanco sobre un fondo blanco.</p> </div> </div> <div class="sect2"> <h3 id="_adaptar_el_tamaño_de_los_cuadrados">Adaptar el tamaño de los cuadrados</h3> <div class="paragraph"> <p>Puedes ajustar el tamaño de los cuadrados según tus necesidades:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré * pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré</code></pre> </div> </div> <div class="paragraph"> <p>El uso de la unidad`em`Garantiza que los cuadrados se adapten al tamaño de la fuente.</p> </div> </div> <div class="sect2"> <h3 id="_crear_variantes">Crear variantes</h3> <div class="paragraph"> <p>Para necesidades específicas, puede crear diferentes formas:</p> </div> <div class="sect3"> <h4 id="_círculo_coloreado">Círculo coloreado</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_cuadrado_con_borde_coloreado">Cuadrado con borde coloreado</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_de_la_solución">Arquitectura de la solución</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="architecture-diagram.svg" alt="architecture diagram" width="1763" height="5432"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ventajas_y_limitaciones">Ventajas y limitaciones</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ventajas">Ventajas</h3> <div class="ulist"> <ul> <li> <p>�✓ <strong>Autonomía</strong> : Sin dependencia de archivos externos</p> </li> <li> <p>�✓ <strong>Portabilidad</strong> : Funciona con todos los procesadores AsciiDoc</p> </li> <li> <p>�✓ <strong>Sincronización</strong> : El código de color está directamente en el HTML</p> </li> <li> <p>�✓ <strong>Flexibilidad</strong> : Personalización completa del estilo</p> </li> <li> <p>�✓ <strong>Mantenimiento</strong> : Modificación simple del código hexadecimal</p> </li> <li> <p>�✓ <strong>Compatibilidad JBake</strong> : Funciona perfectamente con los generadores de sitios estáticos</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_limitaciones">Limitaciones</h3> <div class="ulist"> <ul> <li> <p>�✗ <strong>Verbosidad</strong> : Código HTML repetitivo en el código fuente AsciiDoc</p> </li> <li> <p>�✗ <strong>Legibilidad de la fuente</strong> : El documento fuente está menos depurado</p> </li> <li> <p><strong>Accesibilidad</strong> : No hay texto alternativo nativo (por añadir manualmente)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_mejora_de_la_accesibilidad">Mejora de la accesibilidad</h3> <div class="paragraph"> <p>Para hacer accesibles los cuadrados a los lectores de pantalla:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span role="img" aria-label="Couleur violet Bootstrap" style="display:inline-block;width:1em;height:1em;background:#7952b3; vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p>Los atributos`role="img"` et `aria-label`permiten a las tecnologías de asistencia comprender y describir el contenido visual.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ejemplo_concreto_documentación_de_temas">Ejemplo concreto : Documentación de temas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este es un ejemplo completo que documenta varios temas:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Guide des couleurs de l'application == Thème Clair (`:root`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) == Thème Sombre (`[data-bs-theme="dark"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap) == Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>La inyección HTML a través de la macro``d’AsciiDoc ofrece una solución elegante y pragmática para mostrar muestras de color en la documentación técnica. Aunque sea ligeramente verbosa, este enfoque garantiza una portabilidad máxima y un mantenimiento simplificado.</p> </div> <div class="paragraph"> <p>Esta técnica no requiere ninguna configuración externa, ninguna hoja de estilo adicional, y funciona inmediatamente con JBake y todos los procesadores AsciiDoc estándar.</p> </div> <div class="paragraph"> <p>Una vez que haya creado su primer cuadrado de color, basta con copiar y pegar el código HTML y modificar el código hexadecimal para crear rápidamente una paleta completa.</p> </div> <div class="paragraph"> <p>Esta técnica puede extenderse a otros casos de uso que requieran un renderizado visual personalizado: íconos, insignias, gráficos simples o cualquier elemento visual que requiera un control preciso del estilo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_recursos">Recursos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/" target="_blank" rel="noopener">Documentación AsciiDoc: pass macro</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake Documentación</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value" target="_blank" rel="noopener">MDN : Valores de color CSS</a></p> </li> </ul> </div> <div class="paragraph"> <p><em>Artículo publicado el 2025-11-01</em></p> </div> </div> </div> https://cheroliv.com//blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html Mon, 20 Oct 2025 00:00:00 +0000 blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduction">Introduction</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_casos_de_uso_use_case">Diagrama de casos de uso (Use Case)</a></li> </ul> </li> <li><a href="#_arquitectura_de_la_internacionalización">Arquitectura de la internacionalización</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_estructura_organización_de_los_archivos">Diagrama de estructura (Organización de los archivos)</a></li> <li><a href="#_por_qué_este_enfoque">¿Por qué este enfoque?</a></li> <li><a href="#_diagrama_de_componentes">Diagrama de componentes</a></li> </ul> </li> <li><a href="#_i18n_del_templating_con_thymeleaf">I18n del templating con Thymeleaf</a> <ul class="sectlevel2"> <li><a href="#_estructura_de_los_archivos_de_mensajes">Estructura de los archivos de mensajes</a></li> <li><a href="#_contenido_de_los_archivos_de_mensajes">Contenido de los archivos de mensajes</a></li> <li><a href="#_uso_en_las_plantillas">Uso en las plantillas</a></li> <li><a href="#_diagrama_de_secuencia_resolución_i18n">Diagrama de secuencia - Resolución i18n</a></li> <li><a href="#_configuración_de_la_localización_en_jbake">Configuración de la localización en JBake</a></li> </ul> </li> <li><a href="#_i18n_de_los_artículos_organización_por_carpetas">I18n de los artículos : organización por carpetas</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_flujo_flow_generación">Diagrama de flujo (Flow) - Generación</a></li> <li><a href="#_estructura_de_carpetas">Estructura de carpetas</a></li> <li><a href="#_ventajas_de_este_enfoque">Ventajas de este enfoque</a></li> <li><a href="#_metadatos_de_los_artículos">Metadatos de los artículos</a></li> <li><a href="#_configuración_de_url">Configuración de URL</a></li> </ul> </li> <li><a href="#_plantillas_para_la_visualización_multilingüe">Plantillas para la visualización multilingüe</a> <ul class="sectlevel2"> <li><a href="#_plantilla_de_artículo_con_selector_de_idioma">Plantilla de artículo con selector de idioma</a></li> <li><a href="#_índice_filtrado_por_idioma">Índice filtrado por idioma</a></li> </ul> </li> <li><a href="#_navegación_entre_idiomas">Navegación entre idiomas</a> <ul class="sectlevel2"> <li><a href="#_selector_de_idioma_global">Selector de idioma global</a></li> <li><a href="#_diagrama_de_flujo_lectura_de_usuario">Diagrama de flujo - Lectura de usuario</a></li> <li><a href="#_estilo_css_para_el_selector">Estilo CSS para el selector</a></li> </ul> </li> <li><a href="#_fuente_rss_por_idioma">Fuente RSS por idioma</a></li> <li><a href="#_buenas_prácticas_y_consejos">Buenas prácticas y consejos</a> <ul class="sectlevel2"> <li><a href="#_1_coherencia_de_los_identificadores_de_artículo">1. Coherencia de los identificadores de artículo</a></li> <li><a href="#_2_fechas_consistentes">2. Fechas consistentes</a></li> <li><a href="#_3_etiquetas_multilingües">3. Etiquetas multilingües</a></li> <li><a href="#_4_gestión_de_los_artículos_no_traducidos">4. Gestión de los artículos no traducidos</a></li> <li><a href="#_5_mapa_del_sitio_multilingüe">5. Mapa del sitio multilingüe</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_despliegue">Diagrama de despliegue</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>La internacionalización (i18n) de un sitio estático puede parecer compleja a primera vista, pero JBake combinado con Thymeleaf ofrece soluciones elegantes para crear un sitio multilingüe. En este artículo, les voy a mostrar cómo he implementado la i18n en mi blog, cubriendo tanto el templating como la gestión de los artículos en varios idiomas.</p> </div> <div class="sect2"> <h3 id="_diagrama_de_casos_de_uso_use_case">Diagrama de casos de uso (Use Case)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c38398a30ae93d32532701412cdb7153.png" alt="Diagram" width="655" height="455"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_de_la_internacionalización">Arquitectura de la internacionalización</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestro enfoque se basa en dos pilares:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>La i18n del templating</strong>uso de los archivos de mensajes de Thymeleaf para los elementos de la interfaz</p> </li> <li> <p><strong>La i18n del contenido</strong>: organización de los artículos por idioma en una estructura de carpetas dedicada</p> </li> </ol> </div> <div class="sect2"> <h3 id="_diagrama_de_estructura_organización_de_los_archivos">Diagrama de estructura (Organización de los archivos)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-2f100fc3ec2ec37f9556818cdc246602.png" alt="Diagram" width="188" height="513"> </div> </div> </div> <div class="sect2"> <h3 id="_por_qué_este_enfoque">¿Por qué este enfoque?</h3> <div class="paragraph"> <p>Esta separación permite :</p> </div> <div class="ulist"> <ul> <li> <p>Mantener una coherencia en la interfaz cualquiera que sea el idioma</p> </li> <li> <p>Gestionar de forma independiente el contenido y las traducciones de los artículos</p> </li> <li> <p>Facilitar la adición de nuevos idiomas sin una refactorización importante</p> </li> <li> <p>Permitir artículos disponibles solo en algunos idiomas</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_componentes">Diagrama de componentes</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-44cfd9cc29b3d46252cb3224eb36a239.png" alt="Diagram" width="1771" height="477"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i18n_del_templating_con_thymeleaf">I18n del templating con Thymeleaf</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estructura_de_los_archivos_de_mensajes">Estructura de los archivos de mensajes</h3> <div class="paragraph"> <p>El primer paso consiste en crear los archivos de propiedades para cada idioma soportado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">src/jbake/templates/ ├── messages.properties # Fallback par défaut ├── messages_fr.properties # Français ├── messages_en.properties # Anglais └── messages_de.properties # Allemand</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_contenido_de_los_archivos_de_mensajes">Contenido de los archivos de mensajes</h3> <div class="paragraph"> <p>Este es un ejemplo de archivo`messages_fr.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Accueil nav.blog=Blog nav.about=À propos nav.contact=Contact # Articles article.readmore=Lire la suite article.published=Publié le article.tags=Étiquettes article.also.available=Également disponible en # Interface site.title=Mon Blog Technique site.description=Partage de connaissances et expériences footer.copyright=© 2025 Tous droits réservés search.placeholder=Rechercher un article...</code></pre> </div> </div> <div class="paragraph"> <p>Y su equivalente en inglés`messages_en.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Home nav.blog=Blog nav.about=About nav.contact=Contact # Articles article.readmore=Read more article.published=Published on article.tags=Tags article.also.available=Also available in # Interface site.title=My Tech Blog site.description=Sharing knowledge and experiences footer.copyright=© 2025 All rights reserved search.placeholder=Search articles...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_uso_en_las_plantillas">Uso en las plantillas</h3> <div class="paragraph"> <p>En tus plantillas Thymeleaf, utiliza la sintaxis`#{}`para acceder a los mensajes:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> <meta name="description" th:content="#{site.description}" /> </head> <body> <nav> <a th:href="@{/}" th:text="#{nav.home}">Accueil</a> <a th:href="@{/blog/}" th:text="#{nav.blog}">Blog</a> <a th:href="@{/about.html}" th:text="#{nav.about}">À propos</a> </nav> <footer> <p th:text="#{footer.copyright}">Copyright</p> </footer> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_secuencia_resolución_i18n">Diagrama de secuencia - Resolución i18n</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml actor Auteur participant JBake participant "AsciiDoc\nAnalizador" as parser participant "Thymeleaf ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Auteur participant JBake participant "AsciiDoc\nAnalizador" as parser participant "Thymeleaf Engine" as thymeleaf participant "I18n Resolutor" as i18n database "messages_*.properties" as messages Auteur -> JBake: jbake -b activate JBake JBake -> parser: Lire article.fr.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=fr, article-id=xyz) deactivate parser JBake -> parser: Lire article.en.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=en, article-id=xyz) deactivate parser JBake -> thymeleaf: Générer page FR activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_fr.properties messages --> i18n: "Inicio" i18n --> thymeleaf: "Inicio" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=fr) JBake --> thymeleaf: article.en.html trouvé thymeleaf --> JBake: /fr/blog/article.html deactivate thymeleaf JBake -> thymeleaf: Générer page EN activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_en.properties messages --> i18n: "Inicio" i18n --> thymeleaf: "Inicio" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=en) JBake --> thymeleaf: article.fr.html trouvé thymeleaf --> JBake: /en/blog/article.html deactivate thymeleaf JBake --> Auteur: Site généré deactivate JBake @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_configuración_de_la_localización_en_jbake">Configuración de la localización en JBake</h3> <div class="paragraph"> <p>En su archivo`jbake.properties`, establezca la configuración regional predeterminada :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Locale par défaut thymeleaf.locale=fr # Encodage template.encoding=UTF-8</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i18n_de_los_artículos_organización_por_carpetas">I18n de los artículos : organización por carpetas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_flujo_flow_generación">Diagrama de flujo (Flow) - Generación</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-40dcf3727087287b1fb60f7d93bb5998.png" alt="Diagram" width="285" height="1034"> </div> </div> </div> <div class="sect2"> <h3 id="_estructura_de_carpetas">Estructura de carpetas</h3> <div class="paragraph"> <p>En lugar de usar sufijos en los nombres de archivos, he optado por una organización por carpetas que ofrece más claridad y mantenibilidad:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">content/blog/ ├── 2024/ │ ├── fr/ │ │ ├── introduction-jbake.adoc │ │ ├── guide-thymeleaf.adoc │ │ └── astuces-asciidoc.adoc │ └── en/ │ ├── introduction-jbake.adoc │ ├── thymeleaf-guide.adoc │ └── asciidoc-tips.adoc └── 2025/ ├── fr/ │ └── internationalisation-jbake.adoc └── en/ └── jbake-internationalization.adoc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_ventajas_de_este_enfoque">Ventajas de este enfoque</h3> <div class="paragraph"> <p>Esta estructura presenta varias ventajas :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Separación clara</strong>: cada lengua tiene su propio espacio</p> </li> <li> <p><strong>Nomenclatura flexible</strong>: los archivos pueden tener nombres diferentes según el idioma</p> </li> <li> <p><strong>escalabilidad</strong>: fácil de agregar un nuevo idioma</p> </li> <li> <p><strong>Organización natural</strong>: sigue la lógica temporal de JBake</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_metadatos_de_los_artículos">Metadatos de los artículos</h3> <div class="paragraph"> <p>Cada artículo debe contener metadatos para permitir el enlace entre traducciones. Aquí tienes un ejemplo :</p> </div> <div class="paragraph"> <p><strong>Versión francesa</strong>(<code>2025/fr/internationalisation-jbake.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalisation d'un site statique JBake :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: fr :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide pour mettre en place l'i18n avec JBake</code></pre> </div> </div> <div class="paragraph"> <p><strong>Versión inglesa</strong>(<code>2025/en/jbake-internationalization.adoc</code>):</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalizing a JBake Static Site :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: en :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide to implement i18n with JBake</code></pre> </div> </div> <div class="paragraph"> <p>NOTA: El atributo`:jbake-article-id:`es crucial: permite vincular las diferentes traducciones de un mismo artículo.</p> </div> </div> <div class="sect2"> <h3 id="_configuración_de_url">Configuración de URL</h3> <div class="paragraph"> <p>en`jbake.properties`, configure el patrón de URL para incluir el idioma :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Pattern d'URL avec langue post.permalink.pattern=:lang/blog/:year/:name.html # Langue par défaut site.default.lang=fr</code></pre> </div> </div> <div class="paragraph"> <p>Esto generará URL del tipo:</p> </div> <div class="ulist"> <ul> <li> <p><code>/fr/blog/2025/internationalisation-jbake.html</code></p> </li> <li> <p><code>/en/blog/2025/jbake-internationalization.html</code></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plantillas_para_la_visualización_multilingüe">Plantillas para la visualización multilingüe</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_plantilla_de_artículo_con_selector_de_idioma">Plantilla de artículo con selector de idioma</h3> <div class="paragraph"> <p>Cree una plantilla`post.html`que muestra las traducciones disponibles:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="${content.title}">Article</title> </head> <body> <article> <header> <h1 th:text="${content.title}">Titre</h1> <div class="article-meta"> <time th:text="${#dates.format(content.date, 'dd MMMM yyyy')}" th:attr="datetime=${#dates.format(content.date, 'yyyy-MM-dd')}"> Date </time> <!-- Sélecteur de traductions --> <div class="translations" th:if="${content['article-id']}"> <span th:text="#{article.also.available}">Aussi disponible en :</span> <ul class="language-list"> <li th:each="post : ${published_posts}" th:if="${post['article-id'] == content['article-id'] and post.lang != content.lang}"> <a th:href="${post.uri}" th:text="${post.lang.toUpperCase()}"> LANG </a> </li> </ul> </div> </div> </header> <div class="content" th:utext="${content.body}"> Contenu de l'article </div> <footer class="article-footer"> <div class="tags" th:if="${content.tags}"> <span th:text="#{article.tags}">Étiquettes :</span> <span th:each="tag : ${content.tags}"> <a th:href="@{/tags/{tag}.html(tag=${tag})}" th:text="${tag}">tag</a> </span> </div> </footer> </article> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_índice_filtrado_por_idioma">Índice filtrado por idioma</h3> <div class="paragraph"> <p>Cree plantillas de índice para cada idioma:</p> </div> <div class="paragraph"> <p><strong>index.html</strong>(índice francés) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Titre</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Lire la suite </a> </article> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><strong>index_en.html</strong>(índice inglés) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">My Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'en'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Title</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Read more </a> </article> </div> </main> </body> </html></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_navegación_entre_idiomas">Navegación entre idiomas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_selector_de_idioma_global">Selector de idioma global</h3> </div> <div class="sect2"> <h3 id="_diagrama_de_flujo_lectura_de_usuario">Diagrama de flujo - Lectura de usuario</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-35c457cfbd1b9be0156f6bbbfb2925d1.png" alt="Diagram" width="494" height="761"> </div> </div> <div class="paragraph"> <p>Añade un selector de idioma en tu plantilla principal:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><nav class="language-switcher"> <a href="/index.html" th:classappend="${content.lang == 'fr'} ? 'active'" title="Français"> 🇫🇷 FR </a> <a href="/en/index.html" th:classappend="${content.lang == 'en'} ? 'active'" title="English"> 🇬🇧 EN </a> </nav></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_estilo_css_para_el_selector">Estilo CSS para el selector</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.language-switcher { display: flex; gap: 1rem; padding: 0.5rem; background: #f5f5f5; border-radius: 4px; } .language-switcher a { padding: 0.5rem 1rem; text-decoration: none; color: #333; border-radius: 4px; transition: background 0.2s; } .language-switcher a:hover { background: #e0e0e0; } .language-switcher a.active { background: #007bff; color: white; } .translations { margin: 1rem 0; padding: 1rem; background: #f8f9fa; border-left: 4px solid #007bff; } .language-list { display: inline-flex; gap: 0.5rem; list-style: none; padding: 0; margin: 0; } .language-list li::after { content: "•"; margin-left: 0.5rem; } .language-list li:last-child::after { content: ""; }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fuente_rss_por_idioma">Fuente RSS por idioma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para tener canales RSS separados por idioma, cree plantillas distintas :</p> </div> <div class="paragraph"> <p><strong>feed.xml</strong>(flujo francés) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:th="http://www.thymeleaf.org"> <channel> <title th:text="#{site.title}">Mon Blog</title> <link th:text="${config.site_host}">http://example.com</link> <description th:text="#{site.description}">Description</description> <language>fr</language> <item th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <title th:text="${post.title}">Titre</title> <link th:text="${config.site_host + post.uri}">Lien</link> <pubDate th:text="${#dates.format(post.date, 'EEE, dd MMM yyyy HH:mm:ss Z')}"> Date </pubDate> <description th:text="${post.description}">Description</description> </item> </channel> </rss></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas_y_consejos">Buenas prácticas y consejos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_coherencia_de_los_identificadores_de_artículo">1. Coherencia de los identificadores de artículo</h3> <div class="paragraph"> <p>Asegúrate de que`:jbake-article-id:`es idéntico para todas las traducciones del mismo artículo. Utilice un formato coherente:</p> </div> <div class="ulist"> <ul> <li> <p>Prefiere los identificadores en inglés para universalidad</p> </li> <li> <p>Utiliza guiones para separar las palabras</p> </li> <li> <p>Evite los caracteres especiales</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_fechas_consistentes">2. Fechas consistentes</h3> <div class="paragraph"> <p>Todas las traducciones de un artículo deben tener la misma fecha de publicación`:jbake-date:`Esto facilita el ordenamiento y la visualización cronológica.</p> </div> </div> <div class="sect2"> <h3 id="_3_etiquetas_multilingües">3. Etiquetas multilingües</h3> <div class="paragraph"> <p>Para las etiquetas, tienes dos opciones :</p> </div> <div class="paragraph"> <p><strong>Opción 1: Etiquetas universales en inglés</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> <div class="paragraph"> <p><strong>Option 2 : Etiquetas traducidas con mapeo</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc"># Version française :jbake-tags: java, spring-boot, microservices # Version anglaise :jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_gestión_de_los_artículos_no_traducidos">4. Gestión de los artículos no traducidos</h3> <div class="paragraph"> <p>No es obligatorio traducir todos los artículos. Si un artículo existe solo en una lengua, simplemente no aparecerá en las listas de la otra lengua.</p> </div> </div> <div class="sect2"> <h3 id="_5_mapa_del_sitio_multilingüe">5. Mapa del sitio multilingüe</h3> <div class="paragraph"> <p>Genere un sitemap que incluye todos los idiomas:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org"> <url th:each="post : ${published_posts}"> <loc th:text="${config.site_host + post.uri}">URL</loc> <lastmod th:text="${#dates.format(post.date, 'yyyy-MM-dd')}">Date</lastmod> <!-- Liens alternatifs pour les traductions --> <xhtml:link th:each="translation : ${published_posts}" th:if="${translation['article-id'] == post['article-id'] and translation.lang != post.lang}" rel="alternate" th:attr="hreflang=${translation.lang},href=${config.site_host + translation.uri}" /> </url> </urlset></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>La internacionalización de un sitio JBake con Thymeleaf es un enfoque robusto y mantenible. Al separar la i18n del templating (a través de los archivos de mensajes) y la i18n del contenido (a través de la organización en carpetas), obtienes un sistema flexible que puede evolucionar fácilmente.</p> </div> <div class="paragraph"> <p>Los puntos clave a retener :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Archivos de mensajes Thymeleaf</strong>para la interfaz de usuario</p> </li> <li> <p><strong>Organización por carpetas</strong>(año/idioma) para los artículos</p> </li> <li> <p><strong>Identificadores de artículo</strong>para enlazar las traducciones</p> </li> <li> <p><strong>Plantillas dedicadas</strong>para cada idioma</p> </li> <li> <p><strong>URLs explícitas</strong>incluyendo el código de idioma</p> </li> </ul> </div> <div class="sect2"> <h3 id="_diagrama_de_despliegue">Diagrama de despliegue</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 14) ] @startuml node "Máquina de desarrollo" { artifact "Fuentes" { folder "content/" folder "templates/" folder "assets/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Servidor de compilación ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml node "Máquina de desarrollo" { artifact "Fuentes" { folder "content/" folder "templates/" folder "assets/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Servidor de compilación (CI/CD)" { component "GitHub Actions o GitLab CI" as ci jbake --> ci : push } cloud "CDN / Alojamiento" { node "Servidor web estático" { artifact "Sitio Generado" { folder "/es/blog/" folder "/es/blog/" folder "/assets/" } } } ci --> "Sitio Generado" : déploiement actor "Lectores" as users users --> "Servidor web estático" : HTTPS @enduml</pre> </div> </div> <div class="paragraph"> <p>Esta arquitectura le permite comenzar fácilmente con dos idiomas y agregar otros sin una refactorización importante. Todo permanece completamente estático y de alto rendimiento, fiel a la filosofía de JBake.</p> </div> <div class="paragraph"> <p>¡Buen desarrollo multilingüe! 🌍</p> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0094_tor_browser_install_post.html Sun, 5 Oct 2025 00:00:00 +0000 blog/2025/0094_tor_browser_install_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_descarga_de_tor_y_su_firma">Descarga de Tor y su firma</a></li> <li><a href="#_verificación_criptográfica_de_la_firma">Verificación criptográfica de la firma</a> <ul class="sectlevel2"> <li><a href="#_importar_la_clave_pública_del_proyecto_tor">Importar la clave pública del proyecto Tor</a></li> <li><a href="#_2_verificar_la_firma">2. Verificar la firma</a></li> <li><a href="#_caso_práctico_firma_válida_pero_clave_no_certificada">Caso práctico: firma válida pero clave no certificada</a></li> </ul> </li> <li><a href="#_por_qué_verificar_la_firma">¿Por qué verificar la firma?</a></li> <li><a href="#_extracción_y_lanzamiento_de_tor_browser">Extracción y lanzamiento de Tor Browser</a></li> <li><a href="#_integración_al_escritorio_ubuntu">Integración al escritorio Ubuntu</a></li> <li><a href="#_explorar_recursos_educativos_con_tor">Explorar recursos educativos con Tor</a></li> <li><a href="#_actualización_de_tor_browser">Actualización de Tor Browser</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_referencias">Referencias</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>En un mundo donde la confidencialidad digital está cada vez más amenazada, <strong>Tor Browser</strong> sigue siendo una herramienta esencial para preservar su anonimato y su libertad de información. Sin embargo, es crucial nunca ejecutar un software descargado sin haber<strong>verificado su autenticidad</strong>. Este artículo presenta un método completo para :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Descargar <strong>Tor Browser</strong> y su firma`.asc`</p> </li> <li> <p>Comprobar la validez del archivo descargado</p> </li> <li> <p>Instalar y ejecutar <strong>Tor Browser</strong> en Ubuntu</p> </li> <li> <p>Añadirlo a los menús del escritorio para un uso diario</p> </li> <li> <p>Explorar recursos educativos y OSINT éticos a través de Tor</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_descarga_de_tor_y_su_firma">Descarga de Tor y su firma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Crea una carpeta dedicada para el navegador Tor:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/workspace/tipiak/tor cd ~/workspace/tipiak/tor</code></pre> </div> </div> <div class="paragraph"> <p>Descarga a continuación el archivo del navegador Tor y su firma :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz.asc</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificación_criptográfica_de_la_firma">Verificación criptográfica de la firma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta etapa es<strong>indispensable</strong>para asegurarse de que el archivo descargado proviene bien del <strong>Tor Project</strong> y no ha sido modificado.</p> </div> <div class="sect2"> <h3 id="_importar_la_clave_pública_del_proyecto_tor">Importar la clave pública del proyecto Tor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org</code></pre> </div> </div> <div class="paragraph"> <p>Verifique que la clave esté bien importada :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --list-keys torbrowser@torproject.org</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_verificar_la_firma">2. Verificar la firma</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz</code></pre> </div> </div> <div class="paragraph"> <p>Si todo es correcto, se mostrará el siguiente mensaje :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg: Good signature from "Tor Browser Developers (signing key)"</code></pre> </div> </div> <div class="paragraph"> <p>En caso de advertencia de clave no certificada, esto simplemente significa que aún no ha firmado la clave de confianza del proyecto Tor, pero la firma sigue siendo válida.</p> </div> </div> <div class="sect2"> <h3 id="_caso_práctico_firma_válida_pero_clave_no_certificada">Caso práctico: firma válida pero clave no certificada</h3> <div class="paragraph"> <p>Es frecuente encontrarse con un mensaje como este durante la verificación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz gpg: Signature faite le mar. 16 sept. 2025 14:26:26 CEST gpg: avec la clef RSA CAAE408AEBE2288E96FC5D5E157432CF78A65729 gpg: Bonne signature de « Tor Browser Developers (signing key) <torbrowser@torproject.org> » [inconnu] gpg: Attention : cette clef n'est pas certifiée avec une signature de confiance. gpg: Rien n'indique que la signature appartient à son propriétaire. Empreinte de clef principale : EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290 Empreinte de la sous-clef : CAAE 408A EBE2 288E 96FC 5D5E 1574 32CF 78A6 5729</code></pre> </div> </div> <div class="paragraph"> <p>Este mensaje indica que la firma es técnicamente "buena" (el archivo no ha sido alterado), pero que su sistema GPG no puede <strong>certificar la confianza</strong> en la clave misma. Para eliminar esta duda, es imperativo comparar la huella de la clave principal (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) con la publicada en el sitio oficial del Tor Project.</p> </div> <div class="paragraph"> <p>Según el sitio oficial, la huella esperada es:`EF6E286DDA85EA2A4BA7DE684E2C6E8793298290`.</p> </div> <div class="paragraph"> <p>Puesto que la huella mostrada por`gpg`coincide <strong>exactamente</strong> con la del sitio oficial, puede estar seguro de que la clave es legítima y que el archivo es seguro. La advertencia de "clave no certificada" es entonces información sobre su configuración GPG local, y no sobre la validez de la firma o la autenticidad del archivo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_qué_verificar_la_firma">¿Por qué verificar la firma?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La verificación de las firmas GPG es un acto fundamental de seguridad digital. Permite :</p> </div> <div class="ulist"> <ul> <li> <p>Garantizar<strong>la autenticidad</strong>del software descargado</p> </li> <li> <p>Impedir la instalación de un archivo comprometido por un actor malicioso</p> </li> <li> <p>Participar en la<strong>soberanía digital</strong>individual</p> </li> <li> <p>Fomentar una cultura digital responsable y ética</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="usecase-tor-verification.svg" alt="usecase tor verification" width="380" height="261"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_extracción_y_lanzamiento_de_tor_browser">Extracción y lanzamiento de Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Descomprima el archivo descargado:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">tar -xvf tor-browser-linux-x86_64-14.5.7.tar.xz cd tor-browser</code></pre> </div> </div> <div class="paragraph"> <p>Lanza luego el navegador:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>Durante el primer arranque, se abrirá una ventana de configuración para establecer la conexión a la red Tor.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integración_al_escritorio_ubuntu">Integración al escritorio Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para añadir <strong>Tor Browser</strong> en el menú de aplicaciones:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop --register-app</code></pre> </div> </div> <div class="paragraph"> <p>Luego puede:</p> </div> <div class="ulist"> <ul> <li> <p>Lanzar <strong>Tor Browser</strong> desde el menú de aplicaciones</p> </li> <li> <p>Añadirlo a los favoritos del dock</p> </li> <li> <p>Crear un atajo de teclado si se desea</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="activity-tor-installation.svg" alt="activity tor installation" width="457" height="470"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_explorar_recursos_educativos_con_tor">Explorar recursos educativos con Tor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor no es únicamente una herramienta de anonimato. Constituye un portal de acceso a recursos educativos e investigadores, especialmente en los campos de :</p> </div> <div class="ulist"> <ul> <li> <p><strong>OSINT (Inteligencia de Fuentes Abiertas)</strong></p> </li> <li> <p><a href="https://inteltechniques.com">https://inteltechniques.com</a></p> </li> <li> <p><a href="https://osintframework.com">https://osintframework.com</a></p> </li> <li> <p><strong>Compartir educativo y código abierto</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(acceso a través de Tor para mayor confidencialidad)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(consultable vía Tor)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(acceso a la literatura científica libre)</p> </li> <li> <p><strong>Transmisión de conocimiento y comprensión del ser humano en la sociedad digital</strong></p> </li> <li> <p>Recursos sobre la cultura digital, la libertad de expresión y el acceso al conocimiento</p> </li> <li> <p>Documentación libre sobre ciberseguridad y ética de las tecnologías</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_actualización_de_tor_browser">Actualización de Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para garantizar una seguridad óptima, es crucial mantener <strong>Tor Browser</strong> actualizado. El navegador incorpora un mecanismo de actualización automática que puede activarse desde la línea de comandos.</p> </div> <div class="paragraph"> <p>Desde el directorio de instalación de Tor Browser, basta con volver a ejecutar el script de inicio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cd ~/workspace/tipiak/tor/tor-browser ./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>Al iniciar, <strong>Tor Browser</strong> comprobará automáticamente si existe una nueva versión. Si es así, la descargará e instalará para usted.</p> </div> <div class="paragraph"> <p>Este método sencillo garantiza que siempre disponga de los últimos parches de seguridad y las mejoras más recientes, lo cual es esencial para una navegación segura.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comprobar sus descargas es un reflejo esencial para toda persona que desea evolucionar en un entorno digital seguro. Instalar Tor de manera verificada, es<strong>proteger su integridad digital</strong>, <strong>preservar la confianza en el software libre</strong>, et <strong>reforzar su autonomía informativa</strong>.</p> </div> <div class="paragraph"> <p>La seguridad digital es un acto de conciencia, no de paranoia.</p> </div> <div class="imageblock"> <div class="content"> <img src="summary-diagram.svg" alt="summary diagram" width="505" height="203"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_referencias">Referencias</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Sitio oficial del proyecto Tor :https://www.torproject.org/download/[<a href="https://www.torproject.org/download/" class="bare">https://www.torproject.org/download/</a>]</p> </li> <li> <p>Documentación de verificación de las firmas:https://support.torproject.org/tbb/how-to-verify-signature/[<a href="https://support.torproject.org/tbb/how-to-verify-signature/" class="bare">https://support.torproject.org/tbb/how-to-verify-signature/</a>]</p> </li> <li> <p>Documentación de Ubuntu :https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>Archivo educativo:https://archive.org/details/opensource[<a href="https://archive.org/details/opensource" class="bare">https://archive.org/details/opensource</a>]</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Este artículo forma parte de la serie <strong>Seguridad y Conciencia Digital</strong> orientado a promover prácticas responsables y pedagógicas alrededor de las herramientas libres.</p> </div> </td> </tr> </table> </div> </div> </div> https://cheroliv.com//blog/2025/0093_gradle_plugin_toml_composite_build_post.html Sat, 27 Sep 2025 00:00:00 +0000 blog/2025/0093_gradle_plugin_toml_composite_build_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_el_catálogo_de_versiones_libs_versions_toml_un_recordatorio">El Catálogo de Versiones (<code>libs.versions.toml</code>) : Un Recordatorio</a></li> <li><a href="#_2_el_problema_una_compilación_compuesta_y_dos_mundos_separados">2. El Problema: una compilación compuesta y dos mundos separados</a></li> <li><a href="#_3_la_solución_compartir_la_resolución_de_dependencias">3. La Solución: Compartir la Resolución de Dependencias</a></li> <li><a href="#_4_conclusión_el_poder_de_los_builds_compuestos_bien_gestionados">4. Conclusión : El Poder de los Builds Compuestos Bien Gestionados</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público objetivo: Desarrolladores de Gradle enfrentados a la gestión de dependencias en proyectos multi-builds.</div> <p>En nuestra búsqueda para crear el plugin`site-baker`, hemos buscado mantener una base de código limpia y centralizada. Una de las mejores prácticas en el ecosistema Gradle moderno es el uso del<strong>catálogo de versiones</strong>(<code>libs.versions.toml</code>) para gestionar las dependencias. Pero, ¿qué ocurre cuando tu proyecto se vuelve más complejo, como un<strong>construir compuesto</strong>¿Dónde una compilación independiente (nuestro plugin) debe incluirse en otra ?</p> </div> <div class="paragraph"> <p>Fue allí donde nuestra aventura tomó un giro inesperado. Queríamos que nuestro plugin`site-baker`, que es él mismo un proyecto Gradle, utiliza el mismo catálogo de versiones que nuestro proyecto principal. Este artículo, el quinto de nuestra serie, cuenta cómo hemos resuelto este desafío.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_catálogo_de_versiones_libs_versions_toml_un_recordatorio">El Catálogo de Versiones (<code>libs.versions.toml</code>) : Un Recordatorio</h2> <div class="sectionbody"> <div class="paragraph"> <p>El archivo`gradle/libs.versions.toml`es una funcionalidad de Gradle que permite centralizar las versiones y las coordenadas de las dependencias de su proyecto. Generalmente se estructura en cuatro secciones:</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: Define alias para los números de versión (ej:`kotlin = "1.9.20"`).</p> </li> <li> <p><code>[libraries]</code>: Define alias para las dependencias completas, utilizando las versiones definidas anteriormente (ej:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }`).</p> </li> <li> <p><code>[bundles]</code>: Agrupa varias bibliotecas bajo un solo alias (ej:`jackson = ["jackson-core", "jackson-databind"]`).</p> </li> <li> <p><code>[plugins]</code>: Define alias para los plugins Gradle.</p> </li> </ul> </div> <div class="paragraph"> <p>Una vez definido, Gradle genera automáticamente accesores tipados, lo que hace que su`build.gradle.kts`mucho más legible :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20") implementation(libs.kotlin.stdlib) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="toml-flow.svg" alt="toml flow" width="474" height="252"> </div> <div class="title">Figure 1. Flujo de datos del catálogo de versiones</div> </div> </div> </div> <div class="sect1"> <h2 id="_2_el_problema_una_compilación_compuesta_y_dos_mundos_separados">2. El Problema: una compilación compuesta y dos mundos separados</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestra estructura de proyecto es un<strong>construir compuesto</strong>. El proyecto principal (<code>thymeleaf.cheroliv.com</code>) incluye el proyecto del plugin (<code>site-baker</code>) a través del comando`includeBuild("site-baker")<code>en el archivo`settings.gradle.kts</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="composite-build.svg" alt="composite build" width="1628" height="5708"> </div> <div class="title">Figure 2. Estructura del build compuesto</div> </div> <div class="paragraph"> <p>El problema es que, por defecto, un build incluido es un<strong>mundo separado</strong>. Tiene su propia configuración, su propio ciclo de vida, y no ve el archivo`libs.versions.toml`del build principal. Nuestro`plugin/build.gradle.kts`intentaba utilizar`libs.plugins.kotlin.jvm`, pero el objeto`libs`no se estaba generando a partir del archivo TOML correcto, provocando errores de compilación.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_la_solución_compartir_la_resolución_de_dependencias">3. La Solución: Compartir la Resolución de Dependencias</h2> <div class="sectionbody"> <div class="paragraph"> <p>Después de varias investigaciones, la solución resultó ser una funcionalidad de Gradle diseñada precisamente para este caso:`dependencyResolutionManagement`.</p> </div> <div class="paragraph"> <p>En el archivo`settings.gradle.kts` du <strong>build incluido</strong>(<code>site-baker/settings.gradle.kts</code>), nosotros podemos decirle a Gradle dónde encontrar el catálogo de versiones que se debe usar.</p> </div> <div class="paragraph"> <p>Aquí está la configuración que hemos añadido a`site-baker/settings.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// site-baker/settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { gradlePluginPortal() mavenCentral() } versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } } rootProject.name = "site-baker" include("plugin")</code></pre> </div> </div> <div class="paragraph"> <p>Analicemos la parte crucial:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">versionCatalogs { create("libs") { // Crée un catalogue nommé 'libs' from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier } }</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>create("libs")</code>: Declaramos un catálogo de versiones que será accesible a través del alias`libs`.</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))</code>: Es la magia. Le indicamos a Gradle que la fuente de este catálogo es el archivo TOML ubicado en el directorio`gradle` du <strong>proyecto padre</strong>(<code>../</code>).</p> </li> </ul> </div> <div class="paragraph"> <p>Con esta configuración, el build`site-baker`sabe ahora que él debe utilizar el catálogo de versiones del proyecto principal. El objeto`libs`se genera correctamente, y las dependencias se resuelven como se esperaba.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_conclusión_el_poder_de_los_builds_compuestos_bien_gestionados">4. Conclusión : El Poder de los Builds Compuestos Bien Gestionados</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta experiencia ha sido rica en aprendizajes. El catálogo de versiones es una herramienta fantástica para la mantenibilidad, pero su comportamiento en escenarios de builds compuestos no siempre es intuitivo.</p> </div> <div class="paragraph"> <p>La clave es recordar que una compilación incluida sigue siendo una compilación independiente. Para compartir configuraciones como el catálogo de versiones, hay que utilizar los mecanismos explícitos proporcionados por Gradle, como el bloque.<code>dependencyResolutionManagement`dentro de`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>Al resolver este problema, no solo hemos hecho que nuestro build sea más limpio, sino que también hemos reforzado la coherencia de nuestro proyecto al asegurarnos de que el plugin y el proyecto principal compartan una única fuente de verdad para sus dependencias.</p> </div> <div class="paragraph"> <p>En el próximo artículo, continuaremos enriqueciendo nuestro plugin añadiéndole tareas más complejas, ahora que nuestra gestión de dependencias es sólida y centralizada.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0092_gradle_configuration_cache_post.html Fri, 26 Sep 2025 00:00:00 +0000 blog/2025/0092_gradle_configuration_cache_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_el_síntoma_construcciones_fantasma">El síntoma : Construcciones fantasma</a></li> <li><a href="#_la_encuesta_qué_es_la_caché_de_configuración">La encuesta: ¿Qué es la caché de configuración?</a></li> <li><a href="#_la_causa_del_problema_un_plugin_no_conforme">La causa del problema: un plugin no conforme</a></li> <li><a href="#_la_solución_temporal_desactivar_la_caché">La solución temporal: Desactivar la caché</a></li> <li><a href="#_la_verdadera_solución_hacer_el_plugin_compatible">La verdadera solución: hacer el plugin compatible</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público objetivo : Desarrolladores Gradle que ya han encontrado comportamientos de compilación 'mágicos' o inesperados.</div> <p>En nuestra aventura de crear el plugin`site-baker`, seguimos un enfoque TDD riguroso. Cada funcionalidad estaba probada, validada, y avanzábamos con confianza. Y luego, un día, lo inesperado llegó. Las builds empezaron a comportarse de manera errática. Los cambios en la lógica del plugin o en los archivos de configuración parecían ser ignorados, y nuestras pruebas funcionales, antes fiables, fallaban sin razón aparente.</p> </div> <div class="paragraph"> <p>Este tipo de problema puede ser increíblemente frustrante. Pone en duda la fiabilidad de la herramienta y la validez de nuestro código. Tras una sesión intensa de depuración, el culpable ha sido identificado: el<strong>caché de configuración de Gradle</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_síntoma_construcciones_fantasma">El síntoma : Construcciones fantasma</h2> <div class="sectionbody"> <div class="paragraph"> <p>El problema se manifestaba de varias maneras:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Estaba modificando una cadena de caracteres en una tarea.<code>println</code>, pero la antigua cadena seguía mostrándose en tiempo de ejecución.</p> </li> <li> <p>Estaba cambiando un valor en mi archivo`managed-jbake-context.yml`, pero el plugin actuaba como si el archivo no hubiera sido modificado.</p> </li> <li> <p>Los tests funcionales, que crean proyectos de prueba al vuelo, fallaban porque el plugin no parecía detectar los archivos de configuración recién creados.</p> </li> </ol> </div> <div class="paragraph"> <p>Todo ocurría como si Gradle ejecutara una "versión fantasma" de nuestra compilación, ignorando nuestros cambios más recientes.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_encuesta_qué_es_la_caché_de_configuración">La encuesta: ¿Qué es la caché de configuración?</h2> <div class="sectionbody"> <div class="paragraph"> <p>El caché de configuración es una característica relativamente moderna y extremadamente potente de Gradle, activada por defecto en las nuevas versiones. Su objetivo es hacer que los builds sean más rápidos.</p> </div> <div class="olist arabic"> <div class="title">El principio es simple :</div> <ol class="arabic"> <li> <p>Durante la primera ejecución, Gradle ejecuta la fase de<strong>Configuración</strong>(lectura de`build.gradle.kts`, creación de las tareas, resolución de dependencias) y construye un grafo de tareas.</p> </li> <li> <p>Al final de esta fase, Gradle<strong>serializa este grafo de tareas</strong>y lo guarda en caché.</p> </li> <li> <p>En las ejecuciones siguientes, si nada ha cambiado (scripts de compilación,<code>gradle.properties</code>, etc.), Gradle<strong>omite completamente la fase de configuración</strong>y reutiliza el grafo de tareas almacenado en caché</p> </li> </ol> </div> <div class="paragraph"> <p>El ahorro de tiempo es espectacular en los proyectos grandes. Sin embargo, este rendimiento tiene un precio: impone reglas estrictas sobre cómo deben escribirse los plugins.</p> </div> <div class="imageblock"> <div class="content"> <img src="config-cache-lifecycle.svg" alt="config cache lifecycle" width="661" height="709"> </div> <div class="title">Figure 1. El ciclo de vida de la caché de configuración</div> </div> </div> </div> <div class="sect1"> <h2 id="_la_causa_del_problema_un_plugin_no_conforme">La causa del problema: un plugin no conforme</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestro plugin`site-baker`violait, sin saberlo, varias reglas de la caché de configuración. Para que un grafo de tareas sea serializable, las tareas no deben contener referencias a objetos complejos como el objeto`Project`o leer archivos de manera arbitraria durante la fase de ejecución.</p> </div> <div class="paragraph"> <p>Nuestro error principal era leer el contenido del archivo YAML directamente dentro de la lógica de ejecución de la tarea, utilizando una referencia al camino almacenado en nuestra extensión. Este enfoque es incompatible con el caché porque Gradle no puede saber si el contenido del archivo ha cambiado si esta lectura no se modela como una<strong>entrada de tarea</strong>( tarea entrada ).</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_temporal_desactivar_la_caché">La solución temporal: Desactivar la caché</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para desbloquearnos y recuperar un comportamiento de compilación predecible, la solución más rápida fue desactivar la caché de configuración. Basta con agregar la siguiente línea en el archivo`gradle.properties`del proyecto que utiliza el plugin (o en nuestro caso, el proyecto de prueba`site-baker`) .</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># site-baker/gradle.properties org.gradle.configuration-cache=false</code></pre> </div> </div> <div class="paragraph"> <p>Instantáneamente, los builds recuperaron su comportamiento normal. Cada ejecución reiniciaba la fase de configuración y nuestros cambios fueron tenidos en cuenta.</p> </div> <div class="paragraph"> <p>Sin embargo, es una solución de contorno, no una solución duradera. Sacrifica el rendimiento y no resuelve el problema de fondo de nuestro plugin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_verdadera_solución_hacer_el_plugin_compatible">La verdadera solución: hacer el plugin compatible</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que un plugin sea un buen ciudadano del ecosistema Gradle moderno, debe ser compatible con el caché de configuración. Esto implica repensar la forma en que los datos fluyen hacia nuestras tareas.</p> </div> <div class="paragraph"> <p>La clave es utilizar los<strong>APIs del proveedor</strong>de Gradle. En lugar de pasar valores directos (como un`String` ou un <code>File</code>) a nuestras tareas, nosotros debemos pasar algunos`Property<T>`o de`Provider<T>`.</p> </div> <div class="olist arabic"> <div class="title">Este es el plan de refactorización :</div> <ol class="arabic"> <li> <p><strong>Declarar las entradas de tareas :</strong>La tarea que analiza el archivo YAML debe declarar este archivo como una entrada. Se utiliza para ello la anotación`@InputFile`.</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] (No output, as there is no French text provided to translate) @get:InputFile abstracto val configFile: RegularFileProperty </think></p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0091_jackson_yaml_tdd_post.html Thu, 25 Sep 2025 00:00:00 +0000 blog/2025/0091_jackson_yaml_tdd_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_1_el_contexto_nuestro_plugin_site_baker">1. El Contexto : Nuestro Plugin `site-baker</a></li> <li><a href="#_2_modelado_de_la_configuración_en_kotlin">2. Modelado de la configuración en Kotlin</a></li> <li><a href="#_3_integración_de_jackson_en_el_build_gradle_kts">3. Integración de Jackson en el `build.gradle.kts</a></li> <li><a href="#_4_el_enfoque_tdd_probar_el_análisis_yaml">4. El Enfoque TDD : Probar el Análisis YAML</a> <ul class="sectlevel2"> <li><a href="#_4_1_prueba_unitaria_mapear_el_yaml_a_un_objeto_kotlin">4.1. Prueba unitaria: Mapear el YAML a un objeto Kotlin</a></li> <li><a href="#_4_2_test_funcional_validar_la_lectura_del_archivo_de_configuración">4.2. Test Funcional : Validar la Lectura del Archivo de Configuración</a></li> </ul> </li> <li><a href="#_5_visualización_del_flujo_de_análisis">5. Visualización del Flujo de Análisis</a></li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público objetivo : Desarrolladores Gradle intermedios que desean gestionar configuraciones complejas.</div> <p>En el desarrollo de plugins Gradle, la gestión de configuraciones complejas es una tarea común. En lugar de sobrecargar el DSL con cientos de propiedades, suele ser más limpio y mantenible definir la configuración en un archivo externo, como el YAML. Este artículo te guía a través de la integración de la potente biblioteca Jackson para analizar archivos YAML en objetos Kotlin, adoptando un enfoque TDD riguroso para garantizar la robustez de nuestro plugin.<code>site-baker</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_el_contexto_nuestro_plugin_site_baker">1. El Contexto : Nuestro Plugin `site-baker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestro plugin`site-baker`está diseñado para automatizar la generación y el despliegue de un sitio estático. Necesita leer un archivo de configuración YAML (<code>managed-jbake-context.yml</code>) para obtener información como las rutas de los fuentes, los destinos de despliegue y los identificadores de Git.</p> </div> <div class="paragraph"> <p>La configuración YAML que queremos analizar se parece a esto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" cname: "cheroliv.com" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/pages-content.github.io.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com" # ... autres configurations (pushMaquette, supabase, etc.)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_modelado_de_la_configuración_en_kotlin">2. Modelado de la configuración en Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de parsear, debemos definir la estructura de nuestros datos en Kotlin. Jackson utilizará estas clases para mapear automáticamente el contenido YAML.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt package com.cheroliv.site.baker.data import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.dataformat.yaml.YAMLFactory import com.fasterxml.jackson.module.kotlin.readValue import com.fasterxml.jackson.module.kotlin.registerKotlinModule fun parseSiteConfiguration(yaml: String): SiteConfiguration { val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule() return mapper.readValue(yaml) } data class GitPushConfiguration( val from: String = "", val to: String = "", val repo: RepositoryConfiguration = RepositoryConfiguration(), val branch: String = "", val message: String = "", ) data class RepositoryConfiguration( val name: String = "", val repository: String = "", val credentials: RepositoryCredentials = RepositoryCredentials(), ) { companion object { const val ORIGIN = "origin" const val CNAME = "CNAME" const val REMOTE = "remote" } } data class RepositoryCredentials(val username: String = "", val password: String = "") data class SiteConfiguration( val bake: BakeConfiguration = BakeConfiguration(), val pushPage: GitPushConfiguration = GitPushConfiguration(), val pushMaquette: GitPushConfiguration = GitPushConfiguration(), val pushSource: GitPushConfiguration? = null, val pushTemplate: GitPushConfiguration? = null, val supabase: SupabaseContactFormConfig? = null ) data class BakeConfiguration( val srcPath: String = "", val destDirPath: String = "", val cname: String? = null, ) // ... (autres data classes pour Supabase, si nécessaire)</code></pre> </div> </div> <div class="paragraph"> <p>La función`parseSiteConfiguration`es nuestro punto de entrada para la deserialización. Ella utiliza`ObjectMapper`de Jackson, configurado con`YAMLFactory`pour el formato YAML y`registerKotlinModule()`para el soporte de las especificidades de Kotlin (como los valores predeterminados de las propiedades).</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_integración_de_jackson_en_el_build_gradle_kts">3. Integración de Jackson en el `build.gradle.kts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para usar Jackson, debemos agregar las dependencias necesarias en el`build.gradle.kts`de nuestro módulo`plugin` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/build.gradle.kts dependencies { // Jackson for YAML parsing implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3") implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3") // ... autres dépendances }</code></pre> </div> </div> <div class="paragraph"> <p>Utilizamos`jackson-module-kotlin`para el soporte de Kotlin y`jackson-dataformat-yaml`para la gestión del formato YAML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_el_enfoque_tdd_probar_el_análisis_yaml">4. El Enfoque TDD : Probar el Análisis YAML</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ahora, apliquemos el TDD para validar nuestra lógica de análisis.</p> </div> <div class="sect2"> <h3 id="_4_1_prueba_unitaria_mapear_el_yaml_a_un_objeto_kotlin">4.1. Prueba unitaria: Mapear el YAML a un objeto Kotlin</h3> <div class="paragraph"> <p>Comenzamos con una prueba unitaria en`SiteBakerPluginTest.kt`para comprobar que la función`parseSiteConfiguration`puede transformar correctamente una cadena YAML en un objeto`SiteConfiguration`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt @Test fun `can map configuration text to SiteConfiguration object`() { val yamlString = "../../managed-jbake-context.yml" .run(::File) .readText() .trimIndent() val config: SiteConfiguration = parseSiteConfiguration(yamlString) assertEquals("cheroliv.com", config.bake.cname) assertEquals("main", config.pushPage.branch) assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository) }</code></pre> </div> </div> <div class="paragraph"> <p>Esta prueba lee el contenido del archivo`managed-jbake-context.yml`(que debe existir para que la prueba sea válida) y realiza afirmaciones sobre el objeto`SiteConfiguration`resultante. Valida que los valores clave del YAML están correctamente mapeados.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_test_funcional_validar_la_lectura_del_archivo_de_configuración">4.2. Test Funcional : Validar la Lectura del Archivo de Configuración</h3> <div class="paragraph"> <p>Para asegurarnos de que el plugin pueda leer el archivo de configuración a través de su DSL y que el análisis funcione en un entorno Gradle real, agregamos una prueba funcional en`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="paragraph"> <p>Esta prueba es crucial porque simula la ejecución del plugin en un proyecto real. Debe ser<strong>hermético</strong>, es decir que debe crear él mismo el archivo`managed-jbake-context.yml`con un contenido controlado, para garantizar la reproducibilidad y el aislamiento del test.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt @Test fun `config file contains good data`(){ val configContent = configFile.readText(UTF_8) // Vérifications comme dans vos commentaires assertTrue(configContent.contains("bake")) assertTrue(configContent.contains("pushPage")) assertTrue(configContent.contains("repository")) }</code></pre> </div> </div> <div class="paragraph"> <p>Este test funcional verifica que el archivo de configuración copiado en el directorio temporal de la prueba contiene los datos esperados. Aunque este test no parsea directamente el YAML a un objeto Kotlin, valida la presencia del archivo y de su contenido, lo cual es un paso previo esencial para el parsing por el plugin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_visualización_del_flujo_de_análisis">5. Visualización del Flujo de Análisis</h2> <div class="sectionbody"> <div class="paragraph"> <p>El siguiente diagrama ilustra el flujo de datos y las interacciones durante el análisis de la configuración YAML:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-7f9125145a35faf6ec1e9258c2b6d138.png" alt="Diagram" width="1534" height="472"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Siguiendo un enfoque TDD, hemos integrado con éxito la biblioteca Jackson para analizar archivos de configuración YAML en objetos Kotlin dentro de nuestro plugin Gradle. Este método nos ha permitido:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Modelar claramente</strong>nuestra configuración con clases de datos Kotlin.</p> </li> <li> <p><strong>Validar la lógica de análisis</strong>con pruebas unitarias específicas.</p> </li> <li> <p><strong>Asegurar la integración</strong>en un entorno Gradle real gracias a pruebas funcionales herméticas.</p> </li> </ul> </div> <div class="paragraph"> <p>Esta base sólida nos brinda una gran confianza para extender nuestro plugin con funcionalidades que se basen en esta configuración, al mismo tiempo que garantiza la mantenibilidad y la robustez del código. El parsing YAML ahora es una característica fiable y probada de nuestro plugin.<code>site-baker</code>.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0090_TDD_gradle_plugin_post.html Wed, 24 Sep 2025 00:00:00 +0000 blog/2025/0090_TDD_gradle_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_la_inicialización_del_proyecto">La Inicialización del Proyecto</a></li> <li><a href="#_nuestro_primer_ciclo_tdd_registrar_una_tarea">Nuestro Primer Ciclo TDD: Registrar una tarea</a> <ul class="sectlevel2"> <li><a href="#_2_1_el_test_primero_el_test_que_falla">2.1. El Test Primero (El Test que Falla)</a></li> <li><a href="#_2_2_el_código_luego_hacer_pasar_la_prueba">2.2. El Código Luego (Hacer Pasar la Prueba)</a></li> </ul> </li> <li><a href="#_3_segundo_ciclo_tdd_agregar_una_extensión_dsl">3. Segundo Ciclo TDD : Agregar una Extensión DSL</a> <ul class="sectlevel2"> <li><a href="#_3_1_primero_el_test">3.1. Primero el test</a></li> <li><a href="#_3_2_el_código_luego">3.2. El código luego</a></li> </ul> </li> <li><a href="#_4_la_prueba_funcional_validar_la_integración">4. La prueba funcional: validar la integración</a> <ul class="sectlevel2"> <li><a href="#_4_1_la_prueba_de_integración_crear_un_entorno_controlado">4.1. La prueba de integración: crear un entorno controlado</a></li> <li><a href="#_4_2_finalizar_la_lógica">4.2. Finalizar la lógica</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>En este artículo, vamos a explorar cómo establecer una base de desarrollo sólida para un plugin Gradle utilizando un enfoque de Desarrollo Guiado por Pruebas (TDD - Test-Driven Development). Este método nos asegura que nuestro código es robusto, mantenable y responde precisamente a los requisitos desde el principio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_inicialización_del_proyecto">La Inicialización del Proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle facilita mucho la creación de un nuevo plugin gracias al comando`gradle init`. Al elegir crear un "Gradle Plugin" con Kotlin, obtenemos una estructura de proyecto lista para usar, incluyendo dos tipos de pruebas cruciales :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Pruebas unitarias :</strong>Situados en`src/test`, permiten validar componentes aislados de nuestro plugin, como la lógica interna de una tarea o la configuración de una extensión. Son rápidos y no necesitan una ejecución completa de Gradle.</p> </li> <li> <p><strong>Pruebas funcionales:</strong>Situados en`src/functionalTest`, ellos utilizan`GradleRunner`Para ejecutar una compilación completa de Gradle en un proyecto de prueba temporal. Esto nos permite comprobar el comportamiento real del plugin en un entorno controlado.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_nuestro_primer_ciclo_tdd_registrar_una_tarea">Nuestro Primer Ciclo TDD: Registrar una tarea</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestra primera exigencia es simple: el plugin debe registrar una tarea llamada`printSiteConfig`.</p> </div> <div class="sect2"> <h3 id="_2_1_el_test_primero_el_test_que_falla">2.1. El Test Primero (El Test que Falla)</h3> <div class="paragraph"> <p>Según el TDD, primero escribimos una prueba que verifica la existencia de esta tarea. En`SiteBakerPluginTest.kt`(nuestro archivo de prueba unitaria), añadimos:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers task`() { // Créer un projet de test en mémoire val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Vérifier que la tâche a bien été enregistrée assertNotNull(project.tasks.findByName("printSiteConfig")) }</code></pre> </div> </div> <div class="paragraph"> <p>Este test falla porque todavía no hemos escrito ningún código en nuestro plugin.</p> </div> </div> <div class="sect2"> <h3 id="_2_2_el_código_luego_hacer_pasar_la_prueba">2.2. El Código Luego (Hacer Pasar la Prueba)</h3> <div class="paragraph"> <p>Ahora escribimos el mínimo de código necesario en`SiteBakerPlugin.kt`para que la prueba pase:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer une tâche simple project.tasks.register("printSiteConfig") { task -> // ... la logique de la tâche viendra plus tard } } }</code></pre> </div> </div> <div class="paragraph"> <p>Reiniciamos las pruebas, y pasan. Nuestra primera funcionalidad está validada.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_segundo_ciclo_tdd_agregar_una_extensión_dsl">3. Segundo Ciclo TDD : Agregar una Extensión DSL</h2> <div class="sectionbody"> <div class="paragraph"> <p>La siguiente exigencia es permitir a los usuarios configurar nuestro plugin a través de un bloque DSL en su`build.gradle.kts`. Queremos un bloque`site { …​ }`donde se puede especificar una ruta de configuración.</p> </div> <div class="sect2"> <h3 id="_3_1_primero_el_test">3.1. Primero el test</h3> <div class="paragraph"> <p>Agregamos una prueba para verificar que la extensión`site`está bien registrada y se le puede asignar un valor.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers extension`() { val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Récupérer l'extension et lui affecter une valeur project.extensions .findByType(SiteExtension::class.java)!! .configPath .set("config.yml") // Vérifier que la valeur a bien été prise en compte assertEquals( "config.yml", project.extensions.findByType(SiteExtension::class.java)?.configPath?.get() ) }</code></pre> </div> </div> <div class="paragraph"> <p>Esta prueba falla porque ni la clase`SiteExtension`ni el registro de la extensión existen</p> </div> </div> <div class="sect2"> <h3 id="_3_2_el_código_luego">3.2. El código luego</h3> <div class="paragraph"> <p>Creamos la clase`SiteBakerExtension.kt`y actualizamos`SiteBakerPlugin.kt` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// SiteBakerExtension.kt open class SiteExtension @Inject constructor(objects: ObjectFactory) { val configPath: Property<String> = objects.property(String::class.java) } // SiteBakerPlugin.kt class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer l'extension val extension = project.extensions.create("site", SiteExtension::class.java) project.tasks.register("printSiteConfig") { task -> task.doLast { // On utilisera l'extension plus tard } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Las pruebas pasan de nuevo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_la_prueba_funcional_validar_la_integración">4. La prueba funcional: validar la integración</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ahora que las unidades están probadas, debemos asegurarnos de que todo funcione junto en una compilación real. Éste es el papel de la prueba funcional en`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="sect2"> <h3 id="_4_1_la_prueba_de_integración_crear_un_entorno_controlado">4.1. La prueba de integración: crear un entorno controlado</h3> <div class="paragraph"> <p>Este test simulará un proyecto real utilizando nuestro plugin. Para que sea fiable, debe ser<strong>hermético</strong>, es decir, no debe depender de archivos existentes en el sistema. Debe crear por sí mismo todas las condiciones necesarias para su ejecución.</p> </div> <div class="paragraph"> <p>El test, pues:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Crear un`build.gradle.kts`de prueba que utiliza nuestro plugin y su DSL.</p> </li> <li> <p><strong>Crear el archivo de configuración</strong>(<code>managed-jbake-context.yml</code>) que el plugin debe leer. Es un paso crucial para la robustez de la prueba.</p> </li> <li> <p>Ejecutar la tarea`printSiteConfig`via`GradleRunner`.</p> </li> <li> <p>Comprobar que la salida de la compilación es correcta.</p> </li> </ol> </div> <div class="paragraph"> <p>Al copiar o crear este archivo de configuración en cada ejecución, nos aseguramos que la prueba está<strong>reproducible</strong>y no depende de un estado externo. Esto asegura nuestras pruebas contra regresiones que podrían estar relacionadas con la lectura del archivo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `can run task with DSL`() { // 1. Créer un build.gradle.kts de test buildFile.writeText(""" plugins { id("com.cheroliv.site-baker") } site { configPath = "managed-jbake-context.yml" } """.trimIndent()) // 2. Créer le fichier de configuration pour un test contrôlé val configFile = File(projectDir, "managed-jbake-context.yml") configFile.writeText("site: { title: 'Mon Site de Test' }") // Contenu YAML simple // 3. Exécuter la build val runner = GradleRunner.create() runner.withPluginClasspath() runner.withArguments("printSiteConfig") runner.withProjectDir(projectDir) // Spécifier le répertoire du projet de test val result = runner.build() // 4. Vérifier la sortie assertTrue(result.output.contains("Site config path: managed-jbake-context.yml")) }</code></pre> </div> </div> <div class="paragraph"> <p>Este test fallará mientras la tarea`printSiteConfig`No utilizará realmente el valor de la extensión.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_finalizar_la_lógica">4.2. Finalizar la lógica</h3> <div class="paragraph"> <p>Estamos actualizando la tarea en`SiteBakerPlugin.kt`para que muestre el valor configurado :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.tasks.register("printSiteConfig") { task -> task.doLast { println("Site config path: ${extension.configPath.get()}") } }</code></pre> </div> </div> <div class="paragraph"> <p>Todas las pruebas, unitarias y funcionales, pasan ahora.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Siguiendo un enfoque TDD, hemos construido un plugin de forma incremental y segura. Cada pequeña funcionalidad se valida inmediatamente mediante una prueba, desde pruebas unitarias rápidas hasta pruebas funcionales que validan la integración completa.</p> </div> <div class="paragraph"> <p>Al asegurarnos de que nuestras pruebas funcionen<strong>herméticos</strong>— especialmente al crear mediante programación los archivos de configuración necesarios — estamos construyendo una red de seguridad extremadamente robusta. Esta rigurosidad nos protege eficazmente contra las regresiones y nos brinda una gran confianza para agregar funcionalidades más complejas más adelante, como el análisis del archivo de configuración YAML.</p> </div> <div class="paragraph"> <p>Esta base de pruebas sólidas es el activo más valioso para el mantenimiento y la evolución futura del plugin.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0089_creation_projet_plugin_gradle_post.html Tue, 23 Sep 2025 00:00:00 +0000 blog/2025/0089_creation_projet_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_paso_1_iniciar_el_asistente_de_proyecto">Paso 1: Iniciar el asistente de proyecto</a></li> <li><a href="#_paso_2_comprender_la_estructura_generada">Paso 2: Comprender la estructura generada</a> <ul class="sectlevel2"> <li><a href="#_archivos_y_carpetas_clave">Archivos y carpetas clave</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público objetivo: Desarrollador principiante a intermedio con Gradle.</div> <p>Empezar un nuevo proyecto de plugin Gradle puede parecer intimidante. Afortunadamente, Gradle proporciona un asistente interactivo potente, la tarea`init`, que genera una estructura de proyecto completa, limpia y lista para usar. Esta guía le mostrará cómo utilizar esta herramienta para crear una base de complemento sana, explicará su estructura y le mostrará cómo lanzar las primeras tareas de compilación.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_1_iniciar_el_asistente_de_proyecto">Paso 1: Iniciar el asistente de proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>El comando`gradle init`es el punto de partida. Lanza un asistente de línea de comandos que le hace una serie de preguntas para configurar el proyecto.</p> </div> <div class="paragraph"> <p>Abre tu terminal en una carpeta vacía y ejecuta :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle init</code></pre> </div> </div> <div class="paragraph"> <p>El asistente le guiará. Aquí están las opciones a elegir para un plugin Gradle escrito en Kotlin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Seleccione el tipo de proyecto para generar:</strong>Elige`Gradle plugin`.</p> </li> <li> <p><strong>Seleccione el lenguaje de implementación:</strong>Elige`Kotlin`.</p> </li> <li> <p><strong>Seleccionar DSL de script de construcción:</strong>elijan`Kotlin`.</p> </li> <li> <p><strong>Nombre del proyecto:</strong>Ingrese un nombre para su proyecto (ej:`site-baker`).</p> </li> <li> <p><strong>ID del plugin:</strong>Asigna un identificador único a tu plugin (ejemplo:`com.cheroliv.site-baker`).</p> </li> <li> <p><strong>Clase del complemento:</strong>Especifique el nombre de la clase de implementación (ej:`com.cheroliv.SiteBakerPlugin`).</p> </li> </ol> </div> <div class="paragraph"> <p>Una vez finalizado, Gradle genera un árbol de archivos completo.</p> </div> <div class="imageblock"> <div class="content"> <img src="init-gradle.svg" alt="init gradle" width="197" height="406"> </div> <div class="title">Figure 1. Diagrama del proceso de inicialización</div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_2_comprender_la_estructura_generada">Paso 2: Comprender la estructura generada</h2> <div class="sectionbody"> <div class="paragraph"> <p>El asistente crea una estructura de proyecto multi-módulos, separando el proyecto raíz del código fuente del plugin mismo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── plugin/ │ ├── build.gradle.kts │ └── src/ │ ├── main/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPlugin.kt │ ├── test/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPluginTest.kt │ └── functionalTest/ │ └── kotlin/ │ └── com/cheroliv/SiteBakerPluginFunctionalTest.kt └── settings.gradle.kts</code></pre> </div> </div> <div class="sect2"> <h3 id="_archivos_y_carpetas_clave">Archivos y carpetas clave</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts</code>: Este archivo en la raíz define los módulos incluidos en la compilación. Aquí, incluye el subproyecto`plugin`.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] ---- rootProject.name = "site-baker include("plugin") </think></p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0088_environnement_plugin_gradle_post.html Mon, 22 Sep 2025 00:00:00 +0000 blog/2025/0088_environnement_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_el_jdk_el_motor_de_gradle">El JDK : el motor de Gradle</a> <ul class="sectlevel2"> <li><a href="#_qué_versión_elegir">¿Qué versión elegir?</a></li> <li><a href="#_instalación_vía_sdkman_recomendado">Instalación vía SDKMAN! (Recomendado)</a> <ul class="sectlevel3"> <li><a href="#_instalar_sdkman"><strong>Instalar SDKMAN!</strong></a></li> <li><a href="#_instalar_una_versión_del_jdk"><strong>Instalar una versión del JDK</strong></a></li> <li><a href="#_verificar_la_instalación"><strong>Verificar la instalación</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_2_el_ide_intellij_idea">2. El IDE : IntelliJ IDEA</a></li> <li><a href="#_3_gradle_la_herramienta_de_build">3. Gradle : La herramienta de build</a> <ul class="sectlevel2"> <li><a href="#_instalación_vía_sdkman">Instalación vía SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_instalar_gradle">Instalar Gradle</a></li> <li><a href="#_comprobar_la_instalación">Comprobar la instalación</a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_el_generador_de_sitio_estático">4. JBake: El generador de sitio estático</a> <ul class="sectlevel2"> <li><a href="#_instalación_vía_sdkman_2">Instalación vía SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_instalar_jbake"><strong>Instalar JBake</strong></a></li> <li><a href="#_verificar_la_instalación_2">Verificar la instalación</a></li> </ul> </li> </ul> </li> <li><a href="#_5_el_gradle_wrapper_la_práctica_recomendada_absoluta">5. El Gradle Wrapper: la práctica recomendada absoluta</a></li> <li><a href="#_6_docker_y_portainer_para_builds_reproducibles_opcional">6. Docker y Portainer: Para builds reproducibles (opcional)</a> <ul class="sectlevel2"> <li><a href="#_instalación_de_docker_engine">Instalación de Docker Engine</a> <ul class="sectlevel3"> <li><a href="#_instalar_docker_vía_el_script_oficial"><strong>Instalar Docker vía el script oficial :</strong></a></li> <li><a href="#_gestionar_docker_sin_sudo_recomendado"><strong>Gestionar Docker sin <code>sudo</code> (recomendado) :</strong></a></li> </ul> </li> <li><a href="#_gestionar_docker_con_portainer_gui">Gestionar Docker con Portainer (GUI)</a> <ul class="sectlevel3"> <li><a href="#_crear_un_volumen_para_los_datos_de_portainer">Crear un volumen para los datos de Portainer :</a></li> <li><a href="#_iniciar_el_contenedor_portainer">Iniciar el contenedor Portainer:</a></li> </ul> </li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público objetivo: Desarrolladores que desean iniciar la creación de plugins Gradle.</div> <p>Para desarrollar plugins Gradle eficientemente, un entorno de desarrollo bien configurado es indispensable. Un buen setup le hará ganar tiempo, reducirá las frustraciones y garantizará la coherencia de sus builds.</p> </div> <div class="olist arabic"> <div class="title">Este guía se centra en cuatro pilares esenciales:</div> <ol class="arabic"> <li> <p>Le <strong>JDK</strong>(Java Development Kit), ya que Gradle y JBake se ejecutan en la JVM.</p> </li> <li> <p>Un <strong>Entorno de desarrollo integrado</strong>moderno (IntelliJ IDEA) con buen soporte de Kotlin y Gradle.</p> </li> <li> <p><strong>Gradle</strong>él mismo, para inicializar los proyectos</p> </li> <li> <p><strong>JBake</strong>, el motor de nuestro sitio estático.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/gradle-env.svg" alt="gradle env" width="1582" height="5696"> </div> <div class="title">Figure 1. Componentes del entorno de desarrollo</div> </div> </div> </div> <div class="sect1"> <h2 id="_el_jdk_el_motor_de_gradle">El JDK : el motor de Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle es una aplicación que se ejecuta en la máquina virtual Java (JVM). Por lo tanto, la instalación de un JDK es un requisito absoluto.</p> </div> <div class="sect2"> <h3 id="_qué_versión_elegir">¿Qué versión elegir?</h3> <div class="paragraph"> <p>Se recomienda utilizar una versión LTS (Long-Term Support) de Java. En este momento,<strong>JDK 17</strong> ou <strong>JDK 21</strong>son excelentes opciones</p> </div> </div> <div class="sect2"> <h3 id="_instalación_vía_sdkman_recomendado">Instalación vía SDKMAN! (Recomendado)</h3> <div class="paragraph"> <p>SDKMAN! es una herramienta formidable para gestionar las versiones de muchos SDK, incluyendo Java y Gradle.</p> </div> <div class="sect3"> <h4 id="_instalar_sdkman"><strong>Instalar SDKMAN!</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_instalar_una_versión_del_jdk"><strong>Instalar una versión del JDK</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Pour lister les versions de Java disponibles sdk list java # Pour installer Java 17 (par exemple, la distribution Temurin) sdk install java 17.0.8-tem</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verificar_la_instalación"><strong>Verificar la instalación</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">java -version</code></pre> </div> </div> <div class="paragraph"> <p>Deberías ver la versión que acabas de instalar aparecer.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_el_ide_intellij_idea">2. El IDE : IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para el desarrollo de plugins de Gradle con el DSL de Kotlin,<strong>IntelliJ IDEA</strong>es la herramienta de elección Su integración con Gradle y Kotlin es inigualable.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Edición Comunidad :</strong>Gratuita y ampliamente suficiente para comenzar.</p> </li> <li> <p><strong>Edición Definitiva :</strong>De pago, ofrece funcionalidades avanzadas para el desarrollo web y base de datos.</p> </li> </ul> </div> <div class="paragraph"> <p>Descarga la versión que más te convenga desde el sitio de JetBrains: <a href="https://www.jetbrains.com/idea/download/" class="bare">https://www.jetbrains.com/idea/download/</a></p> </div> <div class="paragraph"> <p>El IDE detectará automáticamente sus archivos`build.gradle.kts` et <code>settings.gradle.kts</code>, ofreciendo una autocompletación potente, la navegación en el código y herramientas de depuración integradas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle_la_herramienta_de_build">3. Gradle : La herramienta de build</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aunque cada proyecto utilizará su propia versión de Gradle a través del Gradle Wrapper, es útil tener una instalación global de Gradle para tareas como la inicialización de nuevos proyectos (<code>gradle init</code>).</p> </div> <div class="sect2"> <h3 id="_instalación_vía_sdkman">Instalación vía SDKMAN!</h3> <div class="paragraph"> <p>Al igual que con el JDK, SDKMAN! simplifica la instalación de Gradle.</p> </div> <div class="sect3"> <h4 id="_instalar_gradle">Instalar Gradle</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install gradle</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_comprobar_la_instalación">Comprobar la instalación</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle -v</code></pre> </div> </div> <div class="paragraph"> <p>Este comando mostrará las versiones de Gradle, Kotlin, Groovy y del JDK utilizadas.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_el_generador_de_sitio_estático">4. JBake: El generador de sitio estático</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake es la herramienta que utilizaremos para transformar nuestros archivos fuente (como este) en un sitio web estático. Tener una instalación local es práctico para previsualizar los cambios.</p> </div> <div class="sect2"> <h3 id="_instalación_vía_sdkman_2">Instalación vía SDKMAN!</h3> <div class="paragraph"> <p>Como con las demás herramientas, SDKMAN! es el método más simple.</p> </div> <div class="sect3"> <h4 id="_instalar_jbake"><strong>Instalar JBake</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install jbake</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verificar_la_instalación_2">Verificar la instalación</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jbake -v</code></pre> </div> </div> <div class="paragraph"> <p>Este comando mostrará la versión de JBake y la información del entorno Java que utiliza.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_el_gradle_wrapper_la_práctica_recomendada_absoluta">5. El Gradle Wrapper: la práctica recomendada absoluta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una vez creado tu proyecto (lo que veremos en el siguiente artículo), ya no deberías usar el comando global`gradle`. En su lugar, usted utilizará el<strong>Gradle Wrapper</strong>(<code>./gradlew</code>), un script incluido en su proyecto.</p> </div> <div class="paragraph"> <p>¿Por qué?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Reproducibilidad :</strong>El Wrapper garantiza que cada persona que trabaja en el proyecto (incluido su servidor de CI/CD) utiliza exactamente la<strong>mismo versión de Gradle</strong>, eliminando así los errores de compilación debido a entornos diferentes.</p> </li> <li> <p><strong>Simplicidad :</strong>No es necesario instalar Gradle manualmente para contribuir a un proyecto.</p> </li> </ul> </div> <div class="paragraph"> <p>Basta con clonar el repositorio y ejecutar`./gradlew`.</p> </div> <div class="paragraph"> <p>Una orden típica se verá así :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Ne pas faire : gradle build # À faire : ./gradlew build</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_6_docker_y_portainer_para_builds_reproducibles_opcional">6. Docker y Portainer: Para builds reproducibles (opcional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aunque no estén estrictamente necesarios para escribir un plugin, Docker y Portainer son herramientas DevOps modernas que facilitan en gran medida la creación de builds reproducibles y la gestión de su entorno.</p> </div> <div class="sect2"> <h3 id="_instalación_de_docker_engine">Instalación de Docker Engine</h3> <div class="paragraph"> <p>Docker le permite empaquetar su aplicación y sus dependencias en un contenedor.</p> </div> <div class="sect3"> <h4 id="_instalar_docker_vía_el_script_oficial"><strong>Instalar Docker vía el script oficial :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_gestionar_docker_sin_sudo_recomendado"><strong>Gestionar Docker sin <code>sudo</code> (recomendado) :</strong></h4> <div class="paragraph"> <p>Agrega tu usuario al grupo`docker`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo usod -aG docker $USER</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run hello-world</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_gestionar_docker_con_portainer_gui">Gestionar Docker con Portainer (GUI)</h3> <div class="paragraph"> <p>Portainer es una interfaz web ligera para administrar sus contenedores Docker.</p> </div> <div class="sect3"> <h4 id="_crear_un_volumen_para_los_datos_de_portainer">Crear un volumen para los datos de Portainer :</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker volume create portainer_data</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_iniciar_el_contenedor_portainer">Iniciar el contenedor Portainer:</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest</code></pre> </div> </div> <div class="paragraph"> <p>Ahora puede acceder a la interfaz de Portainer en`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>¡Tu entorno ya está listo! Dispones de un JDK, del IDE más adecuado, de Gradle y de JBake. Con la adición de Docker, también está preparado para crear builds contenedorizados y reproducibles. Esta base sólida le permitirá concentrarse en lo esencial: el desarrollo de plugins potentes y útiles.</p> </div> <div class="paragraph"> <p>En el próximo artículo, utilizaremos el comando`gradle init`para generar la estructura de nuestro primer proyecto de plugin.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0087_pypi_cicd_part_3_post.html Sat, 19 Jul 2025 00:00:00 +0000 blog/2025/0087_pypi_cicd_part_3_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_integración_con_poetry">Integración con Poetry</a> <ul class="sectlevel2"> <li><a href="#_instalación_de_poetry">Instalación de Poetry</a></li> <li><a href="#_inicialización_del_proyecto">Inicialización del proyecto</a></li> <li><a href="#_adición_e_instalación_de_dependencias">Adición e instalación de dependencias</a></li> <li><a href="#_publicación_con_poetry">Publicación con Poetry</a></li> </ul> </li> <li><a href="#_builds_reproducibles_con_docker">Builds reproducibles con Docker</a> <ul class="sectlevel2"> <li><a href="#_ejemplo_de_dockerfile">Ejemplo de Dockerfile</a></li> <li><a href="#_integración_en_github_actions">Integración en GitHub Actions</a></li> </ul> </li> <li><a href="#_publicación_condicional">Publicación condicional</a></li> <li><a href="#_automatización_de_las_dependencias_con_renovate_y_dependabot">Automatización de las dependencias con Renovate y Dependabot</a> <ul class="sectlevel2"> <li><a href="#_dependabot">Dependabot</a></li> <li><a href="#_renovar">Renovar</a></li> </ul> </li> <li><a href="#_diagramas_plantuml">Diagramas PlantUML</a> <ul class="sectlevel2"> <li><a href="#_caso_de_uso_cicd_avanzado">Caso de Uso – CI/CD avanzado</a></li> <li><a href="#_secuencia_publicación_condicional">Secuencia – Publicación condicional</a></li> <li><a href="#_estados_pipeline_cicd">Estados – Pipeline CI/CD</a></li> <li><a href="#_despliegue_arquitectura_cicd">Despliegue – Arquitectura CI/CD</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>En las dos primeras partes de esta serie, hemos : - Establecido un pipeline CI/CD funcional para una aplicación Python con GitHub Actions y PyPI. - Industrializado este pipeline con pruebas multi-versión, una publicación progresiva a través de Test PyPI, y herramientas de calidad y seguridad.</p> </div> <div class="paragraph"> <p>En esta tercera parte, vamos a ir<strong>más allá de la simple publicación en PyPI</strong>para construir una cadena de CI/CD completa, robusta y profesional con: - <strong>Poesía</strong>para un empaquetado moderno y una gestión optimizada de las dependencias. - <strong>Docker</strong>Para crear compilaciones reproducibles y multiplataforma. - <strong>Publicación condicional</strong>para gestionar escenarios como los candidatos de lanzamiento. - <strong>Herramientas de automatización</strong>(Renovate, Dependabot) para mantener el pipeline actualizado sin esfuerzo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integración_con_poetry">Integración con Poetry</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry reemplaza las antiguas herramientas de empaquetado (setup.py, requirements.txt) al centralizar la gestión de las dependencias y del build en`pyproject.toml`.</p> </div> <div class="sect2"> <h3 id="_instalación_de_poetry">Instalación de Poetry</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Installer Poetry curl -sSL https://install.python-poetry.org | python3 - # Vérifier la version poetry --version</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_inicialización_del_proyecto">Inicialización del proyecto</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Initialiser un nouveau projet avec Poetry poetry init # Suivre l'assistant pour renseigner : nom, version, description, licence, dépendances.</code></pre> </div> </div> <div class="paragraph"> <p>Esto genera un archivo`pyproject.toml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[tool.poetry] name = "playlist-downloader" version = "0.1.0" description = "CLI tool for managing YouTube playlists" authors = ["Christophe Hérolivier <cheroliv@example.com>"] [tool.poetry.dependencies] python = ">=3.8" typer = "^0.9.0" yt-dlp = "^2023.7.6" google-api-python-client = "^2.0.0" google-auth-oauthlib = "^1.0.0" [tool.poetry.group.dev.dependencies] pytest = "^7.0" mypy = "^1.0" bandit = "^1.7" safety = "^2.3" black = "^23.0" ruff = "^0.1"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_adición_e_instalación_de_dependencias">Adición e instalación de dependencias</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell">poetry add typer yt-dlp google-api-python-client google-auth-oauthlib poetry add --group dev pytest mypy black bandit safety ruff</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_publicación_con_poetry">Publicación con Poetry</h3> <div class="paragraph"> <p>Poetry gestiona nativamente la publicación:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Publication sur Test PyPI poetry publish --build --repository test-pypi # Publication sur PyPI poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>Este comando utiliza automáticamente la información presente en`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_builds_reproducibles_con_docker">Builds reproducibles con Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para asegurar ejecuciones idénticas en desarrollo, CI/CD y producción, Docker se integra perfectamente con Poetry.</p> </div> <div class="sect2"> <h3 id="_ejemplo_de_dockerfile">Ejemplo de Dockerfile</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="dockerfile">FROM python:3.11-slim WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry RUN poetry install --no-root --only main COPY . . CMD ["poetry", "run", "python", "cli.py"]</code></pre> </div> </div> <div class="paragraph"> <p>Esto garantiza: - Un entorno Python congelado. - Dependencias bloqueadas via`poetry.lock`. - Una imagen ejecutable en cualquier sistema que admita Docker.</p> </div> </div> <div class="sect2"> <h3 id="_integración_en_github_actions">Integración en GitHub Actions</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Docker Build on: push: branches: [main] jobs: build-docker: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Docker image run: docker build -t ghcr.io/${{ github.repository }}:latest . - name: Push Docker image run: docker push ghcr.io/${{ github.repository }}:latest</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_publicación_condicional">Publicación condicional</h2> <div class="sectionbody"> <div class="paragraph"> <p>En un pipeline profesional, es necesario poder publicar solo en algunos casos : Candidatos de versión hacia Test PyPI. - Versiones estables a PyPI. - Construcciones de Docker desencadenadas únicamente para`main`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">- name: Publish to Test PyPI if: contains(github.ref, '-rc') run: poetry publish --build --repository test-pypi - name: Publish to PyPI if: startsWith(github.ref, 'refs/tags/v') run: poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>Este enfoque evita las publicaciones accidentales.</p> </div> </div> </div> <div class="sect1"> <h2 id="_automatización_de_las_dependencias_con_renovate_y_dependabot">Automatización de las dependencias con Renovate y Dependabot</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para evitar que sus dependencias se vuelvan obsoletas, incorpore herramientas de actualización automática.</p> </div> <div class="sect2"> <h3 id="_dependabot">Dependabot</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "weekly" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"</code></pre> </div> </div> <div class="paragraph"> <p>Dependabot abre PR cada semana para actualizar las dependencias de Python y GitHub Actions.</p> </div> </div> <div class="sect2"> <h3 id="_renovar">Renovar</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="json">{ "extends": ["config:base"], "packageRules": [ { "matchManagers": ["pip"], "groupName": "python-dependencies", "schedule": ["before 6am on monday"] } ] }</code></pre> </div> </div> <div class="paragraph"> <p>Renovate permite un control más fino: agrupamiento de dependencias, planificación y reglas avanzadas.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramas_plantuml">Diagramas PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_caso_de_uso_cicd_avanzado">Caso de Uso – CI/CD avanzado</h3> <div class="imageblock"> <div class="content"> <img src="images/usecase-cicd.svg" alt="usecase cicd" width="841" height="317"> </div> </div> </div> <div class="sect2"> <h3 id="_secuencia_publicación_condicional">Secuencia – Publicación condicional</h3> <div class="imageblock"> <div class="content"> <img src="images/sequence-cicd.svg" alt="sequence cicd" width="275" height="571"> </div> </div> </div> <div class="sect2"> <h3 id="_estados_pipeline_cicd">Estados – Pipeline CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/states-cicd.svg" alt="states cicd" width="284" height="608"> </div> </div> </div> <div class="sect2"> <h3 id="_despliegue_arquitectura_cicd">Despliegue – Arquitectura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/deployment-cicd.svg" alt="deployment cicd" width="1637" height="5604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>En esta tercera parte, hemos visto cómo : - Modernizar el empaquetado de Python con Poetry. - Garantizar compilaciones reproducibles mediante Docker. - Configurar una publicación condicional. - Automatizar la actualización de las dependencias.</p> </div> <div class="paragraph"> <p>Ahora dispone de un pipeline CI/CD<strong>completo, industrializado y seguro</strong>, listo para evolucionar con sus proyectos.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0086_pypi_cicd_part_2_post.html Fri, 18 Jul 2025 00:00:00 +0000 blog/2025/0086_pypi_cicd_part_2_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_arquitectura_del_pipeline_cicd">Arquitectura del Pipeline CI/CD</a></li> <li><a href="#_estructura_del_proyecto">Estructura del Proyecto</a></li> <li><a href="#_configuración_del_paquete_con_pyproject_toml">Configuración del paquete con pyproject.toml</a></li> <li><a href="#_flujo_de_trabajo_de_cicd_pruebas_y_calidad">Flujo de trabajo de CI/CD - Pruebas y Calidad</a></li> <li><a href="#_workflow_de_lanzamiento_y_despliegue">Workflow de Lanzamiento y Despliegue</a></li> <li><a href="#_diagramas_de_arquitectura">Diagramas de Arquitectura</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_secuencia_proceso_de_release">Diagrama de Secuencia - Proceso de Release</a></li> <li><a href="#_diagrama_de_estados_ciclo_de_vida_del_paquete">Diagrama de Estados - Ciclo de Vida del Paquete</a></li> <li><a href="#_diagrama_de_despliegue_infraestructura_cicd">Diagrama de despliegue - infraestructura CI/CD</a></li> </ul> </li> <li><a href="#_objetos_y_modelos_del_pipeline">Objetos y Modelos del Pipeline</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_clases_modelos_cicd">Diagrama de Clases - Modelos CI/CD</a></li> </ul> </li> <li><a href="#_configuración_de_secretos">Configuración de secretos</a> <ul class="sectlevel2"> <li><a href="#_secretos_github_actions">Secretos GitHub Actions</a></li> <li><a href="#_generación_de_los_tokens_pypi">Generación de los Tokens PyPI</a></li> </ul> </li> <li><a href="#_scripts_de_desarrollo_local">Scripts de Desarrollo Local</a> <ul class="sectlevel2"> <li><a href="#_makefile">Makefile</a></li> <li><a href="#_guion_de_versión">Guion de Versión</a></li> </ul> </li> <li><a href="#_buenas_prácticas_y_recomendaciones">Buenas Prácticas y Recomendaciones</a> <ul class="sectlevel2"> <li><a href="#_versionamiento_semántico">Versionamiento semántico</a></li> <li><a href="#_estrategia_de_ramificación">Estrategia de Ramificación</a></li> <li><a href="#_pruebas_y_cobertura">Pruebas y cobertura</a></li> <li><a href="#_seguridad">Seguridad</a></li> </ul> </li> <li><a href="#_monitoreo_y_observabilidad">Monitoreo y Observabilidad</a> <ul class="sectlevel2"> <li><a href="#_métricas_de_pipeline">Métricas de pipeline</a></li> <li><a href="#_notificaciones">Notificaciones</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_recursos_complementarios">Recursos Complementarios</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objetivo: Convertir un pipeline simple en un pipeline industrial robusto, respetando los estándares modernos de empaquetado e ingeniería de software.</div> <p>En la primera parte de esta serie, hemos construido un pipeline CI/CD sencillo pero eficaz para automatizar las pruebas y la publicación de un paquete Python en PyPI.</p> </div> <div class="paragraph"> <p>Ahora es momento de profesionalizar este pipeline. En esta segunda parte, vamos a:</p> </div> <div class="ulist"> <ul> <li> <p>Migrar al estándar moderno pyproject.toml,</p> </li> <li> <p>Agregar herramientas de calidad y seguridad (Black, Mypy, Bandit, Safety),</p> </li> <li> <p>Implementar pruebas multi-versiones,</p> </li> <li> <p>Integrar un despliegue progresivo a través de Test PyPI,</p> </li> <li> <p>Automatizar el versioning y mejorar la vigilancia del pipeline.</p> </li> </ul> </div> <div class="paragraph"> <p>Prepárate para pasar de un pipeline funcional a una infraestructura CI/CD profesional.</p> </div> <div class="paragraph"> <p>Desplegar una aplicación Python en PyPI requiere un pipeline CI/CD robusto que automatice las pruebas, la construcción y la publicación de los paquetes. Este artículo detalla la configuración de un pipeline completo utilizando GitHub Actions para una aplicación CLI de Python, apoyándose en las buenas prácticas del ecosistema Python moderno.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_del_pipeline_cicd">Arquitectura del Pipeline CI/CD</h2> <div class="sectionbody"> <div class="paragraph"> <p>El pipeline que vamos a construir sigue un enfoque en varias etapas:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-0f5f77e4947050ff2368ae8f1cdf0f74.png" alt="Diagram" width="1034" height="604"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estructura_del_proyecto">Estructura del Proyecto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una aplicación CLI de Python preparada para la distribución debe respetar una estructura estandarizada:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">playlist-downloader/ ├── .github/ │ └── workflows/ │ ├── ci.yml │ ├── release.yml │ └── security.yml ├── src/ │ └── playlist_downloader/ │ ├── __init__.py │ ├── cli.py │ ├── core/ │ └── adapters/ ├── tests/ │ ├── unit/ │ ├── integration/ │ └── conftest.py ├── docs/ ├── pyproject.toml ├── requirements.txt ├── requirements-dev.txt ├── MANIFEST.in ├── README.md ├── LICENSE └── CHANGELOG.md</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_del_paquete_con_pyproject_toml">Configuración del paquete con pyproject.toml</h2> <div class="sectionbody"> <div class="paragraph"> <p>El archivo`pyproject.toml`es el estándar moderno para configurar los paquetes de Python:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"] build-backend = "setuptools.build_meta" [project] name = "playlist-downloader" authors = [ {name = "Christophe Hérolivier", email = "cheroliv@example.com"}, ] description = "CLI tool for YouTube playlist management" readme = "README.md" requires-python = ">=3.8" keywords = ["youtube", "playlist", "cli", "downloader"] license = {text = "MIT"} classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Multimedia :: Sound/Audio", "Topic :: Utilities", ] dependencies = [ "typer>=0.9.0", "yt-dlp>=2023.7.6", "google-api-python-client>=2.0.0", "google-auth-oauthlib>=1.0.0", "pyyaml>=6.0", "rich>=13.0.0", ] dynamic = ["version"] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", "black>=23.0.0", "flake8>=6.0.0", "mypy>=1.0.0", "pre-commit>=3.0.0", "tox>=4.0.0", ] test = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", ] [project.urls] Homepage = "https://github.com/cheroliv/playlist-downloader" Documentation = "https://github.com/cheroliv/playlist-downloader#readme" Repository = "https://github.com/cheroliv/playlist-downloader.git" "Bug Tracker" = "https://github.com/cheroliv/playlist-downloader/issues" [project.scripts] playlist-downloader = "playlist_downloader.cli:main" [tool.setuptools_scm] write_to = "src/playlist_downloader/_version.py" [tool.setuptools.packages.find] where = ["src"] [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--cov=src/playlist_downloader", "--cov-report=html", "--cov-report=term-missing", "--cov-fail-under=85", ] [tool.black] line-length = 88 target-version = ['py38'] include = '\.pyi?$' extend-exclude = ''' /( \.eggs | \.git | \.hg | \.mypy_cache | \.tox | \.venv | _build | buck-out | build | dist )/ ''' [tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true disallow_incomplete_defs = true check_untyped_defs = true disallow_untyped_decorators = true no_implicit_optional = true warn_redundant_casts = true warn_unused_ignores = true warn_no_return = true warn_unreachable = true strict_equality = true [[tool.mypy.overrides]] module = [ "yt_dlp.*", "googleapiclient.*", "google_auth_oauthlib.*", ] ignore_missing_imports = true</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_flujo_de_trabajo_de_cicd_pruebas_y_calidad">Flujo de trabajo de CI/CD - Pruebas y Calidad</h2> <div class="sectionbody"> <div class="paragraph"> <p>El flujo de trabajo principal (<code>ci.yml</code>) ejecuta las pruebas en varias versiones de Python:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.8", "3.9", "3.10", "3.11"] steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Cache dependencies uses: actions/cache@v3 with: path: | ~/.cache/pip ~/.cache/pre-commit key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e ".[dev]" - name: Lint with flake8 run: | flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics - name: Check code formatting with Black run: black --check src tests - name: Type checking with mypy run: mypy src - name: Run tests with pytest run: | pytest tests/ -v --cov=src/playlist_downloader \ --cov-report=xml --cov-report=term-missing - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 if: matrix.python-version == '3.11' with: file: ./coverage.xml flags: unittests name: codecov-umbrella security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip pip install bandit[toml] safety - name: Run security checks with bandit run: bandit -r src/ -f json -o bandit-report.json - name: Check dependencies with safety run: safety check --json --output safety-report.json - name: Upload security reports uses: actions/upload-artifact@v3 if: always() with: name: security-reports path: | bandit-report.json safety-report.json build: needs: [test, security] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install build dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package with twine run: twine check dist/* - name: Upload build artifacts uses: actions/upload-artifact@v3 with: name: dist path: dist/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workflow_de_lanzamiento_y_despliegue">Workflow de Lanzamiento y Despliegue</h2> <div class="sectionbody"> <div class="paragraph"> <p>El flujo de trabajo de release (<code>release.yml</code>) gestiona la publicación automática en PyPI :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Release on: push: tags: - 'v*.*.*' workflow_dispatch: inputs: environment: description: 'Deployment environment' required: true default: 'test' type: choice options: - test - production env: PYTHON_VERSION: "3.11" jobs: release: runs-on: ubuntu-latest environment: name: ${{ github.event.inputs.environment || (startsWith(github.ref, 'refs/tags/') && 'production' || 'test') }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package run: twine check dist/* - name: Publish to Test PyPI if: github.event.inputs.environment == 'test' || (startsWith(github.ref, 'refs/tags/') && contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }} run: | twine upload --repository testpypi dist/* - name: Publish to PyPI if: github.event.inputs.environment == 'production' || (startsWith(github.ref, 'refs/tags/') && !contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | twine upload dist/* - name: Create GitHub Release if: startsWith(github.ref, 'refs/tags/') uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} draft: false prerelease: ${{ contains(github.ref, 'rc') }} post-release: needs: release runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Test installation from PyPI run: | sleep 60 # Attendre la propagation sur PyPI pip install playlist-downloader playlist-downloader --version - name: Update documentation run: | # Script pour mettre à jour la documentation echo "Documentation updated for version ${GITHUB_REF#refs/tags/}"</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramas_de_arquitectura">Diagramas de Arquitectura</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_secuencia_proceso_de_release">Diagrama de Secuencia - Proceso de Release</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-df1313394dc86969412cbb60e962e918.png" alt="Diagram" width="962" height="832"> </div> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_estados_ciclo_de_vida_del_paquete">Diagrama de Estados - Ciclo de Vida del Paquete</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-0225d237d087fae3ece6b0a10f49d0a0.png" alt="Diagram" width="525" height="740"> </div> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_despliegue_infraestructura_cicd">Diagrama de despliegue - infraestructura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-2a52c725f52d5cc665332961acdb6596.png" alt="Diagram" width="707" height="604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_objetos_y_modelos_del_pipeline">Objetos y Modelos del Pipeline</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_clases_modelos_cicd">Diagrama de Clases - Modelos CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-7760801e42cae593d421e964eda942e6.png" alt="Diagram" width="814" height="635"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_de_secretos">Configuración de secretos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que el pipeline funcione, debe configurar los siguientes secretos en GitHub :</p> </div> <div class="sect2"> <h3 id="_secretos_github_actions">Secretos GitHub Actions</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># Dans Settings > Secrets and variables > Actions # Token PyPI pour la production PYPI_API_TOKEN=pypi-... # Token Test PyPI pour les pré-releases TEST_PYPI_API_TOKEN=pypi-... # Token GitHub pour créer les releases GITHUB_TOKEN=(automatiquement fourni) # Token Codecov (optionnel) CODECOV_TOKEN=...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_generación_de_los_tokens_pypi">Generación de los Tokens PyPI</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># 1. Créer un compte sur PyPI et Test PyPI # 2. Aller dans Account Settings > API tokens # 3. Créer un token avec scope "Entire account" ou spécifique au projet # 4. Format du token : pypi-AgEIcHlwaS5vcmc...</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scripts_de_desarrollo_local">Scripts de Desarrollo Local</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para facilitar el desarrollo, cree scripts de utilidad:</p> </div> <div class="sect2"> <h3 id="_makefile">Makefile</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="makefile">.PHONY: install test lint format security build clean release-test release-prod install: pip install -e ".[dev]" test: pytest tests/ -v --cov=src/playlist_downloader lint: flake8 src tests mypy src format: black src tests security: bandit -r src/ safety check build: python -m build twine check dist/* clean: rm -rf build/ dist/ *.egg-info/ find . -type d -name __pycache__ -delete find . -name "*.pyc" -delete release-test: clean build twine upload --repository testpypi dist/* release-prod: clean build twine upload dist/* pre-commit: format lint test security @echo "✅ Prêt pour commit"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_guion_de_versión">Guion de Versión</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="python">#!/usr/bin/env python3 """Script pour gérer les versions du projet.""" import sys import subprocess from pathlib import Path def get_current_version(): """Récupère la version actuelle depuis git.""" try: result = subprocess.run( ["git", "describe", "--tags", "--abbrev=0"], capture_output=True, text=True, check=True ) return result.stdout.strip() except subprocess.CalledProcessError: return "0.0.0" def create_version_tag(version, message=None): """Crée un tag de version.""" if not version.startswith('v'): version = f'v{version}' tag_message = message or f"Release {version}" subprocess.run(["git", "tag", "-a", version, "-m", tag_message], check=True) print(f"✅ Tag {version} créé") # Push le tag subprocess.run(["git", "push", "origin", version], check=True) print(f"✅ Tag {version} poussé vers origin") if __name__ == "__main__": if len(sys.argv) < 2: current = get_current_version() print(f"Version actuelle: {current}") print("Usage: python version.py <new_version> [message]") sys.exit(1) new_version = sys.argv[1] message = sys.argv[2] if len(sys.argv) > 2 else None create_version_tag(new_version, message)</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas_y_recomendaciones">Buenas Prácticas y Recomendaciones</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_versionamiento_semántico">Versionamiento semántico</h3> <div class="paragraph"> <p>Utilice el versionado semántico (SemVer):</p> </div> <div class="ulist"> <ul> <li> <p><code>MAJOR.MINOR.PATCH</code> (ex: 1.2.3)</p> </li> <li> <p><code>MAJOR</code>: cambios incompatibles</p> </li> <li> <p>`MINOR`nuevas funcionalidades compatibles</p> </li> <li> <p><code>PATCH</code>: correcciones de errores compatibles</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_estrategia_de_ramificación">Estrategia de Ramificación</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">main ──●──●──●──●──●────●── (releases stables) / / / develop ──●──●──●──●──●──●──●──●── (développement) / / / feature/xxx ●──●──●──●──●──/ (fonctionnalités)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_pruebas_y_cobertura">Pruebas y cobertura</h3> <div class="ulist"> <ul> <li> <p>Cobertura mínima de código: 85%</p> </li> <li> <p>Pruebas unitarias para la lógica de negocio</p> </li> <li> <p>Pruebas de integración para los adaptadores</p> </li> <li> <p>Pruebas de extremo a extremo para las CLI</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_seguridad">Seguridad</h3> <div class="ulist"> <ul> <li> <p>Escaneo automático de dependencias (Safety)</p> </li> <li> <p>Análisis estático del código (Bandit)</p> </li> <li> <p>Secretos nunca en el código</p> </li> <li> <p>Utilización de tokens específicos de PyPI</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoreo_y_observabilidad">Monitoreo y Observabilidad</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_métricas_de_pipeline">Métricas de pipeline</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># .github/workflows/metrics.yml name: Pipeline Metrics on: workflow_run: workflows: ["CI", "Release"] types: [completed] jobs: metrics: runs-on: ubuntu-latest steps: - name: Collect metrics run: | echo "Pipeline: ${{ github.event.workflow_run.name }}" echo "Status: ${{ github.event.workflow_run.conclusion }}" echo "Duration: ${{ github.event.workflow_run.updated_at - github.event.workflow_run.created_at }}" # Envoyer vers système de monitoring</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_notificaciones">Notificaciones</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># Ajout dans les workflows pour notifications - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: failure text: "❌ Pipeline failed for ${{ github.repository }}" env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este pipeline CI/CD completo para Python ofrece :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Automatización completa</strong>: de la validación del código a la publicación</p> </li> <li> <p><strong>Seguridad</strong>: exploraciones automáticas y gestión segura de secretos</p> </li> <li> <p><strong>Calidad</strong>: pruebas multi-versiones, linting y cobertura de código</p> </li> <li> <p><strong>fiabilidad</strong>: despliegue progresivo via Test PyPI</p> </li> <li> <p><strong>Trazabilidad</strong>: artefactos, informes y lanzamientos de GitHub</p> </li> </ul> </div> <div class="paragraph"> <p>La adopción de estas prácticas garantiza un proceso de entrega robusto y profesional para sus aplicaciones Python CLI, facilitando el mantenimiento y la evolución de sus proyectos a largo plazo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_recursos_complementarios">Recursos Complementarios</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://packaging.python.org/">Guía del usuario de empaquetado de Python</a></p> </li> <li> <p><a href="https://docs.github.com/en/actions">Documentación de GitHub Actions</a></p> </li> <li> <p><a href="https://pypi.org/help/">Documentación de ayuda de PyPI</a></p> </li> <li> <p><a href="https://semver.org/">Especificación de Versionado Semántico</a></p> </li> <li> <p><a href="https://keepachangelog.com/">Mantén un registro de cambios</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2025/0085_pypi_cicd_part_1_post.html Thu, 17 Jul 2025 00:00:00 +0000 blog/2025/0085_pypi_cicd_part_1_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_arquitectura_del_pipeline">Arquitectura del Pipeline</a></li> <li><a href="#_configuración_del_pipeline_de_integración_continua_ci">Configuración del Pipeline de Integración Continua (CI)</a> <ul class="sectlevel2"> <li><a href="#_estructura_del_flujo_de_trabajo_ci">Estructura del flujo de trabajo CI</a></li> <li><a href="#_análisis_de_los_pasos_ci">Análisis de los pasos CI</a> <ul class="sectlevel3"> <li><a href="#_desencadenadores_on">desencadenadores (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objetivo : Acompañar al lector en la configuración de un pipeline CI/CD minimalista pero funcional para una aplicación Python, con un despliegue automático en PyPI.</div> <p>La automatización de los procesos de desarrollo se ha vuelto indispensable en los proyectos modernos. Un pipeline CI/CD bien diseñado permite no solo detectar las regresiones temprano en el ciclo de desarrollo, sino también automatizar por completo el proceso de despliegue.</p> </div> <div class="paragraph"> <p>En este artículo, vamos a explorar cómo configurar una canalización completa con GitHub Actions para una aplicación Python, desde la integración continua (CI) hasta el despliegue continuo (CD) en PyPI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_del_pipeline">Arquitectura del Pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuestro pipeline se compone de dos flujos de trabajo distintos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Pipeline de CI</strong>: Ejecutado en cada push y pull request</p> </li> <li> <p><strong>pipeline CD</strong>: desencadenado únicamente durante los releases de GitHub</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/ci-cd-overview.svg" alt="ci cd overview" width="394" height="648"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_del_pipeline_de_integración_continua_ci">Configuración del Pipeline de Integración Continua (CI)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estructura_del_flujo_de_trabajo_ci">Estructura del flujo de trabajo CI</h3> <div class="paragraph"> <p>El flujo de trabajo CI está diseñado para validar cada contribución al código. Aquí está su configuración completa:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI/CD Pipeline on: push: branches: - main pull_request: branches: - main jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock - name: Run Linting (Ruff) run: ruff check . - name: Run Tests (Pytest) run: pytest</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_análisis_de_los_pasos_ci">Análisis de los pasos CI</h3> <div class="sect3"> <h4 id="_desencadenadores_on">desencadenadores (<code>on</code>)</h4> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">---- ---- on: push: branches: - main pull_request: branches: - main ---- El pipeline se dispara en : - Cada push en la rama`main` - Cada pull request hacia`main` Este enfoque garantiza que el código principal permanezca estable y que toda contribución sea validada antes de la integración. ==== 2. Entorno de Ejecución ---- runs-on: ubuntu-latest Ubuntu Latest ofrece un buen compromiso entre rendimiento, costo y compatibilidad para la mayoría de los proyectos de Python. ==== 3. Extracción del código ```yaml ---- ---- - name: Checkout code uses: actions/checkout@v4 ---- la acción`checkout@v4`obtiene el código fuente del repositorio. La versión v4 aporta mejoras de rendimiento y de seguridad. ==== 4. Configuración de Python ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' El uso de`'3.x'`permite usar automáticamente la última versión estable de Python 3, simplificando el mantenimiento. ==== 5. Instalación de las dependencias ```yaml ---- ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- Este paso: Actualiza pip a la última versión Instala las dependencias del proyecto - Añade las herramientas de desarrollo (linting y pruebas) ==== 6. Linting con Ruff ---- - name: Run Linting (Ruff) run: ruff check . **Ruff**es un linter de Python ultra-rápido escrito en Rust. Combina las funcionalidades de varias herramientas (Flake8, Black, isort) en una única herramienta de alto rendimiento. ==== Ejecución de las pruebas ```yaml ---- ---- - name: Run Tests (Pytest) run: pytest ---- Pytest ejecuta todo el conjunto de pruebas, garantizando que las modificaciones no introduzcan regresiones. == Configuración del pipeline de despliegue (CD) === Estructura del Workflow CD El flujo de trabajo CD se activa únicamente en las versiones de GitHub y automatiza la publicación en PyPI : [source,yaml] ---- name: Publish to PyPI on: release: types: - published jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/* ---- === Análisis de las etapas CD ==== 1. Disparador Release ---- on: release: types: - published El pipeline CD solo se activa cuando se publica una release de GitHub. Este enfoque garantiza un control preciso de los despliegues. ==== 2. Instalación de las Herramientas de compilación ```yaml ---- ---- pip install setuptools wheel twine ---- - **setuptools**: Herramientas de empaquetado de Python - **rueda**: Formato moderno de distribución de Python - **hilo**: Herramienta segura para subir a PyPI ==== 3. Configuración de la Autenticación ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} La autenticación utiliza un token de API PyPI almacenado como secreto de GitHub, más seguro que las credenciales clásicas. ==== 4. Compilación y publicación ```yaml ---- ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: Cree una distribución de código fuente - `bdist_wheel`: Crea una wheel (distribución binaria) - `twine upload`Publica las distribuciones en PyPI == Configuración del paquete de Python === Estructura del setup.py Para que el pipeline funcione, su proyecto debe incluir un archivo`setup.py` : [source,python] ---- from setuptools import setup, find_packages with open("README.adoc", "r", encoding="utf-8") as fh: long_description = fh.read() setup( name="playlist-downloader", version="1.0.0", author="Votre Nom", author_email="votre.email@example.com", description="CLI tool for managing YouTube playlists", long_description=long_description, long_description_content_type="text/plain", url="https://github.com/cheroliv/playlist-downloader", packages=find_packages(), classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", ], python_requires=">=3.8", install_requires=[ "typer>=0.9.0", "yt-dlp>=2023.1.6", "google-api-python-client>=2.70.0", "google-auth-oauthlib>=0.7.1", "pymonad>=2.4.0", "pyyaml>=6.0", ], entry_points={ "console_scripts": [ "playlist-downloader=cli:app", ], }, ) ---- === puntos clave de `setup.py 1. **Metadatos**nombre, version, autor, descripción 2. **Dependencias**Lista de los paquetes requeridos 3. **Puntos de entrada**: Comandos CLI expuestos 4. **Clasificadores**: Metadatos para PyPI == Seguridad con los GitHub Secrets === Configuración del Token PyPI 1. **Crear un token API en PyPI** : - Inicia sesión en PyPI - Vaya a Configuración de la cuenta > Tokens de API Cree un nuevo token con los permisos apropiados 1. **Agregar el secreto en GitHub**: - Configuración del repositorio > Secretos y variables > Acciones - Creen un nuevo secreto llamado`PYPI_API_TOKEN` - Pega tu token PyPI [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "Repositorio GitHub" as repo participant "GitHub Actions" as actions participant PyPI dev -> repo : Configure PYPI_API_TOKEN secret repo -> actions : Trigger CD pipeline on release actions -> actions : Access secret securely actions -> PyPI : Authenticate with token PyPI -> PyPI : Validate and publish package note over actions, PyPI Token never exposed in logs Automatic rotation possible end note @enduml ---- == Flujo de Despliegue Completo === Secuencia de Despliegue [plantuml, deployment-sequence, svg] ---- @startuml !theme plain actor Developer as dev participant "Git local" as git participant "GitHub" as github participant "GitHub Actions" as actions participant PyPI participant "usuarios finales" as users dev -> git : git tag v1.0.0 dev -> git : git push origin v1.0.0 git -> github : Push tag dev -> github : Create release from tag github -> actions : Trigger CD pipeline actions -> actions : Checkout code actions -> actions : Setup Python environment actions -> actions : Install build tools actions -> actions : Build distributions (sdist + wheel) actions -> PyPI : Upload to PyPI with token PyPI -> PyPI : Validate and publish users -> PyPI : pip install playlist-downloader note over dev, github Release creation can be automated or done manually through GitHub UI end note @enduml ---- === Estados del Pipeline [plantuml, pipeline-states, svg] ---- @startuml !theme plain [*] --> Idle Idle --> CI_Running : Push/PR created CI_Running --> CI_Success : All checks pass CI_Running --> CI_Failed : Linting/Tests fail CI_Success --> Idle : Merge completed CI_Failed --> Idle : Fix and retry Idle --> CD_Running : Release published CD_Running --> CD_Success : Package published CD_Running --> CD_Failed : Build/Upload error CD_Success --> Idle : Package available on PyPI CD_Failed --> Idle : Fix and retry release note on link #red : Blocks merge note on link #green : Allows deployment @enduml ---- == Buenas prácticas y optimizaciones === 1. Gestión de versiones Utilice etiquetas Git semánticas : ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 === 2. Pruebas de Matriz Para probar en varias versiones de Python : ```yaml ---- ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. Caché de Dependencias Acelere los builds con el caché : ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} === 4. Entornos de despliegue Utilice los entornos de GitHub para despliegues controlados : ```yaml ---- ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == Caso de Uso y Arquitectura === Diagrama de Casos de Uso [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "Desarrollador" as dev actor "GitHub Actions" as ga actor "Usuario final" as user package "Sistema CI/CD" { usecase "Ejecutar Linting" as lint usecase "Ejecutar pruebas" as test usecase "Paquete de construcción" as build usecase "Publicar en PyPI" as publish usecase "Crear versión" as release } dev --> lint : Pushes code dev --> test : Pushes code dev --> release : Creates release ga --> build : On release trigger ga --> publish : After successful build user --> publish : Downloads package lint .> test : triggers test .> build : on success build .> publish : on success @enduml ---- === Arquitectura de la Implementación [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "GitHub" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "pipeline de CI/CD" { [Linting] [Testing] [Building] [Publishing] } [Source Repository] --> [GitHub Actions] : Triggers [GitHub Actions] --> [Linting] [Linting] --> [Testing] [Testing] --> [Building] [Building] --> [Publishing] [Publishing] --> [Package Registry] : Uploads [Secrets Store] --> [Publishing] : Provides token note as N1 Secure token-based authentication end note [Secrets Store] .. N1 @enduml ---- == Monitoreo y depuración === Logs y monitoreo GitHub Actions proporciona registros detallados para cada paso. Para depurar: 1. **Examine los registros**de cada paso 2. **Active el debug**con`ACTIONS_STEP_DEBUG` 3. **Utiliza artefactos**para guardar los archivos de compilación ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ === Notificaciones Añade notificaciones de Slack o correo electrónico : ```yaml ---- ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == Conclusión La implementación de un pipeline CI/CD robusto con GitHub Actions transforma radicalmente la experiencia de desarrollo. Al automatizar el linting, las pruebas y el despliegue, usted: - **Reduce los errores**en producción - **Acelere los ciclos**de desarrollo - **Mejore la confianza**en sus releases - **Facilita la colaboración**en equipo Este pipeline puede adaptarse a diferentes tipos de proyectos Python ajustando las herramientas de linting, los frameworks de prueba o los destinos de despliegue. La inversión inicial en la configuración de estos flujos de trabajo se rentabiliza rápidamente gracias al ahorro de tiempo y la reducción de los errores manuales durante los despliegues. == Recursos Complementarios - https://docs.github.com/en/actions[Documentación GitHub Actions] - https://packaging.python.org/[Guía de empaquetado de Python] - https://docs.pytest.org/[Documentación Pytest] - https://docs.astral.sh/ruff/[Documentación Ruff] - https://twine.readthedocs.io/[Documentación Twine] ✅ Pipeline funcional alcanzado! Ahora tienes un pipeline CI/CD simple que te permite automatizar tus pruebas y publicar tu paquete Python en PyPI directamente desde GitHub Actions. Sin embargo, este pipeline sigue siendo intencionalmente minimalista. Aún no cubre algunos aspectos indispensables en un contexto profesional: Pruebas multi-versiones de Python, Análisis de seguridad automático, Despliegue progresivo a través de Test PyPI, Monitoreo y métricas del pipeline, Automatización del versionado y la integración de las mejores prácticas modernas (pyproject.toml). En la próxima parte, pasaremos al siguiente nivel. Aprenderás a transformar este pipeline básico en una verdadera cadena de despliegue industrial, robusta y segura, lista para proyectos de Python de producción. ----</code></pre> </div> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0084_disco_bot_discord_python_post.html Wed, 16 Jul 2025 00:00:00 +0000 blog/2025/0084_disco_bot_discord_python_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_contexto_y_desafíos_actuales">Contexto y Desafíos Actuales</a> <ul class="sectlevel2"> <li><a href="#_evolución_de_las_apis_musicales">Evolución de las APIs musicales</a></li> <li><a href="#_enfoque_log_driven_development">Enfoque Log Driven Development</a></li> </ul> </li> <li><a href="#_arquitectura_conceptual">Arquitectura Conceptual</a></li> <li><a href="#_pila_técnica_y_paradigma_funcional">Pila técnica y paradigma funcional</a> <ul class="sectlevel2"> <li><a href="#_elecciones_tecnológicas">Elecciones tecnológicas</a></li> <li><a href="#_principios_funcionales_aplicados">Principios Funcionales Aplicados</a></li> </ul> </li> <li><a href="#_metodología_ágil_y_backlog">Metodología Ágil y Backlog</a> <ul class="sectlevel2"> <li><a href="#_principales_épicos">Principales épicos</a> <ul class="sectlevel3"> <li><a href="#_epic_1_infraestructura_bot_discord">Epic 1: Infraestructura Bot Discord</a></li> <li><a href="#_épico_2_integración_spotify">Épico 2 : Integración Spotify</a></li> <li><a href="#_epic_3_integración_youtube">Epic 3 : Integración YouTube</a></li> <li><a href="#_épica_4_funcionalidades_musicales">Épica 4 : Funcionalidades Musicales</a></li> </ul> </li> <li><a href="#_user_stories_detalladas">User Stories Detalladas</a> <ul class="sectlevel3"> <li><a href="#_us1_1_inicialización_del_bot">US1.1: Inicialización del Bot</a></li> <li><a href="#_us2_1_búsqueda_inteligente_de_spotify">US2.1 : Búsqueda inteligente de Spotify</a></li> <li><a href="#_us3_1_extracción_de_youtube_resiliente">US3.1 : Extracción de YouTube resiliente</a></li> </ul> </li> </ul> </li> <li><a href="#_enfoque_de_desarrollo_impulsado_por_registros">Enfoque de desarrollo impulsado por registros</a> <ul class="sectlevel2"> <li><a href="#_estrategia_de_logging">Estrategia de Logging</a></li> <li><a href="#_estructura_de_los_logs">Estructura de los logs</a></li> <li><a href="#_ejemplo_de_diseño_de_registro">Ejemplo de Diseño de Registro</a></li> </ul> </li> <li><a href="#_arquitectura_de_validación_con_pydantic">Arquitectura de Validación con Pydantic</a> <ul class="sectlevel2"> <li><a href="#_modelos_de_datos">Modelos de Datos</a></li> </ul> </li> <li><a href="#_gestión_de_errores_funcionales">Gestión de errores funcionales</a> <ul class="sectlevel2"> <li><a href="#_monads_y_manejo_de_errores">Monads y Manejo de errores</a></li> </ul> </li> <li><a href="#_estrategia_de_evasión_de_las_restricciones">Estrategia de evasión de las restricciones</a> <ul class="sectlevel2"> <li><a href="#_enfoque_multi_fuente">Enfoque Multi-Fuente</a></li> </ul> </li> <li><a href="#_plan_de_desarrollo_iterativo">Plan de Desarrollo Iterativo</a> <ul class="sectlevel2"> <li><a href="#_planificación_del_sprint">Planificación del Sprint</a></li> <li><a href="#_métricas_de_calidad">Métricas de Calidad</a></li> </ul> </li> <li><a href="#_despliegue_y_monitoreo">Despliegue y Monitoreo</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_de_producción">Arquitectura de Producción</a></li> <li><a href="#_monitoreo_proactivo">Monitoreo Proactivo</a></li> </ul> </li> <li><a href="#_conclusión_y_perspectivas">Conclusión y Perspectivas</a> <ul class="sectlevel2"> <li><a href="#_próximos_pasos">Próximos Pasos</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introducción"><a class="anchor" href="#_introducción"></a>Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>El desarrollo de un bot de Discord que integre las API de Spotify y YouTube representa un desafío técnico moderno, especialmente considerando las recientes restricciones y evoluciones de las plataformas. Este artículo presenta un enfoque metodológico basado en el<strong>Desarrollo impulsado por logs</strong>(LDD), una extensión del Test Driven Development, aplicada en un paradigma funcional con Python.</p> </div> <div class="paragraph"> <p>Nuestro objetivo: crear un bot robusto, mantenible y escalable, capaz de navegar las restricciones actuales de las APIs musicales, ofreciendo al mismo tiempo una experiencia de usuario fluida en Discord.</p> </div> </div> </div> <div class="sect1"> <h2 id="_contexto_y_desafíos_actuales"><a class="anchor" href="#_contexto_y_desafíos_actuales"></a>Contexto y Desafíos Actuales</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_evolución_de_las_apis_musicales"><a class="anchor" href="#_evolución_de_las_apis_musicales"></a>Evolución de las APIs musicales</h3> <div class="paragraph"> <p>Las plataformas musicales han endurecido considerablemente sus políticas de acceso:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Spotify</strong>: Restricciones de acceso a los metadatos, limitación de las cuotas</p> </li> <li> <p><strong>YouTube</strong>: Política anti-bot reforzada, complejización de la autenticación</p> </li> <li> <p><strong>Discord</strong>: Nuevos requisitos de seguridad y rendimiento</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_enfoque_log_driven_development"><a class="anchor" href="#_enfoque_log_driven_development"></a>Enfoque Log Driven Development</h3> <div class="paragraph"> <p>El LDD extiende el TDD colocando los registros en el corazón del desarrollo:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Definición de los logs</strong>antes de la implementación</p> </li> <li> <p><strong>Validación por observación</strong>comportamientos esperados</p> </li> <li> <p><strong>Trazabilidad completa</strong>flujos de datos</p> </li> <li> <p><strong>Depuración proactiva</strong>por anticipación de los errores</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_conceptual"><a class="anchor" href="#_arquitectura_conceptual"></a>Arquitectura Conceptual</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-68d90920418474cb17f1456f0063494b.png" alt="Diagram" width="777" height="618"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pila_técnica_y_paradigma_funcional"><a class="anchor" href="#_pila_técnica_y_paradigma_funcional"></a>Pila técnica y paradigma funcional</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_elecciones_tecnológicas"><a class="anchor" href="#_elecciones_tecnológicas"></a>Elecciones tecnológicas</h3> <div class="paragraph"> <p>Nuestro stack se articula alrededor de la programación funcional:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>Gestión de los efectos de borde y composición de funciones</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>Validación de datos type-safe y serialización</p> </dd> <dt class="hdlist1"><strong>Asyncio</strong></dt> <dd> <p>Programación asíncrona para las APIs</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>Registro estructurado para el LDD</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_principios_funcionales_aplicados"><a class="anchor" href="#_principios_funcionales_aplicados"></a>Principios Funcionales Aplicados</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-a92eda8d03f56aba42bc0695be25117c.png" alt="Diagram" width="719" height="554"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_metodología_ágil_y_backlog"><a class="anchor" href="#_metodología_ágil_y_backlog"></a>Metodología Ágil y Backlog</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principales_épicos"><a class="anchor" href="#_principales_épicos"></a>Principales épicos</h3> <div class="paragraph"> <p>Nuestro desarrollo se organiza alrededor de 4 épicos mayores:</p> </div> <div class="sect3"> <h4 id="_epic_1_infraestructura_bot_discord"><a class="anchor" href="#_epic_1_infraestructura_bot_discord"></a>Epic 1: Infraestructura Bot Discord</h4> <div class="paragraph"> <p><strong>Valor del negocio</strong> : Base sólida y extensible</p> </div> <div class="paragraph"> <p><strong>Criterios de aceptación</strong> : - Conexión Discord estable con gestión de reconexión - Sistema modular de comandos - Registro estructurado integrado Gestión centralizada de errores</p> </div> </div> <div class="sect3"> <h4 id="_épico_2_integración_spotify"><a class="anchor" href="#_épico_2_integración_spotify"></a>Épico 2 : Integración Spotify</h4> <div class="paragraph"> <p><strong>Valor de negocio</strong>: Acceso a los metadatos musicales</p> </div> <div class="paragraph"> <p><strong>Criterios de aceptación</strong>: Autenticación OAuth2 segura - Búsqueda de tracks con caché inteligente - Búsqueda de tracks con caché inteligente - Gestión de las cuotas API - fallback sobre errores de red</p> </div> </div> <div class="sect3"> <h4 id="_epic_3_integración_youtube"><a class="anchor" href="#_epic_3_integración_youtube"></a>Epic 3 : Integración YouTube</h4> <div class="paragraph"> <p><strong>Valor de negocio</strong> : Acceso al contenido de audio</p> </div> <div class="paragraph"> <p><strong>Criterios de aceptación</strong> - Elusión legal de las restricciones - Extracción de audio optimizada Gestión de videos privados/eliminados - Respeto de las ToS de YouTube</p> </div> </div> <div class="sect3"> <h4 id="_épica_4_funcionalidades_musicales"><a class="anchor" href="#_épica_4_funcionalidades_musicales"></a>Épica 4 : Funcionalidades Musicales</h4> <div class="paragraph"> <p><strong>Valor de negocio</strong> : Experiencia de usuario completa</p> </div> <div class="paragraph"> <p>Criterios de aceptación - Reproducción de audio alta calidad Cola de lectura inteligente - Comandos de voz Discord - Sincronización multiplataforma</p> </div> </div> </div> <div class="sect2"> <h3 id="_user_stories_detalladas"><a class="anchor" href="#_user_stories_detalladas"></a>User Stories Detalladas</h3> <div class="sect3"> <h4 id="_us1_1_inicialización_del_bot"><a class="anchor" href="#_us1_1_inicialización_del_bot"></a>US1.1: Inicialización del Bot</h4> <div class="paragraph"> <p>Como <strong>Quiero</strong> un bot de Discord que se conecta de manera fiable <strong>Para</strong> garantir la disponibilidad del servicio</p> </div> <div class="paragraph"> <p><strong>DoD (Definition of Done)</strong>: - [ ] Bot se conecta automáticamente al inicio - [ ] Los registros estructurados documentan cada paso - [ ] Reconexión automática en caso de desconexión - [ ] Pruebas de integración pasan</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_búsqueda_inteligente_de_spotify"><a class="anchor" href="#_us2_1_búsqueda_inteligente_de_spotify"></a>US2.1 : Búsqueda inteligente de Spotify</h4> <div class="paragraph"> <p><strong>Como</strong> usuario Discord <strong>Quiero</strong> buscar canciones vía Spotify <strong>Para</strong> descubrir y compartir música</p> </div> <div class="paragraph"> <p><strong>DoD</strong>: - [ ] Orden`/search` fonctionnelle - [ ] Resultados relevantes con metadatos - [ ] caché local para optimizar las consultas [ ] Manejo amigable de los errores de la API</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_extracción_de_youtube_resiliente"><a class="anchor" href="#_us3_1_extracción_de_youtube_resiliente"></a>US3.1 : Extracción de YouTube resiliente</h4> <div class="paragraph"> <p><strong>Como</strong> sistema <strong>Quiero</strong> extraer el audio de YouTube de manera fiable <strong>Con el fin de</strong> mantener la continuidad del servicio</p> </div> <div class="paragraph"> <p><strong>DoD</strong>: - [ ] Extracción sin violar los ToS - [ ] Calidad de audio óptima - [ ] Gestión de las restricciones geográficas - [ ] Registros detallados de las operaciones</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_enfoque_de_desarrollo_impulsado_por_registros"><a class="anchor" href="#_enfoque_de_desarrollo_impulsado_por_registros"></a>Enfoque de desarrollo impulsado por registros</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrategia_de_logging"><a class="anchor" href="#_estrategia_de_logging"></a>Estrategia de Logging</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-f909f37748708ec8c495e65d2d88718a.png" alt="Diagram" width="687" height="633"> </div> </div> </div> <div class="sect2"> <h3 id="_estructura_de_los_logs"><a class="anchor" href="#_estructura_de_los_logs"></a>Estructura de los logs</h3> <div class="paragraph"> <p>Nuestro enfoque LDD utiliza registros estructurados con niveles semánticos:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>traza</strong></dt> <dd> <p>Flujo de datos detallado</p> </dd> <dt class="hdlist1"><strong>DEBUG</strong></dt> <dd> <p>Estados internos de las funciones</p> </dd> <dt class="hdlist1"><strong>INFO</strong></dt> <dd> <p>Operaciones de negocio exitosas</p> </dd> <dt class="hdlist1"><strong>ADVERTIR</strong></dt> <dd> <p>Situaciones degradadas pero gestionadas</p> </dd> <dt class="hdlist1"><strong>error</strong></dt> <dd> <p>Errores que requieren intervención</p> </dd> <dt class="hdlist1"><strong>CRITICAL</strong></dt> <dd> <p>Fallos del sistema</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_ejemplo_de_diseño_de_registro"><a class="anchor" href="#_ejemplo_de_diseño_de_registro"></a>Ejemplo de Diseño de Registro</h3> <div class="paragraph"> <p>Antes de implementar la función de búsqueda de Spotify, definimos sus registros:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">INFO: spotify.search.start query="bohemian rhapsody" user_id=123456 DEBUG: spotify.search.validation query_length=16 safe_chars=true DEBUG: spotify.search.api_call endpoint="/search" params={...} INFO: spotify.search.success results_count=15 duration_ms=340</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_de_validación_con_pydantic"><a class="anchor" href="#_arquitectura_de_validación_con_pydantic"></a>Arquitectura de Validación con Pydantic</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_modelos_de_datos"><a class="anchor" href="#_modelos_de_datos"></a>Modelos de Datos</h3> <div class="paragraph"> <p>Nuestro enfoque funcional favorece la validación anticipada:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ebd4e1dfbd7b19d5a6054ecf213e9e2d.png" alt="Diagram" width="696" height="339"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_gestión_de_errores_funcionales"><a class="anchor" href="#_gestión_de_errores_funcionales"></a>Gestión de errores funcionales</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_monads_y_manejo_de_errores"><a class="anchor" href="#_monads_y_manejo_de_errores"></a>Monads y Manejo de errores</h3> <div class="paragraph"> <p>El uso de PyMonade permite una gestión elegante de los errores:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-4f33aaf6507a4cb1fbddfe99e1205e81.png" alt="Diagram" width="505" height="494"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estrategia_de_evasión_de_las_restricciones"><a class="anchor" href="#_estrategia_de_evasión_de_las_restricciones"></a>Estrategia de evasión de las restricciones</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_enfoque_multi_fuente"><a class="anchor" href="#_enfoque_multi_fuente"></a>Enfoque Multi-Fuente</h3> <div class="paragraph"> <p>Ante las restricciones de las API, adoptamos una estrategia de diversificación:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-02e5c2db6f5a17e38b57fa00d63bf335.png" alt="Diagram" width="665" height="744"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plan_de_desarrollo_iterativo"><a class="anchor" href="#_plan_de_desarrollo_iterativo"></a>Plan de Desarrollo Iterativo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_planificación_del_sprint"><a class="anchor" href="#_planificación_del_sprint"></a>Planificación del Sprint</h3> <div class="paragraph"> <p>Nuestro desarrollo sigue un ciclo de sprints de 2 semanas:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>Sprint 1-2</strong></dt> <dd> <p>Infraestructura y Discord Bot Core</p> </dd> <dt class="hdlist1"><strong>Sprint 3-4</strong></dt> <dd> <p>Integración Spotify con LDD</p> </dd> <dt class="hdlist1"><strong>Sprint 5-6</strong></dt> <dd> <p>Integración de YouTube y soluciones alternativas</p> </dd> <dt class="hdlist1"><strong>Sprint 7-8</strong></dt> <dd> <p>Características musicales avanzadas</p> </dd> <dt class="hdlist1"><strong>Sprint 9-10</strong></dt> <dd> <p>Optimización y producción</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_métricas_de_calidad"><a class="anchor" href="#_métricas_de_calidad"></a>Métricas de Calidad</h3> <div class="paragraph"> <p>Cada sprint se evalúa en:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Cobertura de logs</strong>: >90% de los caminos críticos</p> </li> <li> <p><strong>Fiabilidad API</strong>: <1% de errores no gestionados</p> </li> <li> <p><strong>Rendimiento</strong>: <500ms tiempo de respuesta medio</p> </li> <li> <p><strong>Mantenibilidad</strong>: Complejidad ciclomática <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_despliegue_y_monitoreo"><a class="anchor" href="#_despliegue_y_monitoreo"></a>Despliegue y Monitoreo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitectura_de_producción"><a class="anchor" href="#_arquitectura_de_producción"></a>Arquitectura de Producción</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-6b28fc69f6280b7c1d9ffbae38c9b1df.png" alt="Diagram" width="938" height="381"> </div> </div> </div> <div class="sect2"> <h3 id="_monitoreo_proactivo"><a class="anchor" href="#_monitoreo_proactivo"></a>Monitoreo Proactivo</h3> <div class="paragraph"> <p>El LDD facilita un monitoreo inteligente :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Alertas basadas en los patrones de logs</strong></p> </li> <li> <p><strong>Detección de anomalías de comportamiento</strong></p> </li> <li> <p><strong>Métricas de negocio en tiempo real</strong></p> </li> <li> <p><strong>Debugging asistido por correlación de logs</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_y_perspectivas"><a class="anchor" href="#_conclusión_y_perspectivas"></a>Conclusión y Perspectivas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este enfoque metodológico combina los beneficios del paradigma funcional con la robustez del Log Driven Development. Nos permite:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Anticipar los problemas</strong>gracias a los logs diseñados de antemano</p> </li> <li> <p><strong>Mantener la calidad</strong>a través de la validación continua</p> </li> <li> <p><strong>Adaptar rápidamente</strong>a los cambios de APIs</p> </li> <li> <p><strong>Garantizar la trazabilidad</strong>completa operaciones</p> </li> </ol> </div> <div class="paragraph"> <p>El desarrollo iterativo y la arquitectura modular garantizan una escalabilidad frente a las restricciones cambiantes de las plataformas musicales.</p> </div> <div class="sect2"> <h3 id="_próximos_pasos"><a class="anchor" href="#_próximos_pasos"></a>Próximos Pasos</h3> <div class="ulist"> <ul> <li> <p><strong>Fase 1</strong>: Implementación del core con PyMonade</p> </li> <li> <p><strong>Fase 2</strong>: Integración Spotify con caché inteligente</p> </li> <li> <p><strong>Fase 3</strong>: Solución YouTube resiliente</p> </li> <li> <p><strong>Fase 4</strong>Features avanzadas y optimización</p> </li> </ul> </div> <div class="paragraph"> <p>Esta sólida fundación conceptual nos permitirá navegar los desafíos técnicos mientras brindamos una experiencia de usuario excepcional.</p> </div> <hr> <div class="paragraph"> <p><strong>Este artículo será seguido de una serie técnica que detallará la implementación de cada componente con ejemplos de código y patrones funcionales.</strong></p> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0083_cold_computer_post.html Tue, 15 Jul 2025 00:00:00 +0000 blog/2025/0083_cold_computer_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_objetivo_de_esta_guía">Objetivo de esta guía</a></li> <li><a href="#_requisitos_previos">Requisitos previos</a></li> <li><a href="#_instalar_y_configurar_las_herramientas">Instalar y configurar las herramientas</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_para_detectar_los_sensores">lm-sensors` para detectar los sensores</a></li> <li><a href="#_tlp_gestor_de_energía_inteligente">tlp` : gestor de energía inteligente</a></li> <li><a href="#_cpufrequtils_limitar_las_frecuencias_de_la_cpu">cpufrequtils` : limitar las frecuencias de la CPU</a></li> <li><a href="#_auto_cpufreq_gestión_dinámica_simplificada">auto-cpufreq` : gestión dinámica simplificada</a></li> <li><a href="#_thermald_protección_térmica_automática">thermald` : protección térmica automática</a></li> </ul> </li> <li><a href="#_monitoreo_en_tiempo_real">Monitoreo en tiempo real</a> <ul class="sectlevel2"> <li><a href="#_sensors_en_la_línea_de_comandos">sensors` en la línea de comandos</a></li> <li><a href="#_opción_gui_psensor">Opción GUI : `psensor</a></li> </ul> </li> <li><a href="#_consejos_adicionales">Consejos adicionales</a></li> <li><a href="#_limpiar_el_sistema_para_limitar_las_sobrecargas">Limpiar el sistema para limitar las sobrecargas</a></li> <li><a href="#_para_ir_más_lejos">Para ir más lejos</a></li> <li><a href="#_conclusión">📚 Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>¿Siente que su portátil se calienta anormalmente bajo Ubuntu? Este artículo le propone un enfoque<strong>de software</strong>completa para<strong>enfriar</strong>, <strong>vigilar</strong> et <strong>controlar la temperatura</strong>de su máquina.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivo_de_esta_guía">Objetivo de esta guía</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Reducir la temperatura global del ordenador</p> </li> <li> <p>Optimizar la gestión de energía</p> </li> <li> <p>Monitorear los componentes críticos (CPU, GPU, etc.)</p> </li> <li> <p>Evitar los retrasos debidos al<strong>estrangulamiento térmico</strong></p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="gestion_thermique.svg" alt="gestion thermique" width="392" height="298"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_requisitos_previos">Requisitos previos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Una máquina Ubuntu (20.04 o superior recomendada)</p> </li> <li> <p>Conexión a Internet</p> </li> <li> <p>Habilidad en línea de comandos (nivel principiante a intermedio)</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_instalar_y_configurar_las_herramientas">Instalar y configurar las herramientas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_para_detectar_los_sensores">lm-sensors` para detectar los sensores</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install lm-sensors sudo sensors-detect sensors</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Respondan`YES`a todas las preguntas de`sensors-detect`para detectar los módulos.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_gestor_de_energía_inteligente">tlp` : gestor de energía inteligente</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install tlp tlp-rdw sudo systemctl enable tlp sudo systemctl start tlp</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="tlp_etat.svg" alt="tlp etat" width="380" height="390"> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_limitar_las_frecuencias_de_la_cpu">cpufrequtils` : limitar las frecuencias de la CPU</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install cpufrequtils cpufreq-info sudo cpufreq-set -g powersave</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>powersave</code>: limita los picos de frecuencia</p> </li> <li> <p><code>performance</code>: favorece la potencia a costa de la temperatura</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_gestión_dinámica_simplificada">auto-cpufreq` : gestión dinámica simplificada</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git clone https://github.com/AdnanHodzic/auto-cpufreq.git cd auto-cpufreq sudo ./auto-cpufreq-installer sudo auto-cpufreq --install</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="auto_cpufreq_cycle.svg" alt="auto cpufreq cycle" width="189" height="298"> </div> </div> </div> <div class="sect2"> <h3 id="_thermald_protección_térmica_automática">thermald` : protección térmica automática</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install thermald sudo systemctl enable thermald sudo systemctl start thermald</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoreo_en_tiempo_real">Monitoreo en tiempo real</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_en_la_línea_de_comandos">sensors` en la línea de comandos</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">watch -n 2 sensors</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_opción_gui_psensor">Opción GUI : `psensor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install psensor</code></pre> </div> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>Interfaz gráfica simple para CPU, GPU, ventiladores.</p> </div> </blockquote> </div> </div> </div> </div> <div class="sect1"> <h2 id="_consejos_adicionales">Consejos adicionales</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Cerrar las pestañas y aplicaciones pesadas (ej: navegadores)</p> </li> <li> <p>Evitar el uso intensivo en batería</p> </li> <li> <p>Monitorear los procesos vía`htop`:</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install htop htop</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_limpiar_el_sistema_para_limitar_las_sobrecargas">Limpiar el sistema para limitar las sobrecargas</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt autoremove sudo apt autoclean sudo journalctl --vacuum-time=3d</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puede crear un servicio`systemd`personalizado para aplicar automáticamente algunos ajustes al arranque. ¿Quieres un ejemplo en un próximo artículo? ¡Hazmelo saber!</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">📚 Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Al combinar estas herramientas simples, ganarás :</p> </div> <div class="ulist"> <ul> <li> <p>Una temperatura CPU controlada</p> </li> <li> <p>Menos ruido de ventilación</p> </li> <li> <p>Una mayor autonomía</p> </li> </ul> </div> <div class="paragraph"> <p>No olviden supervisar sus temperaturas regularmente para prevenir cualquier sobrecalentamiento.</p> </div> <div class="paragraph"> <p><em><em>_ Más vale prevenir que fundir su CPU. </em>_</em></p> </div> </div> </div> https://cheroliv.com//blog/2025/0082_ui_struggle_post.html Mon, 14 Jul 2025 00:00:00 +0000 blog/2025/0082_ui_struggle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_el_campo_de_batalla_una_maqueta_tres_navegadores_renderizados_múltiples">El campo de batalla: una maqueta, tres navegadores, renderizados múltiples</a></li> <li><a href="#_problema_1_la_tarjeta_volante_de_la_sección_hero">Problema 1: La tarjeta volante de la sección "Hero</a></li> <li><a href="#_problema_2_la_barra_de_navegación_caníbal">Problema 2 : La barra de navegación caníbal</a></li> <li><a href="#_problema_3_la_tipografía_anárquica">Problema 3 : La tipografía anárquica</a></li> <li><a href="#_problema_4_la_barra_de_navegación_que_se_desborda">Problema 4: La barra de navegación que se desborda</a></li> <li><a href="#_problema_5_el_menú_hamburguesa_invisible">Problema 5: El menú hamburguesa invisible</a></li> <li><a href="#_conclusión_las_lecciones_de_una_depuración_tenaz">Conclusión: las lecciones de una depuración tenaz</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Tiempo de lectura:</strong> aproximadamente 7 minutos <strong>Nivel :</strong> Intermedio</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>En este caso práctico detallado, vamos a desglosar los problemas de compatibilidad de navegador más comunes y a veces más frustrantes encontrados al crear una maqueta UI con Bootstrap 5.2. Desde la gestión de Flexbox hasta la sutileza del renderizado de fuentes, descubre nuestro recorrido de depuración para transformar un diseño inestable bajo Firefox en una experiencia pixel-perfect en todos los navegadores.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_el_campo_de_batalla_una_maqueta_tres_navegadores_renderizados_múltiples">El campo de batalla: una maqueta, tres navegadores, renderizados múltiples</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo desarrollador front-end conoce esa sensación. Después de horas de trabajo, la maqueta está finalmente perfecta. Los alineaciones son nítidos, la tipografía es elegante, las animaciones son fluidas. Suelta un suspiro de satisfacción, admira su trabajo en Chrome (o Brave, o Edge), y luego, por precaución, abre el proyecto en Firefox. Y ahí, viene el drama. Elementos que se desbordan, alineaciones rotos, tipografías con tamaños caóticos… la hermosa armonía se ha ido.</p> </div> <div class="paragraph"> <p>Es precisamente el escenario al que nos enfrentamos al desarrollar una nueva interfaz de portafolio. El pliego de condiciones era simple: una página de inicio moderna, responsive, con un selector de temas (claro, oscuro y de alto contraste), utilizando <strong>vanilla JavaScript</strong> y la última versión de <strong>Bootstrap 5.2</strong>.</p> </div> <div class="paragraph"> <p>Este artículo no es una lista de soluciones milagrosas. Es el registro de nuestra sesión de depuración, una inmersión en el "porqué" de las diferencias de renderizado entre los motores Blink (Chromium, Brave) y Gecko (Firefox), y la demostración de que las soluciones robustas y modernas siempre valen mejor que los parches apresurados.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/usecase-debugging-firefox.svg" alt="usecase debugging firefox" width="1043" height="401"> </div> <div class="title">Figure 1. Diagrama de Casos de Uso : El proceso de depuración</div> </div> <div class="imageblock"> <div class="content"> <img src="./images/components-solution-architecture.svg" alt="components solution architecture" width="1200" height="5160"> </div> <div class="title">Figure 2. Diagrama de componentes : Arquitectura de la solución front-end</div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_1_la_tarjeta_volante_de_la_sección_hero">Problema 1: La tarjeta volante de la sección "Hero</h2> <div class="sectionbody"> <div class="paragraph"> <p>El primer error también era el más visible. La sección de inicio ("hero") está compuesta de dos columnas: a la izquierda, el título principal; a la derecha, una tarjeta de presentación.</p> </div> <div class="ulist"> <ul> <li> <p><strong>El síntoma:</strong>En Chrome y Brave, las dos columnas estaban perfectamente centradas verticalmente. En Firefox, la tarjeta de la derecha caía inexplicablemente debajo del texto de la izquierda.</p> </li> <li> <p><strong>La investigación:</strong>El código HTML parecía, sin embargo, sencillo y correcto, utilizando las clases estándar de Bootstrap.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container"> <!-- Cette ligne est la clé du problème --> <div class="row align-items-center min-vh-100"> <div class="col-lg-6"> <!-- Contenu de gauche --> </div> <div class="col-lg-6"> <!-- Carte de droite --> </div> </div> </div> </section></code></pre> </div> </div> <div class="paragraph"> <p>Nuestro CSS personalizado para`.hero-section`definía`display: flex` et <code>align-items: center</code>, y la clase`min-vh-100`daba una altura mínima a la línea (<code>div.row</code>). Entonces, ¿por qué Firefox se negaba a centrar las columnas?</p> </div> <div class="ulist"> <ul> <li> <p><strong>La causa profunda:</strong>Es un ejemplo típico de la manera en que los motores de renderizado interpretan las alturas implícitas. La`<section>`tenía una`min-height`, pero no`height`explícito. Para aplicar`align-items-center`dentro de`div.row`, Firefox necesita conocer la altura de referencia de este contenedor. Como sus padres (<code>div.container</code> et la `<section>`ella misma) no tenían altura<strong>estricta</strong>, Firefox estaba perdido. El motor Blink, más permisivo, logra "adivinar" la intención y centrar los elementos. Gecko, más fiel a la especificación, no lo hace.</p> </li> <li> <p><strong>La solución:</strong>Hacer explícita la altura. Hemos forzado el`.container` et le `.row`a ocupar el 100% de la altura de su padre respectivo utilizando la clase utilitaria`h-100`de Bootstrap.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container h-100"> <div class="row align-items-center min-vh-100 h-100"> <!-- ... --> </div> </div> </section></code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Cuando un`align-items`Flexbox no funciona como se espera en el eje vertical, siempre verifique que el contenedor tenga una altura`height` ou <code>min-height</code>) definida y, si el problema persiste (especialmente en Firefox), asegúrese de que los contenedores padres intermedios propaguen bien esta altura.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_problema_2_la_barra_de_navegación_caníbal">Problema 2 : La barra de navegación caníbal</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Una vez alineada la sección "Hero", surgió otro problema: la barra de navegación, con su clase`fixed-top`, se superponía al título. Un`padding-top: 80px`había sido aplicado a la sección "Hero" como solución.</div> <ul> <li> <p><strong>El síntoma :</strong> Le `padding`era suficiente en Chrome, pero no en Firefox, donde el título estaba siempre parcialmente oculto.</p> </li> <li> <p><strong>La causa profunda:</strong>El uso de un "número mágico" (<code>80px</code>) es una muy mala práctica. La altura de un elemento como una barra de navegación puede variar de unos pocos píxeles de un navegador a otro debido a diferencias sutiles en el renderizado de las fuentes, los espacios o incluso las opciones del usuario. Confiar en un valor fijo es la receta para un diseño frágil.</p> </li> <li> <p><strong>La solución :</strong>Una solución dinámica e infalible en JavaScript. Hemos escrito un pequeño script para:</p> </li> <li> <p>Medir la altura <strong>real</strong> de la barra de navegación después del renderizado de la página.</p> </li> <li> <p>Aplicar esta altura medida como`padding-top`a la sección "Hero".</p> </li> <li> <p>Vuelve a ejecutar esta función cada vez que se redimensione la ventana para adaptarse a los cambios (como pasar al menú hamburguesa).</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function() { function adjustHeroPadding() { const navbar = document.querySelector('.navbar.fixed-top'); const heroSection = document.querySelector('.hero-section'); if (navbar && heroSection) { const navbarHeight = navbar.offsetHeight; heroSection.style.paddingTop = navbarHeight + 'px'; } } // Ajuster au chargement et au redimensionnement adjustHeroPadding(); window.addEventListener('resize', adjustHeroPadding); });</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/sequence-dynamic-padding.svg" alt="sequence dynamic padding" width="887" height="703"> </div> <div class="title">Figure 3. Diagrama de Secuencia: Ajuste dinámico del padding</div> </div> <div class="paragraph"> <p>En paralelo, por supuesto, hemos eliminado la regla`padding-top: 80px;`de nuestro archivo`styles.css`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_la_tipografía_anárquica">Problema 3 : La tipografía anárquica</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">La preocupación siguiente era la más perjudicial para la imagen de marca: el tamaño del título principal.</div> <ul> <li> <p><strong>El síntoma:</strong>En Firefox, la fuente del título "Développeur Formateur…​" era gigantesca, casi chocante, mientras que era armoniosa en los otros navegadores.</p> </li> <li> <p><strong>La causa profunda :</strong>El título utilizaba una clase`display-4`de Bootstrap. Estas clases utilizan tamaños de fuente responsivos, a menudo basados en la unidad`rem`y de las media queries. Una vez más, el algoritmo de renderizado de Firefox, combinado con la fuente "Inter", resultó en un cálculo de tamaño mucho mayor en nuestra resolución de 1920x1080.</p> </li> <li> <p><strong>La solución :</strong>Recuperar el control con la función CSS`clamp()<code>. Esta función es una revolución para la tipografía fluida. Permite definir un tamaño de fuente con tres valores: un tamaño mínimo, un tamaño "preferido" (que se adapta al ancho de la vista,`vw</code>), y un tamaño máximo.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.hero-content h1 { color: var(--text-primary); line-height: 1.2; /* Min: 2rem Préférée: s'adapte à la vue Max: 2.5rem (40px) */ font-size: clamp(2rem, 1.2rem + 1.5vw, 2.5rem); }</code></pre> </div> </div> <div class="paragraph"> <p>con`clamp()<code>, hemos podido decirle al navegador : "Haz crecer la fuente con la pantalla, pero no excedas<strong>nunca</strong>el límite de`2.5rem</code>. Esto instantáneamente armonizó la representación en todos los navegadores, brindándonos un control absoluto sobre la estética final.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_la_barra_de_navegación_que_se_desborda">Problema 4: La barra de navegación que se desborda</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Es el problema que nos dio más quebraderos de cabeza y que finalmente reveló la naturaleza profunda de las microdiferencias de representación.</div> <ul> <li> <p><strong>El síntoma:</strong>En una pantalla de 1920x1080, los últimos enlaces del menú ("Blog", "Contact") se empujaban fuera de la pantalla hacia la derecha, pero solo en Firefox.</p> </li> <li> <p><strong>La causa profunda:</strong>Tras varios intentos fallidos (cambiar los puntos de ruptura de Bootstrap de`lg` à <code>xl`luego`xxl</code>), hemos entendido. La causa no era la lógica de Bootstrap, sino un simple cálculo de ancho. En Firefox, la suma de los anchos de todos los enlaces, incluyendo sus`padding` et `margin`al subpíxel más cercano, era <strong>ligeramente</strong> superior a 1920 píxeles. En Chrome, esta misma suma era <strong>ligeramente</strong> inferior. Nos faltaban algunos píxeles.</p> </li> <li> <p><strong>La solución :</strong>Una reducción quirúrgica del espaciado. Puesto que estaba fuera de toda cuestión de apuntar específicamente a Firefox con "hacks" CSS obsoletos, la única solución limpia era encontrar un estilo común que funcionara en todas partes. Por lo tanto, hemos reducido ligeramente los márgenes y el padding horizontal de cada enlace de navegación.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* La version finale, légèrement plus compacte */ .navbar-nav .nav-link { font-size: 0.9rem; /* 90% de la taille de base */ color: var(--text-primary) !important; font-weight: 500; margin: 0 0.2rem; padding: 0.5rem 0.5rem !important; border-radius: 0.375rem; transition: all 0.3s ease; }</code></pre> </div> </div> <div class="paragraph"> <p>Esta reducción, casi invisible a simple vista en un solo elemento, nos ha permitido ganar colectivamente el espacio necesario para que todos los enlaces quepan en el marco en Firefox, manteniendo al mismo tiempo una apariencia casi idéntica en los demás navegadores.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_5_el_menú_hamburguesa_invisible">Problema 5: El menú hamburguesa invisible</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">El último problema, y no de menor importancia, se refería a la accesibilidad en móviles.</div> <ul> <li> <p><strong>El síntoma:</strong>En modo responsive (menú "hamburger"), el icono del menú era invisible en los temas "dark" y "high-contrast".</p> </li> <li> <p><strong>La causa profunda:</strong>El icono del menú de Bootstrap 5 es un`background-image`(un SVG codificado en URL). Por defecto, el color de su trazo es oscuro, optimizado para un fondo claro. No se adapta automáticamente al cambio de tema.</p> </li> <li> <p><strong>La solución :</strong>Utilizar las variables CSS de Bootstrap para sobrescribir el ícono. Hemos definido un nuevo ícono SVG, pero esta vez con un trazo blanco (<code>#ffffff</code>), y lo aplicamos específicamente cuando los temas`dark` ou `high-contrast`están activos.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* ====================== Fix pour l'icône du menu Burger (Blanc) ====================== */ [data-bs-theme="dark"] .navbar-toggler-icon, [data-bs-theme="high-contrast"] .navbar-toggler-icon { --bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23ffffff' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e"); }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>La personalización de los componentes de Bootstrap como este se hace cada vez más mediante la sobrescritura de variables CSS (<code>--bs-component-property</code>), que es el método más limpio y duradero.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión_las_lecciones_de_una_depuración_tenaz">Conclusión: las lecciones de una depuración tenaz</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este recorrido, aunque a veces frustrante, es rico en enseñanzas. Cada problema resuelto refuerza una verdad fundamental del desarrollo web:<strong>Nada sustituye una prueba rigurosa entre navegadores</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/mindmap-debugging-summary.svg" alt="mindmap debugging summary" width="999" height="866"> </div> <div class="title">Figure 4. Mapa mental : Síntesis de la depuración y las lecciones aprendidas</div> </div> <div class="olist arabic"> <div class="title">Aquí están las lecciones que hemos retenido :</div> <ol class="arabic"> <li> <p><strong>Firefox es un aliado:</strong>Su mayor fidelidad a los estándares CSS nos obliga a escribir un código más robusto y menos ambiguo.</p> </li> <li> <p><strong>Huid de los "números mágicos" :</strong>Los valores fijos (como`padding-top: 80px`) son bombas de tiempo. Siempre prefiera soluciones dinámicas (JavaScript) o relativas (Flexbox, Grid).</p> </li> <li> <p><strong>Domina tu tipografía :</strong>Utilice`clamp()`para un control total sobre el tamaño de las fuentes responsivas.</p> </li> <li> <p><strong>Piensa en "componentes":</strong>Para personalizar Bootstrap, sobrescriba sus variables CSS en lugar de multiplicar las reglas que anulan el framework.</p> </li> <li> <p><strong>No apunte a un navegador:</strong>La solución casi nunca es hacer un "hack" para un navegador específico, sino encontrar un estilo común que funcione en todas partes.</p> </li> </ol> </div> <div class="paragraph"> <p>Al final, la maqueta ahora es sólida, predecible y lista para integrarse en un sistema de plantillas. Cada error corregido no fue un fracaso, sino un paso hacia un código de mejor calidad.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0081_TDD_Gradle_Properties_Fix_post.html Sun, 13 Jul 2025 00:00:00 +0000 blog/2025/0081_TDD_Gradle_Properties_Fix_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_el_problema_aislar_las_pruebas_unitarias_de_un_plugin_gradle">El problema: aislar las pruebas unitarias de un plugin Gradle</a> <ul class="sectlevel2"> <li><a href="#_arquitectura_del_problema">Arquitectura del Problema</a></li> <li><a href="#_la_tentación_de_una_falsa_buena_idea">La Tentación de una Falsa Buena Idea</a></li> </ul> </li> <li><a href="#_la_solución_simular_la_propiedad_con_extrapropertiesextension">La Solución : Simular la Propiedad con `ExtraPropertiesExtension</a> <ul class="sectlevel2"> <li><a href="#_paso_1_comprender_extrapropertiesextension">Paso 1: Comprender ExtraPropertiesExtension</a></li> <li><a href="#_paso_2_configuración_de_la_prueba_preparación">Paso 2: Configuración de la prueba - Preparación</a></li> <li><a href="#_paso_3_inyección_de_la_propiedad">Paso 3: Inyección de la Propiedad</a></li> <li><a href="#_paso_4_diagrama_de_flujo_de_la_solución">Paso 4 : Diagrama de flujo de la solución</a></li> <li><a href="#_paso_5_comparación_antesdespués">Paso 5 : Comparación Antes/Después</a></li> <li><a href="#_paso_6_gestión_de_los_casos_de_prueba_multiples">Paso 6 : Gestión de los casos de prueba multiples</a></li> <li><a href="#_arquitectura_final_de_la_solución">Arquitectura Final de la Solución</a></li> </ul> </li> <li><a href="#_las_ventajas_de_este_enfoque">Las ventajas de este enfoque</a></li> <li><a href="#_buenas_prácticas_y_consejos">Buenas Prácticas y Consejos</a> <ul class="sectlevel2"> <li><a href="#_crear_un_método_utilitario">Crear un Método Utilitario</a></li> <li><a href="#_validación_de_las_propiedades">Validación de las Propiedades</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div class="sect1"> <h2 id="_el_problema_aislar_las_pruebas_unitarias_de_un_plugin_gradle">El problema: aislar las pruebas unitarias de un plugin Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Al escribir pruebas unitarias para un plugin de Gradle, un desafío común es gestionar las dependencias de la configuración del proyecto, como las propiedades definidas en el archivo`gradle.properties`. En nuestro caso, el plugin`jbake.ghpages`debía leer una propiedad`site_config_path`para funcionar correctamente. La prueba unitaria para la tarea`initialize`debía comprobar el comportamiento del plugin en presencia de esta propiedad.</p> </div> <div class="paragraph"> <p>El problema fundamental es que las pruebas unitarias, por diseño, deben ser <strong>aislados</strong>. El uso de`ProjectBuilder`de Gradle crea una instancia de`Project`en memoria, completamente desconectada de un proyecto real en el sistema de archivos. Por lo tanto, esta instancia de prueba no lee automáticamente el archivo`gradle.properties`y por lo tanto no tiene conocimiento de la propiedad`site_config_path`.</p> </div> <div class="sect2"> <h3 id="_arquitectura_del_problema">Arquitectura del Problema</h3> <div class="paragraph"> <p>El siguiente diagrama ilustra la desconexión entre el entorno de prueba y el sistema de archivos:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/test-isolation-problem.svg" alt="test isolation problem" width="1199" height="5787"> </div> </div> </div> <div class="sect2"> <h3 id="_la_tentación_de_una_falsa_buena_idea">La Tentación de una Falsa Buena Idea</h3> <div class="paragraph"> <p>Una primera aproximación podría ser crear un archivo`gradle.properties`ficticio en los recursos de la prueba.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">// src/test/resources/gradle.properties site_config_path=src/jbake/settings/site.yml</code></pre> </div> </div> <div class="paragraph"> <p>Sin embargo, este método está destinado al fracaso porque`ProjectBuilder`no está diseñado para escanear el sistema de archivos en busca de archivos de configuración. La prueba permanecería aislada e ignoraría este archivo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_simular_la_propiedad_con_extrapropertiesextension">La Solución : Simular la Propiedad con `ExtraPropertiesExtension</h2> <div class="sectionbody"> <div class="paragraph"> <p>La solución elegante a este problema no es <strong>leer</strong> el archivo, sino <strong>simular</strong> la presencia de la propiedad directamente en el objeto`Project`de test. Gradle proporciona un mecanismo poderoso para eso : las <strong>propiedades adicionales</strong> (Extra Properties).</p> </div> <div class="sect2"> <h3 id="_paso_1_comprender_extrapropertiesextension">Paso 1: Comprender ExtraPropertiesExtension</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`es un contenedor clave-valor adjunto a cada objeto del modelo Gradle. Permite agregar propiedades de forma dinámica a un proyecto, una tarea o cualquier otra extensión Gradle.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/extra-properties-architecture.svg" alt="extra properties architecture" width="533" height="436"> </div> </div> </div> <div class="sect2"> <h3 id="_paso_2_configuración_de_la_prueba_preparación">Paso 2: Configuración de la prueba - Preparación</h3> <div class="paragraph"> <p>Comencemos por crear la estructura básica de nuestra prueba unitaria :</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Structure de base</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File @Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Suite des étapes... } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_paso_3_inyección_de_la_propiedad">Paso 3: Inyección de la Propiedad</h3> <div class="paragraph"> <p>Este es el proceso detallado para inyectar la propiedad en el proyecto de prueba:</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Injection complète</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé en mémoire val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Étape 2 : Récupérer le gestionnaire de propriétés supplémentaires val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) // Étape 3 : Définir la propriété requise pour ce test extra.set("site_config_path", "src/jbake/settings/site.yml") // Étape 4 : Vérifier que la propriété est bien injectée assertTrue(project.hasProperty("site_config_path")) // Étape 5 : Appliquer le plugin qui pourra maintenant accéder à la propriété project.plugins.apply("jbake.ghpages") // Étape 6 : Exécuter la tâche et vérifier son comportement val task: Task = project.tasks.findByName("initialize") .apply(::assertNotNull)!! // Étape 7 : Exécuter les actions de la tâche task.actions.forEach { it.execute(task) } // Étape 8 : Assertions finales assertEquals( "src/jbake/settings/site.yml", project.properties["site_config_path"], "La propriété devrait être accessible dans le projet" ) }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_paso_4_diagrama_de_flujo_de_la_solución">Paso 4 : Diagrama de flujo de la solución</h3> <div class="imageblock"> <div class="content"> <img src="./images/solution-flow.svg" alt="solution flow" width="242" height="807"> </div> </div> </div> <div class="sect2"> <h3 id="_paso_5_comparación_antesdespués">Paso 5 : Comparación Antes/Después</h3> <div class="imageblock"> <div class="content"> <img src="./images/before-after-comparison.svg" alt="before after comparison" width="1191" height="5759"> </div> </div> </div> <div class="sect2"> <h3 id="_paso_6_gestión_de_los_casos_de_prueba_multiples">Paso 6 : Gestión de los casos de prueba multiples</h3> <div class="paragraph"> <p>Para probar diferentes escenarios, creemos varias pruebas con configuraciones variadas :</p> </div> <div class="listingblock"> <div class="title">Tests multiples avec configurations différentes</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File private fun createProjectWithProperty(propertyValue: String?): Project { val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Injection conditionnelle de la propriété propertyValue?.let { value -> val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) extra.set("site_config_path", value) } return project } @Test fun `should work with valid property`() { val project = createProjectWithProperty("src/jbake/settings/site.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! task.actions.forEach { it.execute(task) } // Assertions pour le cas normal assertEquals("src/jbake/settings/site.yml", project.properties["site_config_path"]) } @Test fun `should handle missing property gracefully`() { val project = createProjectWithProperty(null) // Pas de propriété project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Le plugin devrait gérer l'absence de propriété assertDoesNotThrow { task.actions.forEach { it.execute(task) } } } @Test fun `should handle invalid property path`() { val project = createProjectWithProperty("invalid/path/to/config.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Test du comportement avec un chemin invalide assertThrows<FileNotFoundException> { task.actions.forEach { it.execute(task) } } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_arquitectura_final_de_la_solución">Arquitectura Final de la Solución</h3> <div class="imageblock"> <div class="content"> <img src="./images/final-architecture.svg" alt="final architecture" width="754" height="631"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_las_ventajas_de_este_enfoque">Las ventajas de este enfoque</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Aislamiento completo</strong>El test no depende de ningún archivo externo. Es autónomo y puede ejecutarse de manera fiable en cualquier entorno (local, CI/CD, etc.).</p> </li> <li> <p><strong>Claridad y intención</strong>: El test declara explícitamente los requisitos previos para su ejecución. Cualquiera que lea el test ve inmediatamente que el plugin requiere la propiedad`site_config_path`para funcionar.</p> </li> <li> <p><strong>mantenibilidad</strong>: Si el nombre de la propiedad cambia, basta con actualizarlo en un solo lugar en la prueba, sin tener que manipular archivos de configuración de prueba.</p> </li> <li> <p><strong>Flexibilidad</strong>Resulta trivial probar diferentes escenarios cambiando simplemente el valor de la propiedad inyectada en cada prueba (valor válido, inválido, ausente, etc.).</p> </li> <li> <p><strong>Rendimiento</strong>: No se lee ningún archivo, todo ocurre en memoria, lo que hace que las pruebas sean más rápidas.</p> </li> <li> <p><strong>Reproducibilidad</strong>Las pruebas son deterministas porque no dependen del estado del sistema de archivos.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas_y_consejos">Buenas Prácticas y Consejos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_crear_un_método_utilitario">Crear un Método Utilitario</h3> <div class="listingblock"> <div class="title">Méthode utilitaire pour la réutilisation</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GradleTestUtils { companion object { fun createProjectWithProperties( projectDir: File, properties: Map<String, String> ): Project { val project = ProjectBuilder.builder() .withProjectDir(projectDir) .build() val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) properties.forEach { (key, value) -> extra.set(key, value) } return project } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_validación_de_las_propiedades">Validación de las Propiedades</h3> <div class="listingblock"> <div class="title">Validation robuste</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `should validate property injection`() { val project = createProjectWithProperty("test-value") // Vérifications multiples assertTrue(project.hasProperty("site_config_path")) assertEquals("test-value", project.property("site_config_path")) assertNotNull(project.properties["site_config_path"]) // Vérification que la propriété est accessible par le plugin project.plugins.apply("jbake.ghpages") // ... reste du test }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>En lugar de luchar por hacer que un entorno de prueba unitaria lea archivos de configuración, la mejor práctica consiste en simular el estado requerido. El uso de`ExtraPropertiesExtension`para definir mediante programación las propiedades de Gradle es el método más limpio y robusto para realizar pruebas unitarias de plugins eficaces y fiables.</p> </div> <div class="paragraph"> <p>Esta técnica transforma un problema de dependencia externa en una simple inyección de dependencia, en el corazón mismo de la filosofía del Desarrollo Dirigido por Pruebas (TDD). Ofrece un control total sobre el entorno de prueba manteniendo el aislamiento necesario para pruebas unitarias de calidad.</p> </div> <div class="paragraph"> <p>Los diagramas y ejemplos presentados en este artículo muestran cómo este enfoque puede llevarse a cabo de manera progresiva y metódica, permitiendo crear una suite de pruebas robusta y mantenible para sus plugins de Gradle.</p> </div> </div> </div> https://cheroliv.com//blog/2025/0079_gradle_tasks_tests_report_post.html Fri, 11 Jul 2025 00:00:00 +0000 blog/2025/0079_gradle_tasks_tests_report_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_centralizar_las_configuraciones_con_allprojects_y_subprojects">Centralizar las Configuraciones con <code>allprojects</code> y `subprojects</a></li> <li><a href="#_sourceplantuml">[source,plantuml]</a></li> <li><a href="#_enduml">@enduml</a></li> <li><a href="#_sourcekotlin">[source,kotlin]</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>La automatización de las tareas de build es crucial para cualquier proyecto de software, y Gradle, con su DSL Kotlin, ofrece una flexibilidad excepcional. Durante nuestra conversación, hemos explorado cómo centralizar y reutilizar la lógica de build, especialmente para los informes de pruebas, aprovechando<strong>allprojects</strong>, <strong>buildSrc</strong>, y tareas personalizadas en Kotlin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_centralizar_las_configuraciones_con_allprojects_y_subprojects">Centralizar las Configuraciones con <code>allprojects</code> y `subprojects</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los bloques`allprojects` et `subprojects`en su`build.gradle.kts`raíz son fundamentales para aplicar configuraciones comunes a lo largo de su proyecto de múltiples módulos.</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: Aplica la configuración a<strong>proyecto raíz y a todos sus subproyectos</strong>. Ideal para definir un`group`, una`version`, o unos`repositories`comunes. *<code>subprojects { …​ }</code>: Aplicar la configuración<strong>únicamente a los subproyectos</strong>, excluyendo el proyecto raíz. Perfecto para aplicar plugins específicos a los módulos (como`java` ou <code>kotlin-jvm</code>) o las dependencias comunes de tus bibliotecas.</p> </div> <div class="paragraph"> <p>Este es un ejemplo ilustrativo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// build.gradle.kts (projet racine) plugins { base // Appliqué au projet racine } allprojects { group = "com.example" version = "1.0.0" repositories { mavenCentral() } tasks.withType<org.gradle.api.tasks.testing.Test> { useJUnitPlatform() // Configuration commune des tests pour tous les projets } } subprojects { apply(plugin = "java") apply(plugin = "org.jetbrains.kotlin.jvm") dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") } }</code></pre> </div> </div> <div class="paragraph"> <p>\== `buildSrc`El Cuchillo Suizo de la Lógica de Build</p> </div> <div class="paragraph"> <p>Cuando la lógica de tus tareas se vuelve compleja o debe ser reutilizada,<strong>buildSrc</strong>es la solución preferida. Es un módulo Gradle especial que se compila antes de los scripts de compilación principales, haciendo que sus clases estén disponibles en el classpath de todo tu build.</p> </div> <div class="paragraph"> <p>\=== ¿Por qué utilizar?`buildSrc`para las Tareas?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Reutilizabilidad</strong>Una tarea definida en`buildSrc`Puede ser aplicada a cualquier proyecto del build.</p> </li> <li> <p><strong>Organización</strong>: Centraliza el código de construcción, haciéndolo más limpio y mantenible.</p> </li> <li> <p><strong>Type Safety y autocompletado</strong>: El código Kotlin en`buildSrc`está compilado, ofreciendo la verificación de errores y el autocompletado de tu IDE, mejorando la experiencia de desarrollo.</p> </li> </ul> </div> <div class="paragraph"> <p>\=== Diagrama de flujo`buildSrc`(Código PlantUML)</p> </div> <div class="paragraph"> <p>Para generar este diagrama, copie el código a continuación y péguelo en una herramienta que admita PlantUML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourceplantuml">[source,plantuml]</h2> <div class="sectionbody"> <div class="paragraph"> <p>@startuml skinparam handwritten true skinparam monocromo verdadero</p> </div> <div class="paragraph"> <p>rectángulo "Gradle Build Process" { componente "buildSrc" como BS { file "MyCustomTask.kt" as T archivo "MyConventionPlugin.kt" como P } componente "Root Project" como RP componente "Subproject A" como SA componente "Subproject B" como SB }</p> </div> <div class="paragraph"> <p>T --\> P : "está definido en P --\> RP : "se aplica a P --\> SA : "se aplica a P --\> SB : "se aplica a</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contiene RP --|\> SB : "contiene</p> </div> <div class="paragraph"> <p>RP -up-\> BS : "depende de (para la lógica de compilación) SA -up-\> BS : "depende de (para la lógica de compilación) SB -up-\> BS : "depende de (para la lógica de compilación)</p> </div> <div class="paragraph"> <p>nota a la derecha de T Clases de tareas personalizadas ejemplo: `OpenTestReportTask nota final</p> </div> <div class="paragraph"> <p>nota a la derecha de P Plugins de convención que registran las tareas nota final</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>\== Creación de Tareas de Reporte Abstractas</p> </div> <div class="paragraph"> <p>Para gestionar los informes de pruebas, hemos diseñado un enfoque modular utilizando una clase de tarea abstracta en`buildSrc`. Según sus necesidades, esta clase puede heredar de`DefaultTask` ou de <code>Exec</code>.</p> </div> <div class="paragraph"> <p>\=== Tarea abstracta`OpenTestReportTask`(heredando de`DefaultTask`)</p> </div> <div class="paragraph"> <p>Este enfoque se recomienda si necesita una lógica personalizada de Kotlin que interactúe con el sistema de archivos o con otras API de Gradle y luego ejecute un comando externo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>paquete com.yourpackage</p> </div> <div class="paragraph"> <p>import org.gradle.api.DefaultTask import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction import java.io.File</p> </div> <div class="paragraph"> <p>abstract class OpenTestReportTask : DefaultTask()</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- init { group = "verification" description = "Opens a test report in Firefox." dependsOn("check") // Assure que les rapports sont générés } @get:Input abstract var reportPath: String @TaskAction fun openReport() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportPath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } project.exec { commandLine("firefox", "--new-tab", reportFile.absolutePath) } logger.lifecycle("Opened test report: ${reportFile.absolutePath}") } ---- ## } \=== Implementaciones Concretas Estas clases heredan de la tarea abstracta y definen la ruta específica del informe. ## [source,kotlin] package com.yourpackage clase abstracta ReportUnitTestsTask : OpenTestReportTask() { init { description = "Abre el informe de pruebas unitarias en Firefox. reportPath = "build/reports/tests/test/index.html } } paquete com.yourpackage abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "Abre el informe de pruebas funcionales en Firefox." reportPath = "build/reports/tests/functionalTest/index.html" } } \=== Registro de las Tareas En el`build.gradle.kts`de tu proyecto raíz : ## [source,kotlin] tasks.register\<com.yourpackage.ReportUnitTestsTask\>("reportTests") {} tasks.register\<com.yourpackage.ReportFunctionalTestsTask\>("reportFunctionalTests") {} \=== Diagrama UML de las Tareas de Informe (Código PlantUML) Copie el código a continuación y péguelo en una herramienta que soporte PlantUML. [source,plantuml] @startuml skinparam handwritten true skinparam monochrome true clase abstracta DefaultTask { } clase abstracta Exec { \+ commandLine(args: String...) \+ exec() } abstract class OpenTestReportTask extends DefaultTask { \+ grupo: String = "verificación \+ descripción: String \+ dependsOn("check") \+ abstract reportPath: Cadena \+ openReport() : void } clase abstracta AbstractJbakeExecTask extends Exec { \+ group: String = "verification \+ description: String \+ dependsOn("check") \+ abstract reportRelativePath: String + exec() : void } class ReportUnitTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/test/index.html } class ReportFunctionalTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/functionalTest/index.html } class ReportJbakeTestsTask extends AbstractJbakeExecTask { + reportRelativePath: String = "build/reports/tests/test/index.html } class ReportJbakeFunctionalTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/functionalTest/index.html } OpenTestReportTask \<-- ReportUnitTestsTask OpenTestReportTask \<-- ReportFunctionalTestsTask AbstractJbakeExecTask \<-- ReportJbakeTestsTask AbstractJbakeExecTask \<-- ReportJbakeFunctionalTestsTask DefaultTask <|-- OpenTestReportTask Exec \<|-- AbstractJbakeExecTask DefaultTask \<|-- Ejecutar ## @enduml \== Tarea Abstracta`AbstractJbakeExecTask`(heredando de`Exec`) Si tu tarea se resume principalmente a ejecutar un comando externo con argumentos variables, heredar directamente de**Ejecutar**es más directo. ## [source,kotlin] paquete com.yourpackage import org.gradle.api.tasks.Exec import org.gradle.api.tasks.Input import java.io.File abstract class AbstractJbakeExecTask : Exec() { ---- init { group = "verification" description = "Opens a Jbake project report in Firefox." dependsOn("check") } @get:Input abstract var reportRelativePath: String override fun exec() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportRelativePath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } commandLine("firefox", "--new-tab", reportFile.absolutePath) logger.lifecycle("Attempting to open report: ${reportFile.absolutePath}") super.exec() // Appelle la méthode exec() de la super-classe Exec } ## } Implementaciones Concretas para`Exec` [source,kotlin] ---- ----</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html Wed, 9 Jul 2025 00:00:00 +0000 blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_objetivo">Objetivo</a></li> <li><a href="#_configuración_declarativa">Configuración declarativa</a></li> <li><a href="#_arquitectura_del_plugin">Arquitectura del plugin</a></li> <li><a href="#_definición_de_la_extensión_dsl">Definición de la extensión DSL</a></li> <li><a href="#_definición_de_la_tarea_personalizada">Definición de la tarea personalizada</a></li> <li><a href="#_interfaz_gitadapter">Interfaz GitAdapter</a></li> <li><a href="#_implementación_concreta_con_jgit">Implementación concreta con JGit</a></li> <li><a href="#_configuration_dsl_kotlin">Configuration DSL Kotlin</a></li> <li><a href="#_tests_unitarios_con_mockito">Tests unitarios con Mockito</a> <ul class="sectlevel2"> <li><a href="#_dependencias">Dependencias</a></li> <li><a href="#_prueba_del_comportamiento_git">Prueba del comportamiento Git</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_próximos_pasos">Próximos pasos</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Este artículo presenta el proceso completo de diseño y pruebas (TDD) de un plugin Gradle escrito en Kotlin DSL. Este plugin automatiza la generación de sitios estáticos con <strong>JBake</strong> y el <strong>despliegue Git</strong> mediante <strong>JGit</strong>, todo a partir de un archivo de configuración YAML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivo">Objetivo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Crear un plugin Gradle :</p> </div> <div class="ulist"> <ul> <li> <p>configurable en el DSL de Kotlin;</p> </li> <li> <p>capaz de :</p> </li> <li> <p>generar un sitio estático a partir de JBake ;</p> </li> <li> <p>desplegar en un repositorio Git remoto mediante JGit ;</p> </li> <li> <p>integrable en un flujo de trabajo CI/CD ;</p> </li> <li> <p>probado según un enfoque TDD.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_configuración_declarativa">Configuración declarativa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aquí tiene un ejemplo de configuración YAML para modelar en nuestro DSL:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/trainings.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com"</code></pre> </div> </div> <div class="paragraph"> <p>Esta configuración se representa mediante una extensión Gradle declarable en DSL de Kotlin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_del_plugin">Arquitectura del plugin</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-class-diagram.png" alt="jbake asciidoctor class diagram" width="568" height="261"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definición_de_la_extensión_dsl">Definición de la extensión DSL</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">open class WorkspaceEngineExtension { var outputDir: String = "build/site" var template: String = "freemarker" var repoUrl: String = "" var branch: String = "main" var message: String = "Generated by engine" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definición_de_la_tarea_personalizada">Definición de la tarea personalizada</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class GenerateSiteTask : DefaultTask() { lateinit var gitAdapter: GitAdapter @get:Input abstract val repoUrl: Property<String> @get:InputDirectory abstract val outputDir: DirectoryProperty @get:Input abstract val branch: Property<String> @get:Input abstract val message: Property<String> @TaskAction fun run() { val repo = gitAdapter.cloneRepository(repoUrl.get(), outputDir.get().asFile) gitAdapter.commitAndPush(repo, branch.get(), message.get()) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_interfaz_gitadapter">Interfaz GitAdapter</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">interface GitAdapter { fun cloneRepository(uri: String, directory: File): Repository fun commitAndPush(repo: Repository, branch: String, message: String) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implementación_concreta_con_jgit">Implementación concreta con JGit</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JGitAdapter : GitAdapter { override fun cloneRepository(uri: String, directory: File): Repository { return Git.cloneRepository() .setURI(uri) .setDirectory(directory) .call() .repository } override fun commitAndPush(repo: Repository, branch: String, message: String) { Git(repo).use { it.add().addFilepattern(".").call() it.commit().setMessage(message).call() it.push().call() } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuration_dsl_kotlin">Configuration DSL Kotlin</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">workspaceEngine { outputDir = "build/out" template = "freemarker" repoUrl = "https://github.com/cheroliv/trainings.git" branch = "main" message = "deploy from plugin" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tests_unitarios_con_mockito">Tests unitarios con Mockito</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dependencias">Dependencias</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">testImplementation("org.mockito:mockito-core:5.12.0") testImplementation("org.mockito.kotlin:mockito-kotlin:5.2.1") testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_prueba_del_comportamiento_git">Prueba del comportamiento Git</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GenerateSiteTaskMockitoTest { @TempDir lateinit var tempDir: File @Test fun `task should call clone and commitAndPush`() { val project = ProjectBuilder.builder().build() val task = project.tasks.create("generateSite", GenerateSiteTask::class.java) val mockGitAdapter = mock<GitAdapter>() val mockRepo = mock<Repository>() whenever(mockGitAdapter.cloneRepository(any(), any())).thenReturn(mockRepo) task.gitAdapter = mockGitAdapter task.repoUrl.set("https://github.com/cheroliv/test.git") task.outputDir.set(project.layout.projectDirectory.dir(tempDir.name)) task.branch.set("main") task.message.set("test commit") task.run() verify(mockGitAdapter).cloneRepository(eq("https://github.com/cheroliv/test.git"), any()) verify(mockGitAdapter).commitAndPush(eq(mockRepo), eq("main"), eq("test commit")) } }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-sequence-diagram.png" alt="jbake asciidoctor sequence diagram" width="821" height="326"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>La separación de responsabilidades vía`GitAdapter`permite aplicar plenamente el TDD en el desarrollo de plugin Gradle :</p> </div> <div class="ulist"> <ul> <li> <p>las llamadas Git son abstractas y testables;</p> </li> <li> <p>la configuración DSL es clara y limpia ;</p> </li> <li> <p>el plugin sigue siendo agnóstico de la implementación real.</p> </li> </ul> </div> <div class="paragraph"> <p>Este enfoque asegura una alta testabilidad y extensibilidad (hacia GitHub API, GitLab, etc.).</p> </div> </div> </div> <div class="sect1"> <h2 id="_próximos_pasos">Próximos pasos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Integrar la generación JBake como un`BakeAdapter`</p> </li> <li> <p>Agregar pruebas de integración con`GradleRunner`</p> </li> <li> <p>Soporte la carga automática de archivos`site.yml`a través de SnakeYAML</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2025/0077_asciidoc_syntaxe_post.html Fri, 20 Jun 2025 00:00:00 +0000 blog/2025/0077_asciidoc_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_qué_es_asciidoc">¿Qué es AsciiDoc?</a> <ul class="sectlevel2"> <li><a href="#_por_qué_elegir_asciidoc">¿Por qué elegir AsciiDoc?</a></li> </ul> </li> <li><a href="#_diagrama_de_casos_de_uso_use_case">Diagrama de casos de uso (Use Case)</a></li> <li><a href="#_diagrama_de_mapa_mental">Diagrama de mapa mental</a></li> <li><a href="#_diagrama_de_flujo_flujo">Diagrama de flujo (flujo)</a></li> <li><a href="#_estructura_básica_de_un_archivo_asciidoc">Estructura básica de un archivo AsciiDoc</a></li> <li><a href="#_sintaxis_fundamental">Sintaxis fundamental</a> <ul class="sectlevel2"> <li><a href="#_títulos_y_secciones">Títulos y secciones</a></li> <li><a href="#_texto_en_negrita_cursiva_y_monoespaciado">Texto en negrita, cursiva y monoespaciado</a></li> <li><a href="#_listas_con_viñetas_y_numeradas">Listas con viñetas y numeradas</a></li> <li><a href="#_liens_et_images">Liens et images</a></li> <li><a href="#_bloques_de_código">Bloques de código</a></li> <li><a href="#_tablas">Tablas</a></li> <li><a href="#_notas_y_amonestaciones">Notas y amonestaciones</a></li> </ul> </li> <li><a href="#_uso_de_atributos_y_variables">Uso de atributos y variables</a></li> <li><a href="#_casos_de_uso_comunes">Casos de uso comunes</a></li> <li><a href="#_buenas_prácticas">Buenas prácticas</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_para_ir_más_lejos">Para ir más lejos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Público objetivo :</em> Desarrolladores, redactores técnicos y toda persona que desee redactar documentación técnica o artículos ricos.</div> <p>AsciiDoc es un lenguaje de marcado ligero, diseñado para redactar documentos técnicos estructurados, artículos, libros o incluso presentaciones. Se distingue por su legibilidad, su riqueza sintáctica y su capacidad para generar diversos formatos (HTML, PDF, DocBook, etc.). En este artículo, vamos a explorar la sintaxis esencial de AsciiDoc y ofrecer consejos para una introducción rápida.</p> </div> </div> </div> <div class="sect1"> <h2 id="_qué_es_asciidoc">¿Qué es AsciiDoc?</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc es un lenguaje de descripción de documentos, similar a Markdown pero más potente. Permite estructurar eficientemente textos, títulos, listas, tablas, bloques de código, y mucho más. Su versatilidad lo convierte en una opción popular para la documentación de proyectos de código abierto, la redacción de libros y la publicación web.</p> </div> <div class="sect2"> <h3 id="_por_qué_elegir_asciidoc">¿Por qué elegir AsciiDoc?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Sintaxis legible e intuitiva.</p> </li> <li> <p>Soporte nativo de estructuras complejas (tablas, notas, admoniciones, etc.).</p> </li> <li> <p>Generación multi-formato (HTML, PDF, ePub, DocBook…).</p> </li> <li> <p>Integración fácil con generadores de sitios estáticos como JBake o Antora.</p> </li> <li> <p>Personalización avanzada con los atributos y extensiones.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrama_de_casos_de_uso_use_case">Diagrama de casos de uso (Use Case)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un diagrama de caso de uso permite presentar las interacciones principales entre los usuarios y el sistema. Aquí tiene un ejemplo sencillo para un sistema de documentación:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-381f40e6e0660c0c53433ff054330b76.png" alt="Diagram" width="423" height="258"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrama_de_mapa_mental">Diagrama de mapa mental</h2> <div class="sectionbody"> <div class="paragraph"> <p>El mind map (mapa mental) es ideal para explorar los conceptos relacionados con AsciiDoc y sus relaciones :</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e1560e9cc014158b6fbeed1e5ad8e138.png" alt="Diagram" width="394" height="527"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrama_de_flujo_flujo">Diagrama de flujo (flujo)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un diagrama de flujo permite describir el proceso de generación de un documento AsciiDoc:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-51318d77b9e18062d3a9b751587670ae.png" alt="Diagram" width="299" height="361"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estructura_básica_de_un_archivo_asciidoc">Estructura básica de un archivo AsciiDoc</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un archivo AsciiDoc suele comenzar con un título, atributos opcionales y luego el contenido estructurado. Aquí tiene un ejemplo mínimo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre Principal Auteur 2024-09-03 :toc: :icons: font Votre contenu commence ici...</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_sintaxis_fundamental">Sintaxis fundamental</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_títulos_y_secciones">Títulos y secciones</h3> <div class="paragraph"> <p>AsciiDoc admite varios niveles de títulos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre de niveau 1 == Titre de niveau 2 === Titre de niveau 3 ==== Titre de niveau 4</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_texto_en_negrita_cursiva_y_monoespaciado">Texto en negrita, cursiva y monoespaciado</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">*gras* _italique_ `monospace`</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_listas_con_viñetas_y_numeradas">Listas con viñetas y numeradas</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* Élément 1 * Élément 2 . Premier . Deuxième . Troisième</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_liens_et_images">Liens et images</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">Lien standard : https://asciidoc.org[AsciiDoc] Image : image::images/logo.png[AsciiDoc Logo]</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_bloques_de_código">Bloques de código</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">[source,python]</code></pre> </div> </div> <div class="paragraph"> <p>def hello(): print("Bonjour AsciiDoc !")</p> </div> </div> <div class="sect2"> <h3 id="_tablas">Tablas</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">|=== | Colonne 1 | Colonne 2 | Valeur A | Valeur B | Valeur C | Valeur D |===</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_notas_y_amonestaciones">Notas y amonestaciones</h3> <div class="paragraph"> <p>AsciiDoc propone bloques de información visual:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">NOTE: Ceci est une note importante. TIP: Conseil utile pour l’utilisateur. WARNING: Attention à ce point.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_uso_de_atributos_y_variables">Uso de atributos y variables</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los atributos personalizados permiten reutilizar valores o configurar comportamientos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:project-name: AsciiDoc Explorer Le projet s’appelle {project-name}.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casos_de_uso_comunes">Casos de uso comunes</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentación de proyecto de código abierto (README, guías técnicas) - Redacción de libros y ebooks - Generación automática de sitios web estáticos (JBake, Antora) - Presentaciones técnicas</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas">Buenas prácticas</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Utilice títulos coherentes y un índice automático (:toc:). - Prefiera las advertencias para llamar la atención sobre puntos clave. - Structure tus archivos para facilitar el mantenimiento. - Aprovecha los bloques de código anotados para ilustrar ejemplos.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc es una herramienta potente y accesible para redactar cualquier documentación técnica o artículo estructurado. Su sintaxis rica, combinada con la generación de múltiples formatos, lo convierte en un aliado de elección para desarrolladores y redactores exigentes. Prueba AsciiDoc en tu próximo proyecto y descubre la diferencia!</p> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentation oficial : <a href="https://asciidoc.org" class="bare">https://asciidoc.org</a> - Asciidoctor : <a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - JBake et AsciiDoc : <a href="https://jbake.org/docs/2.6.4/#asciidoc_support" class="bare">https://jbake.org/docs/2.6.4/#asciidoc_support</a></p> </li> </ul> </div> <div class="paragraph"> <p>Comparte tus experiencias y consejos en los comentarios !</p> </div> </div> </div> https://cheroliv.com//blog/2025/0076_port_forwarding_post.html Wed, 28 May 2025 00:00:00 +0000 blog/2025/0076_port_forwarding_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_el_problema_nat_y_direcciones_privadas">El problema: NAT y direcciones privadas</a></li> <li><a href="#_paso_1_identificar_tu_dirección_ip_pública">Paso 1: Identificar tu dirección IP pública</a></li> <li><a href="#_paso_2_conocer_la_dirección_ip_local_de_tu_máquina_ubuntu">Paso 2: Conocer la dirección IP local de tu máquina Ubuntu</a></li> <li><a href="#_paso_3_configurar_el_reenvío_de_puertos_en_su_router">Paso 3: Configurar el reenvío de puertos en su router</a> <ul class="sectlevel2"> <li><a href="#_acceso_a_la_interfaz_de_administración">Acceso a la interfaz de administración</a></li> <li><a href="#_configuración_de_la_redirección">Configuración de la redirección</a></li> </ul> </li> <li><a href="#_paso_4_configuración_del_servicio_en_ubuntu">Paso 4: Configuración del servicio en Ubuntu</a></li> <li><a href="#_paso_5_configuración_del_firewall_ubuntu">Paso 5: Configuración del firewall Ubuntu</a></li> <li><a href="#_paso_6_prueba_y_validación">Paso 6: Prueba y validación</a> <ul class="sectlevel2"> <li><a href="#_prueba_desde_la_red_local">Prueba desde la red local</a></li> <li><a href="#_prueba_desde_el_exterior">Prueba desde el exterior</a></li> </ul> </li> <li><a href="#_buenas_prácticas_y_seguridad">Buenas prácticas y seguridad</a> <ul class="sectlevel2"> <li><a href="#_seguridad_básica">Seguridad básica</a></li> <li><a href="#_monitoreo_de_las_conexiones">Monitoreo de las conexiones</a></li> <li><a href="#_uso_de_un_proxy_inverso">Uso de un proxy inverso</a></li> </ul> </li> <li><a href="#_alternativas_al_reenvío_de_puertos">Alternativas al reenvío de puertos</a> <ul class="sectlevel2"> <li><a href="#_soluciones_en_la_nube">Soluciones en la nube</a></li> <li><a href="#_vps_y_reverse_proxy">VPS y reverse proxy</a></li> </ul> </li> <li><a href="#_solución_de_problemas">Solución de problemas</a> <ul class="sectlevel2"> <li><a href="#_problemas_comunes">Problemas comunes</a></li> <li><a href="#_depuración_de_red">Depuración de red</a></li> </ul> </li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="ulist"> <div class="title">Público objetivo : Intermedio</div> <ul> <li> <p><strong>Requisitos asumidos</strong> : conocimientos básicos de Ubuntu, del terminal, conceptos básicos de redes</p> </li> <li> <p><strong>Conceptos técnicos</strong> : NAT, reenvío de puertos, cortafuegos, proxy inverso</p> </li> <li> <p><strong>Comandos de sistema</strong>: utilización del terminal, configuración de red</p> </li> <li> <p><strong>Secciones avanzadas</strong> : monitoring, seguridad, alternatives cloud</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_el_problema_nat_y_direcciones_privadas">El problema: NAT y direcciones privadas</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Problemática : ¿Estás desarrollando una aplicación web en tu máquina Ubuntu y deseas que sea accesible desde fuera de tu red doméstica? ¡Estás en el lugar correcto! En este artículo veremos cómo exponer un servicio local (por ejemplo en el puerto 8080) a Internet mediante la configuración del reenvío de puertos en tu caja de internet.</div> <p>Por defecto, tu router de internet utiliza el NAT (Network Address Translation) para compartir una única dirección IP pública entre todos los dispositivos de tu red doméstica. Tus máquinas locales utilizan direcciones IP privadas (192.168.x.x, 10.x.x.x, etc.) que no son enrutables en Internet.</p> </div> <div class="paragraph"> <p>Cuando inicias un servicio en tu máquina Ubuntu (por ejemplo, un servidor web en el puerto 8080), solo es accesible desde tu red local. Para hacerlo accesible desde Internet, debemos configurar una redirección de puertos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_1_identificar_tu_dirección_ip_pública">Paso 1: Identificar tu dirección IP pública</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de todo, obtengamos la dirección IP pública de tu conexión a Internet :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Plusieurs méthodes au choix curl ifconfig.me curl ipecho.net/plain wget -qO- http://ipecho.net/plain # Ou encore curl -s checkip.amazonaws.com</code></pre> </div> </div> <div class="paragraph"> <p>Esta dirección IP es la que los internautas utilizarán para acceder a su servicio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_2_conocer_la_dirección_ip_local_de_tu_máquina_ubuntu">Paso 2: Conocer la dirección IP local de tu máquina Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Su máquina Ubuntu tiene una dirección IP privada en su red local. Para conocerla :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Afficher toutes les interfaces réseau ip addr show # Ou plus spécifiquement pour l'interface principale ip route get 1.1.1.1 | awk '{print $7; exit}' # Alternative avec hostname hostname -I | awk '{print $1}'</code></pre> </div> </div> <div class="paragraph"> <p>Anote esta dirección (por ejemplo`192.168.1.100`), lo necesitaremos para la configuración.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_3_configurar_el_reenvío_de_puertos_en_su_router">Paso 3: Configurar el reenvío de puertos en su router</h2> <div class="sectionbody"> <div class="paragraph"> <p>La configuración varía según el modelo de tu box, pero el principio permanece el mismo :</p> </div> <div class="sect2"> <h3 id="_acceso_a_la_interfaz_de_administración">Acceso a la interfaz de administración</h3> <div class="paragraph"> <p>Abre tu navegador y ve a la interfaz web de tu box :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Freebox</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p>(Note: The output preserves the exact characters you provided, including the leading space(s) around the colon.)<code>192.168.1.1</code> ou <code>mafreebox.freebox.fr</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Livebox Orange</strong> : <code>192.168.1.1</code></p> </li> <li> <p><strong>SFR Caja</strong>:`192.168.1.1`</p> </li> <li> <p><strong>Bbox Bouygues</strong>:`192.168.1.254`</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_configuración_de_la_redirección">Configuración de la redirección</h3> <div class="paragraph"> <p>Busca la sección dedicada al port forwarding (los nombres varían):</p> </div> <div class="ulist"> <ul> <li> <p>Redirección de puertos</p> </li> <li> <p>NAT/PAT</p> </li> <li> <p>Reenvío de puertos</p> </li> <li> <p>Servidores de juegos</p> </li> </ul> </div> <div class="paragraph"> <p>Crea una nueva regla con estos parámetros:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">campo</th> <th class="tableblock halign-left valign-top">Valor</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre/Descripción</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Servicio Web Ubuntu" (o otro nombre explícito)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Puerto externo (o puerto público)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dirección IP interna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La IP de tu máquina Ubuntu (ej: 192.168.1.100)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Puerto interno (o puerto privado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">protocolo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">TCP</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Estado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Activado</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_paso_4_configuración_del_servicio_en_ubuntu">Paso 4: Configuración del servicio en Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Asegúrate de que tu servicio escuche en todas las interfaces, no solo en localhost:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># ✅ Correct : écoute sur toutes les interfaces python3 -m http.server 8080 --bind 0.0.0.0 # ❌ Incorrect : écoute seulement en local python3 -m http.server 8080 --bind 127.0.0.1</code></pre> </div> </div> <div class="paragraph"> <p>Para comprobar que su servicio escucha correctamente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier les ports en écoute sudo netstat -tlnp | grep :8080 # ou avec ss (plus moderne) sudo ss -tlnp | grep :8080</code></pre> </div> </div> <div class="paragraph"> <p>Deberías ver algo como`0.0.0.0:8080`y no`127.0.0.1:8080`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_paso_5_configuración_del_firewall_ubuntu">Paso 5: Configuración del firewall Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu utiliza UFW (Uncomplicated Firewall) por defecto. Verifique su estado y permita el puerto si es necesario:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier le statut du pare-feu sudo ufw status # Si le pare-feu est actif, autoriser le port 8080 sudo ufw allow 8080/tcp # Ou plus spécifiquement pour un service web sudo ufw allow 'Apache' # si vous utilisez Apache sudo ufw allow 'Nginx Full' # si vous utilisez Nginx</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_paso_6_prueba_y_validación">Paso 6: Prueba y validación</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prueba_desde_la_red_local">Prueba desde la red local</h3> <div class="paragraph"> <p>Primero, prueba el acceso desde otra máquina de tu red local:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par l'IP locale de votre machine Ubuntu curl http://192.168.1.100:8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_prueba_desde_el_exterior">Prueba desde el exterior</h3> <div class="paragraph"> <p>Ahora, prueba desde Internet usando tu IP pública :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par votre IP publique curl http://VOTRE_IP_PUBLIQUE:8080</code></pre> </div> </div> <div class="paragraph"> <p>También puedes utilizar herramientas en línea como :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://www.yougetsignal.com/tools/open-ports/" class="bare">https://www.yougetsignal.com/tools/open-ports/</a></p> </li> <li> <p><a href="https://canyouseeme.org/" class="bare">https://canyouseeme.org/</a></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buenas_prácticas_y_seguridad">Buenas prácticas y seguridad</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_seguridad_básica">Seguridad básica</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Configurer fail2ban pour protéger contre les attaques par force brute sudo apt update && sudo apt install fail2ban # Limiter l'accès avec UFW (exemple : autoriser seulement certaines IP) sudo ufw allow from 203.0.113.0/24 to any port 8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_monitoreo_de_las_conexiones">Monitoreo de las conexiones</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Surveiller les connexions en temps réel sudo netstat -an | grep :8080 # Logs des connexions (selon votre application) sudo tail -f /var/log/nginx/access.log # pour Nginx sudo journalctl -f -u your-service # pour un service systemd</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_uso_de_un_proxy_inverso">Uso de un proxy inverso</h3> <div class="paragraph"> <p>Para una mejor seguridad y flexibilidad, considere el uso de un reverse proxy como Nginx:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-nginx" data-lang="nginx">server { listen 80; server_name votre-domaine.com; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_alternativas_al_reenvío_de_puertos">Alternativas al reenvío de puertos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_soluciones_en_la_nube">Soluciones en la nube</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>: túnel seguro temporal</p> </li> <li> <p><strong>Cloudflare túnel</strong>solución gratuita y segura</p> </li> <li> <p><strong>serveo.net</strong>: túnel SSH simple</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Exemple avec ngrok ngrok http 8080 # Exemple avec serveo ssh -R 80:localhost:8080 serveo.net</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_vps_y_reverse_proxy">VPS y reverse proxy</h3> <div class="paragraph"> <p>Para uso profesional, considere el uso de un VPS con un proxy inverso que apunte a su infraestructura local a través de VPN.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_solución_de_problemas">Solución de problemas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_problemas_comunes">Problemas comunes</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Problema</th> <th class="tableblock halign-left valign-top">Solución</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Servicio inaccesible desde el exterior</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Verifique la configuración del reenvío de puertos y que el servicio escuche en 0.0.0.0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Conexión rechazada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El servicio no está iniciado o está escuchando solo en 127.0.0.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Timeout de conexión</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema de cortafuegos (box o Ubuntu) o reenvío de puertos mal configurado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">IP pública cambia regularmente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configure un DNS dinámico (DynDNS, No-IP, etc.).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_depuración_de_red">Depuración de red</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Tester la connectivité locale telnet localhost 8080 # Tester depuis une autre machine du réseau telnet 192.168.1.100 8080 # Vérifier les routes réseau ip route show # Analyser le trafic réseau sudo tcpdump -i any port 8080</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Exponer un servicio local en Internet requiere una configuración cuidadosa del reenvío de puertos, de la seguridad y del monitoreo. Aunque este enfoque es perfecto para el desarrollo o para proyectos personales, considere las alternativas más robustas (VPS, CDN, servicios en la nube) para un uso en producción.</p> </div> <div class="paragraph"> <p>Lo importante es siempre tener la seguridad en mente: utilice contraseñas fuertes, actualice regularmente su sistema y vigile los accesos a sus servicios expuestos.</p> </div> <div class="paragraph"> <p>¡No dudes en compartir tus experiencias y preguntas en los comentarios!</p> </div> </div> </div> https://cheroliv.com//blog/2025/0099_debugging-mockito-gradle-plugin_post.html Sun, 17 Nov 2024 00:00:00 +0000 blog/2025/0099_debugging-mockito-gradle-plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_el_contexto_plugin_gradle_bakery">El contexto : Plugin Gradle Bakery</a></li> <li><a href="#_problema_1_verificar_el_mock_incorrecto">Problema #1: Verificar el mock incorrecto</a> <ul class="sectlevel2"> <li><a href="#_el_diagnóstico">El diagnóstico</a></li> <li><a href="#_la_solución">La solución</a></li> </ul> </li> <li><a href="#_problema_2_unfinishedstubbingexception_en_cascada">Problema #2: UnfinishedStubbingException en cascada</a> <ul class="sectlevel2"> <li><a href="#_el_diagnóstico_2">El diagnóstico</a></li> <li><a href="#_la_solución_2">La solución</a></li> </ul> </li> <li><a href="#_problema_3_el_archivo_de_configuración_no_existe">Problema #3 : El archivo de configuración no existe</a> <ul class="sectlevel2"> <li><a href="#_el_diagnóstico_3">El diagnóstico</a></li> <li><a href="#_la_solución_3">La solución</a></li> </ul> </li> <li><a href="#_problema_4_afterevaluate_y_nullpointerexception">Problema #4 : afterEvaluate y NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_el_diagnóstico_4">El diagnóstico</a></li> <li><a href="#_la_solución_4">La solución</a></li> </ul> </li> <li><a href="#_la_solución_completa">La solución completa</a></li> <li><a href="#_lecciones_aprendidas">Lecciones aprendidas</a> <ul class="sectlevel2"> <li><a href="#_1_verificar_el_mock_correcto">1. Verificar el mock correcto</a></li> <li><a href="#_2_evitar_los_mocks_anidados">2. Evitar los mocks anidados</a></li> <li><a href="#_3_simular_los_callbacks_de_evaluación">3. Simular los callbacks de evaluación</a></li> <li><a href="#_4_probar_la_resolución_de_los_caminos">4. Probar la resolución de los caminos</a></li> </ul> </li> <li><a href="#_arquitectura_de_prueba_final">Arquitectura de prueba final</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante el desarrollo del plugin Gradle<strong>panadería</strong>para mi blog JBake, encontré un problema aparentemente simple: una prueba unitaria que fallaba con el error`Wanted but not invoked`. Lo que parecía ser un error trivial resultó ser un caso de estudio perfecto para comprender las sutilezas del mocking con Mockito y Kotlin.</p> </div> <div class="paragraph"> <p>En este artículo, te llevo en un viaje de depuración metódico, donde cada solución revela un nuevo problema, hasta la resolución final.</p> </div> </div> </div> <div class="sect1"> <h2 id="_el_contexto_plugin_gradle_bakery">El contexto : Plugin Gradle Bakery</h2> <div class="sectionbody"> <div class="paragraph"> <p>El plugin Bakery es un wrapper alrededor de JBake que facilita la publicación de sitios estáticos. Aquí está su estructura simplificada :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class BakeryPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "bakery", BakeryExtension::class.java ) project.afterEvaluate { if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") } else { // C'EST ICI QUE ÇA SE PASSE project.plugins.apply(JBakePlugin::class.java) val site = FileSystemManager.from(project, extension.configPath.get()) // Configuration de JBake... } } } }</code></pre> </div> </div> <div class="paragraph"> <p>La prueba que fallaba era simple :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val project = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(project.plugins).apply(JBakePlugin::class.java) }</code></pre> </div> </div> <div class="paragraph"> <p>El error :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Wanted but not invoked: pluginContainer.apply(class org.jbake.gradle.JBakePlugin); Actually, there were zero interactions with this mock.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_1_verificar_el_mock_incorrecto">Problema #1: Verificar el mock incorrecto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_diagnóstico">El diagnóstico</h3> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-1.svg" alt="mockito problem 1" width="711" height="521"> </div> </div> <div class="paragraph"> <p>El problema: Mockito no puede rastrear las interacciones en`project.plugins`porque solo es un getter que devuelve el mock real`mockPluginContainer`. La verificación debe hacerse directamente en la instancia del mock.</p> </div> </div> <div class="sect2"> <h3 id="_la_solución">La solución</h3> <div class="paragraph"> <p>Modificar`createMockProject()`para devolver los dos objetos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { val mockPluginContainer = mock<PluginContainer>() val mockProject = mock<Project> { on { plugins } doReturn mockPluginContainer } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>Y adaptar la prueba :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) // ✅ Vérification directe sur le bon mock verify(mockPluginContainer).apply(JBakePlugin::class.java) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_2_unfinishedstubbingexception_en_cascada">Problema #2: UnfinishedStubbingException en cascada</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_diagnóstico_2">El diagnóstico</h3> <div class="paragraph"> <p>Una vez aplicada la primera corrección, apareció un nuevo error:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">UnfinishedStubbingException: Unfinished stubbing detected here Hints: 3. you are stubbing the behaviour of another mock inside before 'thenReturn' instruction is completed</code></pre> </div> </div> <div class="paragraph"> <p>El código problemático utilizaba la sintaxis DSL de Mockito-Kotlin :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val mockProject = mock<Project> { on { extensions } doReturn mockExtensionContainer on { plugins } doReturn mockPluginContainer on { logger } doReturn mock() // ❌ PROBLÈME ICI ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-2.svg" alt="mockito problem 2" width="690" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_la_solución_2">La solución</h3> <div class="paragraph"> <p>Crear<strong>todos</strong>los mocks fuera de cualquier bloque de stubbing, luego configurarlos con`whenever()` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ Créer TOUS les mocks d'abord val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() // 2️⃣ Configurer les mocks séparément avec whenever() whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.logger).thenReturn(mockLogger) return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Regla de oro</strong>: Nunca llamar`mock()`dentro de un bloque de configuración de mock. Siempre cree los mocks primero, luego configúrelos.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_el_archivo_de_configuración_no_existe">Problema #3 : El archivo de configuración no existe</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_diagnóstico_3">El diagnóstico</h3> <div class="paragraph"> <p>Incluso con los mocks correctos, el test siempre fallaba porque el plugin no encontraba el archivo de configuración :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Dans BakeryPlugin.kt if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") return@afterEvaluate // ❌ Sort avant d'appliquer JBake ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-3.svg" alt="mockito problem 3" width="639" height="373"> </div> </div> </div> <div class="sect2"> <h3 id="_la_solución_3">La solución</h3> <div class="paragraph"> <p>Configurar los mocks para que la resolución del camino funcione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile // Configuration cohérente des chemins whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // Maintenant : projectDir.resolve("site.yml") existe ! ✅ }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/path-resolution.svg" alt="path resolution" width="1747" height="5592"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_afterevaluate_y_nullpointerexception">Problema #4 : afterEvaluate y NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_diagnóstico_4">El diagnóstico</h3> <div class="paragraph"> <p>El plugin aplica JBake en un bloque`afterEvaluate`, y accede a`buildDirectory.dir()`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.afterEvaluate { // ... project.tasks.withType(JBakeTask::class.java) .getByName("bake").apply { output = project.layout.buildDirectory .dir(site.bake.destDirPath) // ❌ NPE ici ! .get() .asFile } }</code></pre> </div> </div> <div class="paragraph"> <p>El mock de`buildDirectory.dir()<code>volvía`null</code>.</p> </div> </div> <div class="sect2"> <h3 id="_la_solución_4">La solución</h3> <div class="paragraph"> <p>burlar`afterEvaluate`para que se ejecute inmediatamente, y configurarlo completamente`buildDirectory`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val mockBuildDirectory = mock<DirectoryProperty>() val buildDir = File(projectDir, "build") // Mocker dir() pour retourner un Provider valide whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // Mocker afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) // ✅ Exécution synchrone null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/after-evaluate-flow.svg" alt="after evaluate flow" width="806" height="357"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solución_completa">La solución completa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aquí está la función`createMockProject()`Finalmente, que resuelve todos los problemas :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ CRÉER tous les mocks (pas de nested mocks !) val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockTaskContainer = mock<TaskContainer>() val mockConfigPathProperty = mock<Property<String>>() val mockBakeryExtension = mock<BakeryExtension>() val mockProjectDirectory = mock<Directory>() val mockBuildDirectory = mock<DirectoryProperty>() val mockProjectLayout = mock<ProjectLayout>() val mockProject = mock<Project>() // 2️⃣ CONFIGURER la résolution des chemins val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile val buildDir = File(projectDir, "build") whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockConfigPathProperty.isPresent).thenReturn(true) whenever(mockBakeryExtension.configPath).thenReturn(mockConfigPathProperty) whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // 3️⃣ CONFIGURER buildDirectory avec dir() whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // 4️⃣ ASSEMBLER le projet whenever(mockProjectLayout.projectDirectory).thenReturn(mockProjectDirectory) whenever(mockProjectLayout.buildDirectory).thenReturn(mockBuildDirectory) whenever(mockExtensionContainer.create("bakery", BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockExtensionContainer.getByType(BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.tasks).thenReturn(mockTaskContainer) whenever(mockProject.layout).thenReturn(mockProjectLayout) whenever(mockProject.logger).thenReturn(mockLogger) whenever(mockProject.projectDir).thenReturn(projectDir) // 5️⃣ CONFIGURER afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>Y la prueba final que pasa:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(mockPluginContainer).apply(JBakePlugin::class.java) // ✅ SUCCÈS ! }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lecciones_aprendidas">Lecciones aprendidas</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/lessons-learned.svg" alt="lessons learned" width="748" height="472"> </div> </div> <div class="sect2"> <h3 id="_1_verificar_el_mock_correcto">1. Verificar el mock correcto</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX verify(project.plugins).apply(JBakePlugin::class.java) // ✅ CORRECT val (project, mockPluginContainer) = createMockProject() verify(mockPluginContainer).apply(JBakePlugin::class.java)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_evitar_los_mocks_anidados">2. Evitar los mocks anidados</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX - UnfinishedStubbingException val mockProject = mock<Project> { on { logger } doReturn mock() // Nested mock creation ! } // ✅ CORRECT - Créer séparément val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() whenever(mockProject.logger).thenReturn(mockLogger)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_3_simular_los_callbacks_de_evaluación">3. Simular los callbacks de evaluación</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ✅ afterEvaluate doit s'exécuter pour les tests whenever(mockProject.afterEvaluate(any())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_probar_la_resolución_de_los_caminos">4. Probar la resolución de los caminos</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Toujours vérifier que les chemins se résolvent correctement val extension = project.extensions.getByType(BakeryExtension::class.java) val configPath = extension.configPath.get() val projectDir = project.layout.projectDirectory.asFile val resolvedConfig = projectDir.resolve(configPath) println("Resolved config: ${resolvedConfig.absolutePath}") println("Exists: ${resolvedConfig.exists()}")</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitectura_de_prueba_final">Arquitectura de prueba final</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/test-architecture.svg" alt="test architecture" width="1756" height="5468"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo que parecía ser un problema sencillo de prueba resultó ser un excelente caso de estudio sobre:</p> </div> <div class="ulist"> <ul> <li> <p>Las sutilezas de Mockito con Kotlin</p> </li> <li> <p>La importancia de mockear los objetos correctos</p> </li> <li> <p>La gestión de los callbacks asíncronos en las pruebas</p> </li> <li> <p>La resolución de rutas en los plugins de Gradle</p> </li> </ul> </div> <div class="paragraph"> <p>La depuración metódica, al comprender cada capa del problema, ha permitido llegar a una solución robusta y mantenible.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Consejo para tus pruebas</strong>: Si encuentras "Wanted but not invoked" con Mockito, pregúntese siempre : 1. ¿Estoy verificando el mock correcto? 2. ¿Se crean todos mis mocks fuera de los bloques de configuración? 3. ¿Se ejecutan realmente mis callbacks? 4. ¿Se resuelven correctamente mis caminos?</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_recursos">Recursos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/mockito/mockito-kotlin">Documentación de Mockito-Kotlin</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Guía de desarrollo de complementos de Gradle</a></p> </li> <li> <p><a href="https://jbake.org/">JBake Generador de sitios estáticos</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p>¿Has encontrado problemas similares en tus pruebas? ¡Comparte tu experiencia en los comentarios!</p> </div> </div> </div> https://cheroliv.com//blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html Tue, 24 Sep 2024 00:00:00 +0000 blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_qué_es_la_mónada_either">¿Qué es la mónada Either?</a> <ul class="sectlevel2"> <li><a href="#_por_qué_usar_either">¿Por qué usar Either?</a></li> </ul> </li> <li><a href="#_contexto">Contexto</a></li> <li><a href="#_los_diferentes_enfoques">Los diferentes enfoques</a> <ul class="sectlevel2"> <li><a href="#_el_enfoque_clásico_con_when">El enfoque clásico con `when</a></li> <li><a href="#_uso_de_fold_para_un_enfoque_más_conciso">Uso de <code>fold</code> para un enfoque más conciso</a></li> <li><a href="#_transformación_con_map_y_mapleft">Transformación con <code>map</code> y `mapLeft</a></li> <li><a href="#_gestión_de_errores_con_getorelse">Gestión de errores con `getOrElse</a></li> <li><a href="#_acciones_laterales_con_onleft_y_onright">Acciones laterales con <code>onLeft</code> y `onRight</a></li> <li><a href="#_encadenamiento_de_operaciones_con_flatmap">Encadenamiento de operaciones con `flatMap</a></li> <li><a href="#_transformación_bidireccional_con_bimap">Transformación bidireccional con `bimap</a></li> <li><a href="#_inversión_de_los_lados_con_swap">Inversión de los lados con `swap</a></li> <li><a href="#_uso_de_tap_y_tapleft">Uso de <code>tap</code> y <code>tapLeft</code> :</a></li> <li><a href="#_uso_de_recover">Uso de <code>recover</code> :</a></li> </ul> </li> <li><a href="#_casos_de_uso_prácticos">Casos de uso prácticos</a></li> <li><a href="#_conclusión">Conclusión</a></li> <li><a href="#_para_ir_más_lejos">Para ir más lejos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Público objetivo :</em> Desarrolladores Kotlin de nivel intermedio a avanzado.</div> <p>En el mundo de la programación funcional en Kotlin, la biblioteca Arrow ofrece herramientas poderosas para manejar errores y casos alternativos. Entre estas herramientas, la mónada`Either`se distingue por su capacidad para representar dos estados posibles: éxito (Right) o fracaso (Left). Pero, ¿cómo navegar eficazmente entre estos dos estados? Eso es lo que vamos a explorar en este artículo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_qué_es_la_mónada_either">¿Qué es la mónada Either?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La monada`Either`es una estructura de datos que representa dos posibilidades mutuamente excluyentes. En Kotlin con Arrow, se utiliza a menudo para manejar los casos de éxito y error de una operación, proporcionando una alternativa elegante a las excepciones tradicionales.</p> </div> <div class="sect2"> <h3 id="_por_qué_usar_either">¿Por qué usar Either?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Gestión explícita de errores: Obliga al desarrollador a considerar los casos de fallo.</p> </li> <li> <p>Composición funcional: Facilita el encadenamiento de operaciones que pueden fallar.</p> </li> <li> <p>Type-safety: Los errores están tipados, lo que ayuda a gestionarlos de manera más precisa.</p> </li> <li> <p>Sin excepciones: Evita los efectos secundarios y las interrupciones inesperadas del flujo de ejecución.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_contexto">Contexto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Imaginemos que estás desarrollando una API REST conhttps://spring.io/projects/spring-boot/[Spring Boot,windows=read-later] et <a href="https://kotlinlang.org/">Kotlin</a>, utilizando la bibliotecahttps://arrow-kt.io/[Arrow,windows=read-later]. Tienes una función`findOneUserByEmail`que devuelve un`Either<Throwable, User>`. ¿Cómo puede tratar este resultado de manera elegante y funcional ?</p> </div> <div class="paragraph"> <p>Tenemos una clase User:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@file:Suppress( "RemoveRedundantQualifierName", "MemberVisibilityCanBePrivate", "SqlNoDataSourceInspection" ) package webapp.users import arrow.core.Either import arrow.core.left import arrow.core.right import com.fasterxml.jackson.annotation.JsonIgnore import com.fasterxml.jackson.databind.ObjectMapper import jakarta.validation.constraints.NotNull import jakarta.validation.constraints.Pattern import jakarta.validation.constraints.Size import org.springframework.beans.factory.getBean import org.springframework.context.ApplicationContext import org.springframework.data.r2dbc.core.R2dbcEntityTemplate import org.springframework.r2dbc.core.DatabaseClient import org.springframework.r2dbc.core.awaitOne import org.springframework.r2dbc.core.awaitRowsUpdated import webapp.core.property.ANONYMOUS_USER import webapp.core.property.EMPTY_STRING import webapp.core.utils.AppUtils.cleanField import webapp.users.EntityModel.Companion.ID_MEMBER import webapp.users.User.UserDao.Attributes.EMAIL_ATTR import webapp.users.User.UserDao.Attributes.ID_ATTR import webapp.users.User.UserDao.Attributes.LANG_KEY_ATTR import webapp.users.User.UserDao.Attributes.LOGIN_ATTR import webapp.users.User.UserDao.Attributes.PASSWORD_ATTR import webapp.users.User.UserDao.Attributes.VERSION_ATTR import webapp.users.User.UserDao.Constraints.LOGIN_REGEX import webapp.users.User.UserDao.Fields.EMAIL_FIELD import webapp.users.User.UserDao.Fields.ID_FIELD import webapp.users.User.UserDao.Fields.LANG_KEY_FIELD import webapp.users.User.UserDao.Fields.LOGIN_FIELD import webapp.users.User.UserDao.Fields.PASSWORD_FIELD import webapp.users.User.UserDao.Fields.VERSION_FIELD import webapp.users.User.UserDao.Relations.INSERT import webapp.users.security.Role import webapp.users.security.Role.RoleDao import webapp.users.security.UserRole.UserRoleDao import java.util.* import jakarta.validation.constraints.Email as EmailConstraint data class User( override val id: UUID? = null, @field:NotNull @field:Pattern(regexp = LOGIN_REGEX) @field:Size(min = 1, max = 50) val login: String, @JsonIgnore @field:NotNull @field:Size(min = 60, max = 60) val password: String = EMPTY_STRING, @field:EmailConstraint @field:Size(min = 5, max = 254) val email: String = EMPTY_STRING, @JsonIgnore val roles: MutableSet<Role> = mutableSetOf(Role(ANONYMOUS_USER)), @field:Size(min = 2, max = 10) val langKey: String = EMPTY_STRING, @JsonIgnore val version: Long = -1, ) : EntityModel<UUID>() { companion object { @JvmStatic fun main(args: Array<String>) = println(UserDao.Relations.sqlScript) } object UserDao { object Constraints { // Regex for acceptable logins const val LOGIN_REGEX = "^(?>[a-zA-Z0-9!$&*+=?^_`{|}~.-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*)|(?>[_.@A-Za-z0-9-]+)$" const val PASSWORD_MIN: Int = 4 const val PASSWORD_MAX: Int = 16 const val IMAGE_URL_DEFAULT = "https://placehold.it/50x50" const val PHONE_REGEX = "^(\\+|00)?[1-9]\\d{0,49}\$" } object Members { const val PASSWORD_MEMBER = "password" const val ROLES_MEMBER = "roles" } object Fields { const val ID_FIELD = "`id`" const val LOGIN_FIELD = "`login`" const val PASSWORD_FIELD = "`password`" const val EMAIL_FIELD = "`email`" const val LANG_KEY_FIELD = "`lang_key`" const val VERSION_FIELD = "`version`" } object Attributes { val ID_ATTR = ID_FIELD.cleanField() val LOGIN_ATTR = LOGIN_FIELD.cleanField() val PASSWORD_ATTR = PASSWORD_FIELD.cleanField() val EMAIL_ATTR = EMAIL_FIELD.cleanField() const val LANG_KEY_ATTR = "langKey" val VERSION_ATTR = VERSION_FIELD.cleanField() } object Relations { const val TABLE_NAME = "`user`" const val SQL_SCRIPT = """ CREATE TABLE IF NOT EXISTS $TABLE_NAME ( $ID_FIELD UUID default random_uuid() PRIMARY KEY, $LOGIN_FIELD VARCHAR, $PASSWORD_FIELD VARCHAR, $EMAIL_FIELD VARCHAR, $LANG_KEY_FIELD VARCHAR, $VERSION_FIELD bigint ); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_login` ON $TABLE_NAME ($LOGIN_FIELD); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_email` ON $TABLE_NAME ($EMAIL_FIELD); """ @Suppress("SqlDialectInspection") const val INSERT = """ insert into $TABLE_NAME ( $LOGIN_FIELD, $EMAIL_FIELD, $PASSWORD_FIELD, $LANG_KEY_FIELD, $VERSION_FIELD ) values ( :login, :email, :password, :langKey, :version)""" @JvmStatic val sqlScript: String get() = setOf( UserDao.Relations.SQL_SCRIPT, RoleDao.Relations.SQL_SCRIPT, UserRoleDao.Relations.SQL_SCRIPT ).joinToString("") .trimMargin() } object Dao { val Pair<User, ApplicationContext>.toJson: String get() = second.getBean<ObjectMapper>().writeValueAsString(first) suspend fun Pair<User, ApplicationContext>.save(): Either<Throwable, Long> = try { second.getBean<R2dbcEntityTemplate>() .databaseClient .sql(INSERT) .bind(LOGIN_ATTR, first.login) .bind(EMAIL_ATTR, first.email) .bind(PASSWORD_ATTR, first.password) .bind(LANG_KEY_ATTR, first.langKey) .bind(VERSION_ATTR, first.version) .fetch() .awaitRowsUpdated() .right() } catch (e: Throwable) { e.left() } suspend fun ApplicationContext.findOneUserByEmail( email: String ): Either<Throwable, User> = try { getBean<DatabaseClient>() .sql("SELECT * FROM `user` WHERE LOWER(email) = LOWER(:email)") .bind("email", email) .fetch() .awaitOne() .let { row -> User( id = row[ID_ATTR] as UUID?, login = row[LOGIN_ATTR] as String, password = row[PASSWORD_ATTR] as String, email = row[EMAIL_ATTR] as String, langKey = row[LANG_KEY_ATTR] as String, version = row[VERSION_ATTR] as Long ) }.right() } catch (e: Throwable) { e.left() } } } /** Account REST API URIs */ object UserRestApis { const val API_AUTHORITY = "/api/authorities" const val API_USERS = "/api/users" const val API_SIGNUP = "/signup" const val API_SIGNUP_PATH = "$API_USERS$API_SIGNUP" const val API_ACTIVATE = "/activate" const val API_ACTIVATE_PATH = "$API_USERS$API_ACTIVATE?key=" const val API_ACTIVATE_PARAM = "{activationKey}" const val API_ACTIVATE_KEY = "key" const val API_RESET_INIT = "/reset-password/init" const val API_RESET_FINISH = "/reset-password/finish" const val API_CHANGE = "/change-password" const val API_CHANGE_PATH = "$API_USERS$API_CHANGE" } } // Abstract entity model with Generic ID, which can be of any type abstract class EntityModel<T>( open val id: T? = null ) { companion object { const val ID_MEMBER = "id" } } // Generic extension function that allows the ID to be applied to any EntityModel type inline fun <reified T : EntityModel<ID>, ID> T.withId(id: ID): T { // Use reflection to create a copy with the passed ID return this::class.constructors.first { it.parameters.any { param -> param.name == ID_MEMBER } } .call(id, *this::class.constructors.first().parameters.drop(1).map { param -> this::class.members.first { member -> member.name == param.name }.call(this) }.toTypedArray()) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_los_diferentes_enfoques">Los diferentes enfoques</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_el_enfoque_clásico_con_when">El enfoque clásico con `when</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user: User by lazy { userFactory(USER) } val result: Either<Throwable, User> = context.findOneUserByEmail(user.email) when (result) { is Either.Left -> { val error = result.value println("Erreur : ${error.message}") } is Either.Right -> { val user = result.value println("Utilisateur trouvé : ${user.login}") } }</code></pre> </div> </div> <div class="paragraph"> <p>Este método, aunque simple y legible, no aprovecha plenamente las capacidades funcionales de Arrow.</p> </div> </div> <div class="sect2"> <h3 id="_uso_de_fold_para_un_enfoque_más_conciso">Uso de <code>fold</code> para un enfoque más conciso</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.fold( { error -> println("Erreur : ${error.message}") }, { user -> println("Utilisateur trouvé : ${user.login}") } )</code></pre> </div> </div> <div class="paragraph"> <p>`fold`permite definir acciones para los dos casos (Left y Right) de forma concisa y elegante.</p> </div> </div> <div class="sect2"> <h3 id="_transformación_con_map_y_mapleft">Transformación con <code>map</code> y `mapLeft</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val processedResult = result .map { user -> "Utilisateur trouvé : ${user.login}" } .mapLeft { error -> "Erreur : ${error.message}" } println(processedResult.merge())</code></pre> </div> </div> <div class="paragraph"> <p>Este enfoque permite transformar los valores contenidos en Either manteniendo su estructura, ideal para cadenas de procesamiento más complejas.</p> </div> </div> <div class="sect2"> <h3 id="_gestión_de_errores_con_getorelse">Gestión de errores con `getOrElse</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user = result.getOrElse { error -> println("Erreur : ${error.message}") User(login = "default", email = "default@example.com") // utilisateur par défaut } println("Login : ${user.login}")</code></pre> </div> </div> <div class="paragraph"> <p>`getOrElse`Ofrece un manejo elegante de errores permitiendo proporcionar un valor por defecto</p> </div> </div> <div class="sect2"> <h3 id="_acciones_laterales_con_onleft_y_onright">Acciones laterales con <code>onLeft</code> y `onRight</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.onLeft { error -> println("Erreur : ${error.message}") } .onRight { user -> println("Utilisateur trouvé : ${user.login}") }</code></pre> </div> </div> <div class="paragraph"> <p>Estos métodos permiten realizar acciones en cada lado sin modificar Either, perfecto para el registro o los efectos secundarios ligeros.</p> </div> </div> <div class="sect2"> <h3 id="_encadenamiento_de_operaciones_con_flatmap">Encadenamiento de operaciones con `flatMap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findUser(email: String): Either<Throwable, User> = // ... implémentation fun getUserPermissions(user: User): Either<Throwable, List<String>> = // ... implémentation val userPermissions = findUser("user@example.com") .flatMap { user -> getUserPermissions(user) }</code></pre> </div> </div> <div class="paragraph"> <p><code>flatMap`es útil para encadenar operaciones que devuelven ellas mismas de`Either</code>, evitando así los`Either`anidados.</p> </div> </div> <div class="sect2"> <h3 id="_transformación_bidireccional_con_bimap">Transformación bidireccional con `bimap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val processedResult = result.bimap( { error -> "Erreur: ${error.message}" }, { user -> "Utilisateur: ${user.login}" } )</code></pre> </div> </div> <div class="paragraph"> <p>`bimap`Permite transformar tanto el lado izquierdo como el derecho en una sola operación.</p> </div> </div> <div class="sect2"> <h3 id="_inversión_de_los_lados_con_swap">Inversión de los lados con `swap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val swapped = result.swap()</code></pre> </div> </div> <div class="paragraph"> <p><code>swap`es útil cuando quieres invertir los lados de un`Either</code>, por ejemplo para adaptar la interfaz de una función a otra.</p> </div> </div> <div class="sect2"> <h3 id="_uso_de_tap_y_tapleft">Uso de <code>tap</code> y <code>tapLeft</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.tap { user -> println("Utilisateur trouvé : ${user.login}") } .tapLeft { error -> println("Erreur : ${error.message}") }</code></pre> </div> </div> <div class="paragraph"> <p>Similar a`onLeft` et <code>onRight</code>, pero estos métodos devuelven el Either original, lo cual es útil para encadenar operaciones.</p> </div> </div> <div class="sect2"> <h3 id="_uso_de_recover">Uso de <code>recover</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val recoveredUser = result.recover { error -> println("Erreur récupérée : ${error.message}") User(login = "recovered", email = "recovered@example.com") } println("Login : ${recoveredUser.login}")</code></pre> </div> </div> <div class="paragraph"> <p>Este método permite transformar un Either.Left en Either.Right proporcionando un valor de reemplazo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casos_de_uso_prácticos">Casos de uso prácticos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Use`fold`para operaciones simples que requieren un tratamiento para cada caso. - prefieran`map` et <code>mapLeft`para de las transformaciones de datos sin cambiar la estructura de l'`Either</code>. - Opte por`flatMap`al encadenar operaciones que pueden fallar. emplead`recover`para proporcionar un valor predeterminado en caso de error - Eligan`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) para efectos secundarios como el logging. - Utilice`bimap`para transformar ambos lados en una sola operación - Aplica`swap`Cuando debas adaptar la interfaz de una función a otra</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cada una de estas aproximaciones tiene sus ventajas según el contexto de uso. Los métodos como`fold`, <code>map</code>/<code>mapLeft</code>, et `recover`son especialmente útiles cuando usted quiere encadenar varias operaciones o transformar los datos de manera funcional.</p> </div> <div class="paragraph"> <p>La monada`Either`d’Arrow ofrece una flexibilidad notable para manejar los casos de éxito y error en tus aplicaciones Kotlin. Al dominar estos diferentes enfoques, podrás escribir un código más robusto, más legible y más funcional.</p> </div> <div class="paragraph"> <p>En tu próximo proyecto, no dudes en explorar estas técnicas para aprovechar al máximo la programación funcional con Kotlin y Arrow!</p> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_más_lejos">Para ir más lejos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentación oficial de Arrow :https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[Arrow Either] - Corrutinas de Kotlin con Arrow :https://arrow-kt.io/docs/fx/[Arrow Fx Coroutines]</p> </li> </ul> </div> <div class="paragraph"> <p>No olviden de compartir tus experiencias y tus técnicas favoritas para trabajar con`Either`¡En los comentarios de abajo!</p> </div> </div> </div> https://cheroliv.com//blog/2024/0074_seach_file_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2024/0074_seach_file_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introducción">Introducción</a></li> <li><a href="#_uso_del_comando_find">Uso del comando `find</a> <ul class="sectlevel2"> <li><a href="#_opciones_adicionales_para_find">Opciones adicionales para `find</a></li> </ul> </li> <li><a href="#_uso_del_comando_locate">Uso del comando `locate</a></li> <li><a href="#_utilización_del_comando_grep_para_buscar_texto_en_archivos">Utilización del comando <code>grep</code> para buscar texto en archivos</a></li> <li><a href="#_conclusión">Conclusión</a></li> </ul> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">La problemática : Buscar archivos en un sistema operativo linux a través del terminal.</div> <p>En este artículo, vamos a explorar cómo buscar un archivo en Ubuntu utilizando un terminal Zsh. Zsh (Z shell) es un intérprete de comandos poderoso y ampliamente utilizado por su flexibilidad y sus características avanzadas.</p> </div> <div class="paragraph"> <p>Ubuntu, una distribución de Linux popular, ofrece varias herramientas de línea de comandos para buscar archivos. Veremos cómo usar comandos como`find`, <code>locate</code> et `grep`para localizar archivos rápidamente y eficientemente en el terminal.</p> </div> </div> </div> <div class="sect1"> <h2 id="_uso_del_comando_find">Uso del comando `find</h2> <div class="sectionbody"> <div class="paragraph"> <p>El comando`find`permite buscar archivos en un directorio específico y sus subdirectorios. Su sintaxis básica es la siguiente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find [chemin] -name [nom_du_fichier]</code></pre> </div> </div> <div class="paragraph"> <p>Este es un ejemplo práctico donde buscamos un archivo llamado`example.txt`en el directorio`/home`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -name "example.txt"</code></pre> </div> </div> <div class="paragraph"> <p>Este comando recorrerá todos los subdirectorios de`/home`y mostrar la ruta completa del archivo si se encuentra.</p> </div> <div class="paragraph"> <p><strong>Manual en línea del comando`find`:https://man.archlinux.org/man/find.1.fr/[man find,read-later]</strong></p> </div> <div class="sect2"> <h3 id="_opciones_adicionales_para_find">Opciones adicionales para `find</h3> <div class="paragraph"> <p>El comando`find`es muy potente y dispone de muchas opciones. Aquí tiene algunos ejemplos útiles :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Buscar por tipo de archivo</strong>Para buscar únicamente archivos, utilice`-type f`, y para buscar directorios, use`-type d`. - <strong>Buscar por tamaño</strong>También puedes filtrar los archivos según su tamaño utilizando la opción`-size`. Par exemple, pour rechercher des fichiers de plus de 100 Mo, utilisez :</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -size +100M</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_uso_del_comando_locate">Uso del comando `locate</h2> <div class="sectionbody"> <div class="paragraph"> <p>La orden`locate`es más rápido que`find`Porque utiliza una base de datos preindexada de los archivos presentes en el sistema. Debes actualizar primero esta base de datos con el siguiente comando:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo updatedb</code></pre> </div> </div> <div class="paragraph"> <p>Luego, puedes buscar un archivo así:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">locate example.txt</code></pre> </div> </div> <div class="paragraph"> <p>Utilizohttps://fr.wikipedia.org/wiki/Z_Shell[zsh]conhttps://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], resulta que el pedido`locate`no es accesible desde`zsh`pero bien posible desde`bash`, para paliar a esto, el argumento`-c`del comando`bash`permite lanzar un comando`bash`desde otro tipo de terminal.</p> </div> <div class="paragraph"> <p>aquí busco los archivos que terminan con el motivo`001.pdf`en el directorio del usuario</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">bash -c "locate ~/*001.pdf"</code></pre> </div> </div> <div class="paragraph"> <p><strong>Manual en línea del comando`locate`:https://man.archlinux.org/man/locate.1.fr/[man locate,windows=read-later]</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_utilización_del_comando_grep_para_buscar_texto_en_archivos">Utilización del comando <code>grep</code> para buscar texto en archivos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si quieres buscar un texto específico dentro de un archivo, puedes usar`grep`. Por ejemplo, para buscar la ocurrencia de la palabra <code>Ubuntu</code> en todos los archivos`.txt`del directorio actual, use:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">grep "Ubuntu" *.txt</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>La búsqueda de archivos en Ubuntu a través de una terminal Zsh se puede realizar con varias herramientas poderosas.`find`es flexible y ofrece una multitud de opciones, mientras que`locate`Permite una búsqueda rápida utilizando una base de datos preconstruida. Finalmente,`grep`permite encontrar ocurrencias de texto dentro de los archivos.</p> </div> <div class="paragraph"> <p>Estos comandos le ofrecen una gama completa de herramientas para hacer que sus búsquedas de archivos sean más eficientes y adaptadas a sus necesidades y cada uno de estos comandos posee un manual visible con el comando`man`</p> </div> </div> </div> https://cheroliv.com//blog/2021/0030_memo_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2021/0030_memo_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_el_teclado">El teclado:</a> <ul class="sectlevel2"> <li><a href="#_la_tecla_ctrl"><em>la tecla <Ctrl></em></a></li> </ul> </li> <li><a href="#_permisoauthorization">Permiso(authorization)</a></li> <li><a href="#_búsqueda_de_archivos">Búsqueda de archivos</a></li> </ul> </div> <div class="sect1"> <h2 id="_el_teclado">El teclado:</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_tecla_ctrl"><em>la tecla <Ctrl></em></h3> <table class="tableblock frame-all grid-all stretch"> </table> <div class="paragraph"> <p><a href="https://korben.info/les-raccourcis-clavier-pour-bash-terminal-linux-et-macos.html">enlace</a><br> <a href="https://blogmotion.fr/systeme/astuces-bash-linux-16175">otro enlace</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_permisoauthorization">Permiso(authorization)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD se utiliza para cambiar los permisos de un archivo.</p> </div> <div class="paragraph"> <p>PERMISO COMANDO</p> </div> <div class="paragraph"> <p>U G W rwx rwx rwx chmod 777 filename rwx rwx r-x chmod 775 nom de fichier rwx r-x r-x chmod 755 nombre_de_archivo rw- rw- r-- chmod 664 nombre_archivo rw- r-- r-- chmod 644 filename</p> </div> <div class="paragraph"> <p>U = Usuario G = Grupo W = Mundo</p> </div> <div class="paragraph"> <p>r = Readable w = escribible x = ejecutable - = no permiso</p> </div> <div class="paragraph"> <p>Otra forma de ver los permisos:</p> </div> <div class="paragraph"> <p>400 leído por el propietario 040 leído por el grupo 004 leído por cualquiera (otro) 200 write by owner 020 escribir por grupo 002 escribir por cualquiera 100 ejecutar por el propietario 010 ejecutar por grupo ejecutado por cualquiera</p> </div> <div class="paragraph"> <p>Para obtener una combinación, basta con sumarlos.<br> Por ejemplo, para ser leído, escrito, ejecutado por el propietario,<br> leído, ejecutado, por grupo y ejecutado por cualquiera,<br> añadirías 400+200+100+040+010+001 para dar 751.<br></p> </div> </div> </div> <div class="sect1"> <h2 id="_búsqueda_de_archivos"><a href="/blog/2024/0074_seach_file_linux_post.html">Búsqueda de archivos</a></h2> <div class="sectionbody"> </div> </div> https://cheroliv.com//blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html Thu, 1 Feb 2024 00:00:00 +0000 blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html https://cheroliv.com//blog/2024/0070_installer_pandoc_post.html Tue, 30 Jan 2024 00:00:00 +0000 blog/2024/0070_installer_pandoc_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Tiempo de lectura: 3 min</em> Pandoc un convertidor universal de documento</div> <p>Pandoc es un software de procesamiento de texto de código abierto que se puede utilizar para convertir documentos entre diferentes formatos. Hay varias formas de instalar Pandoc.</p> </div> </div> </div> <div class="sect1"> <h2 id="_instalación_desde_la_página_de_descarga"><strong>Instalación desde la página de descarga</strong></h2> <div class="sectionbody"> <div class="paragraph"> <p>Para instalar Pandoc desde la página de descarga, siga estos pasos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Acceda a la página de descarga de Pandoc:https://pandoc.org/installing.html/[<a href="https://pandoc.org/installing.html" class="bare">https://pandoc.org/installing.html</a>]</p> </li> <li> <p>Descarga el instalador del paquete para tu sistema operativo.</p> </li> <li> <p>Ejecute el instalador para instalar Pandoc.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Instalación desde un archivo zip</strong></p> </div> <div class="paragraph"> <p>Para instalar Pandoc desde un archivo zip, siga estos pasos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Descargue el archivo zip que contiene los binarios de Pandoc y la documentación.</p> </li> <li> <p>Descomprima el archivo zip.</p> </li> <li> <p>Mueva los binarios a un directorio de su elección.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Instalación con Chocolatey</strong></p> </div> <div class="paragraph"> <p>Para instalar Pandoc usando Chocolatey, sigue estos pasos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Abre el símbolo del sistema.</p> </li> <li> <p>Ejecute el siguiente comando :</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">choco install pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>Instalación con winget</strong></p> </div> <div class="paragraph"> <p>Para instalar Pandoc utilizando winget, siga estos pasos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Abre el símbolo del sistema.</p> </li> <li> <p>Ejecute el siguiente comando:</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">winget install --source winget --exact --id JohnMacFarlane.Pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>Recomendaciones</strong></p> </div> <div class="paragraph"> <p>Por defecto, Pandoc crea PDFs usando LaTeX. Se recomienda instalar LaTeX a través de MiKTeX. Con la opción`--pdf-engine`, pero puede especificar otros programas para esta tarea.</p> </div> <div class="paragraph"> <p><strong>Advertencia</strong></p> </div> <div class="paragraph"> <p>El uso de varios métodos de instalación puede dar lugar a dos instalaciones distintas de Pandoc. Se recomienda desinstalar correctamente Pandoc antes de pasar a un método de instalación alternativo.</p> </div> <div class="paragraph"> <p><strong>Instalación en Linux por WSL</strong></p> </div> <div class="paragraph"> <p>Comprueba si la versión de pandoc en tu gestor de paquetes no está obsoleta. Pandoc se encuentra en los repositorios de Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, gentoo y Void.</p> </div> <div class="paragraph"> <p>Para obtener la última versión, ofrecemos un paquete binario para la arquitectura amd64 en la página de descarga.</p> </div> <div class="paragraph"> <p>El ejecutable está enlazado estáticamente y no tiene dependencias dinámicas ni dependencias de archivos de datos externos. Nota: debido al enlace estático, el binario pandoc de este paquete no puede usar los filtros lua que requieren módulos lua externos escritos en C.</p> </div> <div class="paragraph"> <p>Se proporciona un tarball y un instalador .deb. Para instalar el deb :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i $DEB</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo al momento de escribir :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wget https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="paragraph"> <p>où `$DEB`es la ruta hacia el deb descargado. Esto instalará el ejecutable`pandoc`y la página del manual.</p> </div> <div class="paragraph"> <p>Si utiliza una distribución basada en RPM, quizás pueda instalar el deb de nuestra página de descarga utilizando alien.</p> </div> <div class="paragraph"> <p>En cualquier distribución, puede instalar desde el tarball en`$DEST`(por ejemplo,<code>/usr/local/</code> ou <code>$HOME/.local</code>) haciendo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">tar xvzf $TGZ --strip-components 1 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>où `$TGZ`es el camino hacia el tarball zipped descargado. Para las versiones de Pandoc anteriores a 2.0, que no proporcionan un tarball, intente en su lugar:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>También puede instalar desde el código fuente, utilizando las instrucciones que se encuentran a continuación bajo`Compilation à partir de la source`. Tenga en cuenta que la mayoría de las distribuciones tienen la plataforma Haskell en sus repositorios de paquetes. Por ejemplo, en Debian/Ubuntu, puedes instalarlo con</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">apt-get install haskell-platform</code></pre> </div> </div> <div class="paragraph"> <p>Por defecto, Pandoc crea PDFs utilizando LaTeX. Le recomendamos instalar TeX Live a través de su gestor de paquetes. (En Debian/Ubuntu,<code>apt-get install texlive</code>). Con la opción`--pdf-engine`, sin embargo, puede especificar otros programas para esta tarea.</p> </div> </div> </div> https://cheroliv.com//blog/2023/0069_triple_python_js_ts_post.html Mon, 25 Dec 2023 00:00:00 +0000 blog/2023/0069_triple_python_js_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Tiempo de lectura : 2 min</em> Crear una implementación completa de la clase kotlin.Triple en JavaScript, TypeScript y Python utilizando la programación funcional.</div> <p><strong>Nota:</strong>Los tipos`Maybe`, <code>Either</code>, `Result`no forman parte del lenguaje base en JavaScript o TypeScript, por lo que hay que implementarlos nosotros mismos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_javascript">JavaScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//javascript // Maybe type const Maybe = (value) => ({ map: (fn) => (value !== null && value !== undefined ? Maybe(fn(value)) : Maybe(null)), flatMap: (fn) => (value !== null && value !== undefined ? fn(value) : Maybe(null)), getOrElse: (defaultValue) => (value !== null && value !== undefined ? value : defaultValue), }); // Either type const Either = { Left: (value) => ({ map: (fn) => Either.Left(value), flatMap: (fn) => Either.Left(value), getOrElse: (defaultValue) => defaultValue, isLeft: true, isRight: false, }), Right: (value) => ({ map: (fn) => Either.Right(fn(value)), flatMap: (fn) => fn(value), getOrElse: (defaultValue) => value, isLeft: false, isRight: true, }), }; // Triple class class Triple { constructor(a, b, c) { this.a = a; this.b = b; this.c = c; } map(fn) { return new Triple(fn(this.a), fn(this.b), fn(this.c)); } static of(a, b, c) { return new Triple(a, b, c); } // Example method using Maybe and Either divideBy(other) { return Maybe(this.b) .flatMap((numerator) => Maybe(other) .flatMap((denominator) => denominator !== 0 ? Either.Right(numerator / denominator) : Either.Left('Division by zero') ) ) .getOrElse(Either.Left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_typescript">TypeScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">//Typescript // Maybe type // noinspection JSAnnotator type Maybe<T> = { map<U>(fn: (value: T) => U): Maybe<U>; flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>; getOrElse(defaultValue: T): T; }; const just = <T>(value: T): Maybe<T> => ({ map: <U>(fn: (value: T) => U) => just(fn(value)), flatMap: <U>(fn: (value: T) => Maybe<U>) => fn(value), getOrElse: (_: T) => value, }); const nothing = <T>(): Maybe<T> => ({ map: <U>(_: (value: T) => U) => nothing<U>(), flatMap: <U>(_: (value: T) => Maybe<U>) => nothing<U>(), getOrElse: (defaultValue: T) => defaultValue, }); // Either type type Either<L, R> = { map<U>(fn: (value: R) => U): Either<L, U>; flatMap<U>(fn: (value: R) => Either<L, U>): Either<L, U>; getOrElse(defaultValue: R): R; isLeft: boolean; isRight: boolean; }; const left = <L, R>(value: L): Either<L, R> => ({ map: <U>(_: (value: R) => U) => left<L, U>(value), flatMap: <U>(_: (value: R) => Either<L, U>) => left<L, U>(value), getOrElse: (defaultValue: R) => defaultValue, isLeft: true, isRight: false, }); const right = <L, R>(value: R): Either<L, R> => ({ map: <U>(fn: (value: R) => U) => right<L, U>(fn(value)), flatMap: <U>(fn: (value: R) => Either<L, U>) => fn(value), getOrElse: (_: R) => value, isLeft: false, isRight: true, }); // Triple class class Triple<T> { constructor(public a: T, public b: T, public c: T) {} map<U>(fn: (value: T) => U): Triple<U> { return new Triple<U>(fn(this.a), fn(this.b), fn(this.c)); } static of<T>(a: T, b: T, c: T): Triple<T> { return new Triple<T>(a, b, c); } // Example method using Maybe and Either divideBy(other: T): Either<string, number> { return just(this.b) .flatMap((numerator) => just(other) .flatMap((denominator) => denominator !== 0 ? right(numerator / denominator) : left('Division by zero') ) ) .getOrElse(left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_python_pydantic_pymonad">Python, pydantic, pymonad</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para crear una implementación en Python utilizando`pydantic`para la validación de tipos y`pymonad`para las monadas :</p> </div> <div class="listingblock"> <div class="title">Instalar las dependencias :</div> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install pydantic pymonad</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python">from pymonad.either import Either, Left, Right from pydantic import BaseModel, ValidationError, validator # Définition de la classe Triple avec Pydantic class Triple(BaseModel): a: int b: int c: int @validator('b') def validate_b(cls, b, values): if b == 0: raise ValueError('Division by zero is not allowed') return b # Méthode utilisant Either pour la gestion des erreurs def divide_by(self, other): def division(numerator, denominator): return Right(numerator / denominator) def handle_error(error): return Left(str(error)) return Either(lambda: division(self.b, other)).or_else(handle_error) # Exemple d'utilisation try: triple = Triple(a=1, b=2, c=3) result = triple.divide_by(2) if result.is_right: print(f'Division result: {result.value}') else: print(f'Error: {result.value}') except ValidationError as e: print(f'Validation Error: {e}') except Exception as e: print(f'An unexpected error occurred: {e}')</code></pre> </div> </div> <div class="ulist"> <div class="title">En este ejemplo:</div> <ul> <li> <p><code>pydantic`para definir la clase`Triple`con campos tipados. - El método`divide_by`utiliza la mónada`Either</code> de `pymonad`para gestionar los errores potenciales resultantes de la división por cero. - Validación personalizada para asegurarse de que el valor de`b`no es igual a cero. Si es igual a cero, se lanza una excepción, y`pymonad`Captura esta excepción para devolver un resultado`Left`indicando el error.</p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2023/0068_introduction_google_apps_script_post.html Fri, 22 Dec 2023 00:00:00 +0000 blog/2023/0068_introduction_google_apps_script_post.html <div class="sect1"> <h2 id="_tabla_de_contenidos">Tabla de contenidos</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>tiempo de lectura : 30 min</em></p> </div> <div class="ulist"> <ul> <li> <p><a href="#_introducción">Introducción</a></p> </li> <li> <p>Estructura básica en Google Apps Script</p> </li> <li> <p>Tipos y Variables en Google Apps Script</p> </li> <li> <p><a href="#Constantes">Variables y Letras en Google Apps Script</a></p> </li> <li> <p><a href="#_operaciones_y_operadores_en_google_apps_script">Operaciones y Operadores en Google Apps Script</a></p> </li> <li> <p><a href="#Var">Let y Const en Google Apps Script</a></p> </li> <li> <p><a href="#_estructuras_de_control_en_google_apps_script">Estructuras de Control en Google Apps Script</a></p> </li> <li> <p><a href="#_bucles_en_google_apps_script">Bucles en Google Apps Script</a></p> </li> <li> <p><a href="#_objetos_en_google_apps_script">Objetos en Google Apps Script</a></p> </li> <li> <p><a href="#_funciones_en_google_apps_script">Funciones en Google Apps Script</a></p> </li> <li> <p><a href="#Parámetros y Alcances en Google Apps Script">[Parámetros y Alcances en Google Apps Script]</a></p> </li> <li> <p><a href="#Operadores de reposo y propagación en Google Apps Script">[Operadores de reposo y propagación en Google Apps Script]</a></p> </li> <li> <p><a href="#Asignación por Descomposición en Google Apps Script">[Asignación por Descomposición en Google Apps Script]</a></p> </li> <li> <p><a href="#_colecciones_y_programación_declarativa_en_google_apps_script">Colecciones y Programación Declarativa en Google Apps Script</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_introducción">Introducción</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script (GAS) es una plataforma de desarrollo de scripts asociada a diversos servicios de Google, como Google Sheets, Google Docs y Google Forms. Permite automatizar tareas, agregar funcionalidades personalizadas e integrar servicios de Google.</p> </div> <div class="paragraph"> <p>En este memorándum, vamos a explorar los conceptos principales de Google Apps Script apoyándonos en ejemplos concretos. Abordaremos nociones como las variables, los bucles, las funciones y mucho más, adaptándolas al contexto específico de GAS.</p> </div> </div> </div> <div class="sect1"> <h2 id="_estructura_básica_en_google_apps_script">Estructura básica en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para empezar, examinemos la estructura básica de un script de Google Apps.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structure de base en Google Apps Script */ function exempleStructureGAS() { // Votre code ici Logger.log("Hello, Google Apps Script!"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tipos_y_variables_en_google_apps_script">Tipos y variables en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script utiliza JavaScript como lenguaje de programación. Los tipos de datos y las variables funcionan de manera similar a JavaScript estándar.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Types et Variables en Google Apps Script */ function exempleTypesVariablesGAS() { // Votre code ici var nombre = 42; var texte = "Bonjour, Google Apps Script!"; Logger.log(nombre); Logger.log(texte); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_operaciones_y_operadores_en_google_apps_script">Operaciones y Operadores en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Las operaciones y operadores en Google Apps Script son los mismos que en JavaScript.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérations et Opérateurs en Google Apps Script */ function exempleOperationsGAS() { // Votre code ici var x = 10; var y = 5; var resultat = x + y; Logger.log(resultat); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_var_let_y_const_en_google_apps_script">Var, Let y Const en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>En GAS, los conceptos de`var`, <code>let</code>, et `const`se utilizan para declarar variables. Sin embargo, es esencial comprender sus diferencias e implicaciones.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Var, Let et Const en Google Apps Script */ function exempleVarLetConstGAS() { // Votre code ici // Utilisation de var var x = 10; if (true) { var x = 20; // La variable x est modifiée globalement } Logger.log(x); // Utilisation de let let y = 30; if (true) { let y = 40; // La variable y est limitée au bloc if } Logger.log(y); // Utilisation de const const z = 50; // z = 60; // Impossible de réassigner une constante Logger.log(z); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estructuras_de_control_en_google_apps_script">Estructuras de Control en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Las estructuras de control tales como`if`, <code>else</code>, <code>while</code> et `for`son utilizadas para gestionar el flujo de ejecución en Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structures de Contrôle en Google Apps Script */ function exempleStructuresControleGAS() { // Votre code ici var condition = true; if (condition) { Logger.log("La condition est vraie."); } else { Logger.log("La condition est fausse."); } var compteur = 0; while (compteur < 5) { Logger.log(compteur); compteur++; } for (var i = 0; i < 3; i++) { Logger.log(i); } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_parámetros_y_ámbitos_en_google_apps_script">Parámetros y ámbitos en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los parámetros y los scopes juegan un papel crucial en el desarrollo de scripts en GAS. Comprende cómo funcionan para evitar comportamientos inesperados.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Paramètres et Scopes en Google Apps Script */ function exempleParametresScopesGAS(parametre) { // Votre code ici var variableGlobale = "Je suis global"; function afficherParametre() { Logger.log(parametre); } afficherParametre(); Logger.log(variableGlobale); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_constantes_variables_y_letras_en_google_apps_script">Constantes, Variables y Letras en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Entender la diferencia entre`const`, <code>var</code>, et `let`es esencial para un uso eficaz de las variables en Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_bucles_en_google_apps_script">Bucles en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los bucles, tales como`for` et <code>while</code>, son esenciales para iterar sobre elementos y realizar operaciones repetitivas.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Boucles en Google Apps Script */ function exempleBouclesGAS() { // Votre code ici for (var i = 0; i < 3; i++) { Logger.log(i); } var condition = true; var compteur = 0; while (condition) { Logger.log("Tour de boucle"); compteur++; if (compteur === 3) { condition = false; } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_objetos_en_google_apps_script">Objetos en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los objetos se utilizan para estructurar los datos. En GAS, muchos objetos integrados facilitan la interacción con los servicios de Google.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Objets en Google Apps Script */ function exempleObjetsGAS() { // Votre code ici var feuille = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var cellule = feuille.getRange("A1"); cellule.setValue("Nouvelle valeur"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_constantes_variables_y_letras_en_google_apps_script_2">Constantes, Variables y Letras en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Entender la diferencia entre`const`, <code>var</code>, et `let`es esencial para un uso eficaz de las variables en Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_funciones_en_google_apps_script">Funciones en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Las funciones son elementos fundamentales en la programación. En GAS, pueden declararse y llamarse de distintas maneras.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Fonctions en Google Apps Script */ function exempleFonctionsGAS() { // Votre code ici function additionner(a, b) { return a + b; } var resultat = additionner(2, 3); Logger.log(resultat); // Fonction anonyme var multiplier = function (x, y) { return x * y; }; Logger.log(multiplier(4, 5)); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_operadores_de_repos_y_de_propagación_en_google_apps_script">Operadores de repos y de propagación en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los operadores de repos`…​<code>) y de propagación (</code>…​`) son útiles para manipular los arrays y los objetos de manera concisa.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateurs de Repos et de Propagation en Google Apps Script */ function exempleOperateursReposPropagationGAS() { // Votre code ici // Opérateur de repos (...) pour les tableaux var nombres = [1, 2, 3, 4, 5]; var [...copieNombres] = nombres; Logger.log(copieNombres); // Opérateur de propagation (...) pour les objets var objOriginal = { x: 1, y: 2 }; var objClone = { ...objOriginal, z: 3 }; Logger.log(objClone); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_asignación_por_desestructuración_en_google_apps_script">Asignación por desestructuración en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>La asignación por desestructuración es una característica poderosa que permite extraer valores de objetos y arrays de forma concisa.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Affectation par Décomposition en Google Apps Script */ function exempleAffectationDecompositionGAS() { // Votre code ici var coordonnees = [3, 4]; var [x, y] = coordonnees; Logger.log(x); Logger.log(y); var utilisateur = { nom: "John", age: 30 }; var { nom, age } = utilisateur; Logger.log(nom); Logger.log(age); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_colecciones_y_programación_declarativa_en_google_apps_script">Colecciones y Programación Declarativa en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script admite estructuras de datos como los arreglos, y conceptos de programación funcional y de iteración declarativa (><imperativa), como`map`, <code>reduce</code> et <code>forEach</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Collections et Programmation Déclarative en Google Apps Script */ function exempleCollectionsFonctionnelleGAS() { // Votre code ici // Exemple de tableau (collection) var nombres = [1, 2, 3, 4, 5]; // Utilisation de forEach nombres.forEach(function (nombre) { Logger.log(nombre); }); // Utilisation de map var carresNombres = nombres.map(function (nombre) { return nombre * nombre; }); Logger.log(carresNombres); // Utilisation de reduce var somme = nombres.reduce(function (acc, nombre) { return acc + nombre; }, 0); Logger.log(somme); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusión">Conclusión</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este memorando ha cubierto los conceptos fundamentales de Google Apps Script ilustrándolos con ejemplos de código concretos. Utiliza estos conocimientos para automatizar tus tareas diarias, personalizar tus documentos y aprovechar plenamente las funcionalidades de Google Apps Script.</p> </div> </div> </div> https://cheroliv.com//blog/2023/0067_formation_express_sur_google_forms_script_post.html Wed, 20 Dec 2023 00:00:00 +0000 blog/2023/0067_formation_express_sur_google_forms_script_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Duración : 30 minutos</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivos">Objetivos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Entender los conceptos básicos de Google Apps Script en Forms - Aprender a acceder al editor de script y ejecutar una instrucción en el desencadenador</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_temporización">Temporización</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Introducción a Google Form Script</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Vista rápida de Google Form Script Presentación de las funcionalidades principales</p> </li> </ul> </div> </li> <li> <p><strong>Creación de un Formulario de Google y un Script asociado</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Creación de un formulario sencillo con Google Forms - Introducción al editor de script asociado</p> </li> </ul> </div> </li> <li> <p><strong>Ejecutar una instrucción</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Configuración del disparador "on start - Configuración del desencadenador \"on submit\ Escritura de un script para ejecutar una instrucción Pruebas rápidas para verificar el buen funcionamiento en el registro</p> </li> </ul> </div> </li> <li> <p><strong>Análisis de Resultados y Buenas Prácticas</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Verificación de los resultados de la ejecución de una instrucción Discusión sobre un ejemplo de script y cómo la automatización puede ahorrar tiempo</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_prerrequisito">Prerrequisito</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Tener una cuenta de Google y acceso a Google Forms y Google Sheets</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_material">Material</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Ordenador con un navegador web y una conexión a internet</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_comentario">Comentario</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta formación express ofrece una introducción rápida a la automatización con Google Form Script. Para una comprensión más profunda, se recomiendan formaciones más largas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_introducción_al_script_de_google_forms">1 - Introducción al script de Google Forms</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_resumen_rápido_del_script_de_google_form">Slide 1: Resumen rápido del script de Google Form</h3> <div class="ulist"> <ul> <li> <p>Google Form Script es una plataforma de scripting integrada a Google Forms. - Permite agregar funcionalidades personalizadas y automatizar tareas.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_2_presentación_de_las_funcionalidades_principales">Slide 2: Presentación de las funcionalidades principales</h3> <div class="ulist"> <ul> <li> <p>Script Editor : El editor de script integrado para escribir scripts de Google Apps Script. Desencadenantes: Eventos como "on submit" que activan la ejecución de los scripts.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_diapositiva_3_ventajas_del_uso_del_script_de_google_form">Diapositiva 3: Ventajas del uso del script de Google Form</h3> <div class="ulist"> <ul> <li> <p>Personalización : Crea formularios personalizados con características únicas. - Automatización: Automatiza acciones en respuesta a las respuestas de los formularios. - Integración: Integra scripts con otros servicios de Google para una experiencia más rica.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_nota_para_el_presentador">Nota para el presentador :</h3> <div class="paragraph"> <p>Estas funcionalidades ofrecen un potencial considerable para personalizar y automatizar los formularios. La continuación de esta formación explorará más en detalle la creación de scripts y automatizaciones específicas.</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=es" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=es</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms?hl=es" class="bare">https://developers.google.com/apps-script/reference/forms?hl=es</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms/form-app?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms/form-app?hl=fr</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_creación_de_un_formulario_de_google_y_un_script_asociado_5_min"><strong>Creación de un Formulario de Google y un Script asociado</strong> (5 min)</h2> <div class="sectionbody"> </div> </div> https://cheroliv.com//blog/2023/0066_memo_python_post.html Sun, 19 Nov 2023 00:00:00 +0000 blog/2023/0066_memo_python_post.html <div class="sect1"> <h2 id="_instalar_python_en_windows">Instalar python en windows</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">python en windows</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/starting/install3/win.html" class="bare">https://python-docs.readthedocs.io/en/latest/starting/install3/win.html</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref" class="bare">https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_ejecutando_python">Ejecutando python</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Referencia :</div> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">cd mon_projet python -m venv mon_venv source mon_venv/bin/activate # Sur windows mon_venv\Scripts\activate deactivate</code></pre> </div> </div> <div class="sect2"> <h3 id="_requisito_de_instalación">requisito de instalación</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install -r requirements.txt</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_iniciación">iniciación</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">python POO</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_patrones_de_diseño_del_gof_en_python">Patrones de diseño del GoF en Python</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">implementación 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">implementación 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">libro completo</a></p> </div> <div class="paragraph"> <p>Los design patterns de GoF son un conjunto de 23 design patterns que han sido descritos en el libro "Design Patterns: Elements of Reusable Object-Oriented Software".</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Aquí tienes una lista de los patrones de diseño GoF</caption> <colgroup> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0849%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Método de fábrica</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea objetos sin especificar la clase exacta a instanciar.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fábrica Abstracta</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea familias de objetos relacionados o dependientes sin especificar su clase concreta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Constructor</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Separa la construcción de un objeto complejo de su representación para que el mismo proceso de construcción pueda crear diferentes representaciones.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Prototipo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea nuevos objetos copiando un prototipo existente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Singleton</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Restringe la instanciación de una clase a un solo objeto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Adaptar</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Convierte la interfaz de una clase en otra interfaz que el cliente espera.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>bridge</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Desacopla una abstracción de su implementación de modo que ambos puedan variar independientemente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Compuesto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Compone objetos en estructuras de árbol para representar jerarquías de parte-todo.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Decorador</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Adjunta dinámicamente responsabilidades adicionales a un objeto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fachada</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Proporciona una interfaz unificada a un conjunto de interfaces en un subsistema.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Peso mosca</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reduce el costo de creación y uso de objetos ligeros.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>proxy</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Proporciona un sustituto o un espacio reservado para otro objeto a fin de controlar el acceso a él.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cadena de Responsabilidad</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite que más de un objeto procese una solicitud.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Comando</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Encapsule una solicitud en un objeto, permitiendo así parametrizar clientes con diferentes solicitudes, colas o registros, y admitir operaciones deshacibles.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Intérprete</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Da una representación de la gramática de un idioma y usa esta representación para interpretar frases en ese idioma.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Iterador</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Proporciona una manera de recorrer secuencialmente los elementos de un objeto agregado sin exponer su representación subyacente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mediador</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite reducir las dependencias complejas entre los objetos haciendo que se comuniquen únicamente a través de un objeto mediador.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Recuerda</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Proporciona la capacidad de restaurar un objeto a su estado anterior (sin violar la encapsulación).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Observa</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define una dependencia uno-a-muchos entre los objetos de modo que cuando un objeto cambia de estado, todos sus dependientes son notificados y actualizados automáticamente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>estado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite a un objeto cambiar de comportamiento cuando cambia su estado interno.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Estrategia</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define una familia de algoritmos, encapsula cada uno de ellos y los hace intercambiables.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Método plantilla</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define el esqueleto de un algoritmo en un método, delegando algunos pasos a las subclases.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Visitante</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite definir una nueva operación que se realiza sobre una estructura de objetos sin cambiar las clases de los objetos sobre los que actúa.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_programación_funcional">Programación funcional</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 27.7777%;"> <col style="width: 55.5557%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">biblioteca</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/jasondelaat/pymonad" class="bare">https://github.com/jasondelaat/pymonad</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad es una implementación de estructuras de datos monádicas en Python basada en lenguajes de programación como Haskell y F# con implementaciones para los tipos de monads más comúnmente usados en programación funcional.https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[artículo]</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/EntilZha/PyFunctional/" class="bare">https://github.com/EntilZha/PyFunctional/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional es una biblioteca Python para la programación funcional que proporciona herramientas para trabajar con funciones puras e iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://toolz.readthedocs.io/en/latest/" class="bare">https://toolz.readthedocs.io/en/latest/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz es una biblioteca Python para la programación funcional que proporciona herramientas para trabajar con funciones puras e iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/kachayev/fn.py" class="bare">https://github.com/kachayev/fn.py</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py es una biblioteca Python para la programación funcional que proporciona herramientas para trabajar con funciones puras e iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">coco</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://coconut-lang.org/" class="bare">https://coconut-lang.org/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Coconut agrega varias funcionalidades a Python para la programación funcional, incluido el pattern matching.https://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[conversación sof]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_efectos_secundarios">efectos secundarios</h3> </div> <div class="sect2"> <h3 id="_bucles">bucles</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python"># impérative way result = [] for i in inputs: x = f(g(i)) result.append(x) # idiomatic way result = map(comp(f,g), inputs)</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2023/0065_training_web_dev_post.html Thu, 24 Aug 2023 00:00:00 +0000 blog/2023/0065_training_web_dev_post.html https://cheroliv.com//blog/2023/0064_training_trading_card_games_post.html Mon, 21 Aug 2023 00:00:00 +0000 blog/2023/0064_training_trading_card_games_post.html https://cheroliv.com//blog/2023/0063_memo_ts_post.html Sat, 19 Aug 2023 00:00:00 +0000 blog/2023/0063_memo_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>repositorio de github:https://github.com/cheroliv/ts-codebase[ts-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_ts"><span class="underline">Introducción typescript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">Los tipos en typescript</a></p> </li> <li> <p><a href="#funciones">Funciones</a></p> </li> <li> <p><a href="#data_struct">Estructura de datos</a></p> </li> <li> <p><a href="#enums_tuples">Enums y tuplas</a></p> </li> <li> <p><a href="#void_never">Vacío y Nunca</a></p> </li> <li> <p><a href="#class_interface">Clases y interfaces</a></p> </li> <li> <p><a href="#tsconfig">El archivo tsconfig.json</a></p> </li> <li> <p><a href="#módulos">[módulos]</a></p> </li> <li> <p><a href="#promesas">Promesas</a></p> </li> <li> <p><a href="#async-await">async/await</a></p> </li> <li> <p><a href="#genéricos">[genéricos]</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> <title>Document</title> </head> <body> Intro typescript <script src="01_types.js"></script> <script src="02_data_structure.js"></script> <script src="03_enums_tuples.js"></script> </body> </html></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="ts_types">Los tipos en typescript</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les types en typescript */ //quand le type n'est pas defini des le debut, // alors il est réassignable // c'est le type Any qui est attribué par défaut let my_var; my_var = "username"; console.assert(my_var === "username"); my_var = 11; console.assert(my_var === 11); my_var = true; console.assert(my_var === true); let age = 1; console.assert(age === 1); age = 2; // age="trois" c'est impossible // car l'inference de type a attribué le type number console.assert(age === 2); // Déclaration explicite de type let pi: Number = 3.14; console.assert(typeof pi === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="funciones">Funciones</h2> <div class="sectionbody"> <div class="paragraph"> <p>Las funciones son bloques de código reutilizables.</p> </div> <div class="paragraph"> <p>Ejemplo de calificación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const add = (a: number, b: number): number => a + b;</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">Estructura de datos</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_data_structure.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/*** * Structure de données: * Avec le type any on peut changer * le type de la variable à tout instruction * Lorsque l'on fixe le type * alors il n'est plus possible de le changer * lors d'une assignation */ // Arrays let buddies: any[] = [ "cheroliv", "imrandeh", "issoudeh", "soumi92" ] console.assert(buddies[0] === "cheroliv"); console.assert(buddies[1] === "imrandeh"); console.assert(buddies[2] === "issoudeh"); console.assert(buddies[3] === "soumi92"); // Déclaré en type any, l'inference de type // a bien réaligné en type string console.assert(typeof buddies[0] === "string"); console.assert(typeof buddies[1] === "string"); console.assert(typeof buddies[2] === "string"); console.assert(typeof buddies[3] === "string"); let writers: (String | String | String | Number)[][] = [ ["Chrétien", "de Troyes", "fr", 12], ["François", "Rabelais", "fr", 16], ["René", "Descartes", "fr", 17], ["Jean-Jacques", "Rousseau", "fr", 18], ["Georg", "Hegel", "de", 19], ["Karl", "Marx", "de", 19], ["Friedrich", "Engels", "de", 19], ["Victor", "Hugo", "fr", 19], ["Paul", "Verlaine", "fr", 19], ["Arthur", "Rimbaud", "fr", 19], ["Gérard", "de Nerval", "fr", 19], ["Georg", "Lukacs", "hu", 20], ["Franz", "Kafka", "hu", 20], ["Antonio", "Gramsci", "it", 20], ["Domenico","Losurdo","it",20], ]; // console.table(writers); // Objects let author: { first_name: String, last_name: String, lang: String, century: Number } = { // slice(-1) renvoie le dernier élèment first_name: writers.slice(-1)[0][0] as String, last_name: writers.slice(-1)[0][1] as String, lang: writers.slice(-1)[0][2] as String, century: writers.slice(-1)[0][3] as Number, } // assertion sur la valeur en accés par encapsulation(dot) console.assert(author.first_name === "Antonio") console.assert(author.last_name === "Gramsci") console.assert(author.lang === "it") console.assert(author.century === 20); // assertion sur le type en accès par index console.assert(typeof author["first_name"] === "string") console.assert(typeof author["last_name"] === "string") console.assert(typeof author["lang"] === "string") console.assert(typeof author["century"] === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">Enums y tuplas</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_enums_tuples.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Enums et Tuples * * Enum: il existe les enums numérique * et les enums chaine de caracteres. * * Tuple: similaire aux arrays mais ne peut * contenir qu'une valeur de type spécifié. * */ //Enum numérique // l'index par de debut défaut est 0 // ici on le place a 1 enum Week { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7, }; console.assert(Week.Monday == 1); console.assert(Week.Tuesday == 2); console.assert(Week.Wednesday == 3); console.assert(Week.Thursday == 4); console.assert(Week.Friday == 5); console.assert(Week.Saturday == 6); console.assert(Week.Sunday == 7); console.assert(Week[1] === "Monday"); console.assert(Week[2] === "Tuesday"); console.assert(Week[3] === "Wednesday"); console.assert(Week[4] === "Thursday"); console.assert(Week[5] === "Friday"); console.assert(Week[6] === "Saturday"); console.assert(Week[7] === "Sunday"); let motd_arr_fr: String[] = [ "Associé à la Lune", "Du dieu Tiw, associé à Mars", "Du dieu germanique Odin", "Du dieu germanique du tonnerre Thor", "De la déesse germanique Frigga associée à Vénus", "Associé à Saturne", "Associé au Soleil", ]; let motd_arr_en: String[] = [ "associated with the Moon", "from the god Tiw, associated with Mars", "from Germanic god Odin", "from Germanic god of thunder Thor", "from Germanic goddess Frigga associated with Venus", "associated with Saturn", "associated with the Sun", ]; // Un tuple (triple) let monday_triple_fr: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_fr[0], ]; console.assert(monday_triple_fr[0] === 1); console.assert(monday_triple_fr[1] === "Monday"); console.assert(monday_triple_fr[2] === "Associé à la Lune"); let monday_triple_en: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_en[0], ]; console.assert(monday_triple_en[0] === 1); console.assert(monday_triple_en[1] === "Monday"); console.assert(monday_triple_en[2] === "associated with the Moon"); // On se fait un type pour ajouter le nom de la langue type Meaning_of_the_day = { lang: String, meaning: (Week | String)[][], }; //fonction d'affichage du type Meaning_of_the_day const display_motd = (motd: Meaning_of_the_day) => { motd.meaning.forEach(day => console.table(`${Week[day[0] as Week]}: ${day[1]}.(${motd.lang})`) ) }; //fonction d'assertion sur le type Meaning_of_the_day // afin de verifier la concordance du contenu avec // motd_arr_#lang# const test_motd = ( motd: Meaning_of_the_day, motd_arr: String[] ) => { console.assert(motd.lang.length === 2) for (const [i, value] of motd.meaning.entries()) { console.assert(value[1] === motd_arr[i]); } }; let motd_fr: Meaning_of_the_day = { lang: "fr", meaning: [ [Week.Monday, motd_arr_fr[0]], [Week.Tuesday, motd_arr_fr[1]], [Week.Wednesday, motd_arr_fr[2]], [Week.Thursday, motd_arr_fr[3]], [Week.Friday, motd_arr_fr[4]], [Week.Saturday, motd_arr_fr[5]], [Week.Sunday, motd_arr_fr[6]], ], } console.log("---------"); console.log("display_motd(motd_fr):"); display_motd(motd_fr); test_motd(motd_fr, motd_arr_fr) let motd_en: Meaning_of_the_day = { lang: "en", meaning: [ [Week.Monday, motd_arr_en[0]], [Week.Tuesday, motd_arr_en[1]], [Week.Wednesday, motd_arr_en[2]], [Week.Thursday, motd_arr_en[3]], [Week.Friday, motd_arr_en[4]], [Week.Saturday, motd_arr_en[5]], [Week.Sunday, motd_arr_en[6]], ], } console.log("---------"); console.log("display_motd(motd_en):"); display_motd(motd_en); console.log("---------"); test_motd(motd_en, motd_arr_en); // Un tuple (triple) utilisant le type // Meaning_of_the_day pour peupler le meaning let motd_triple: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_fr.meaning[0][1] as String ]; console.assert(motd_triple[0] === 1); console.assert(motd_triple[1] === "Monday"); console.assert(motd_triple[2] === "Associé à la Lune");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="void_never">Vacío y Nunca</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Le type void est l'opposé du type any // c'est l'absence de type. function verify_writers_length(): void { console.assert(writers.length > 0); } verify_writers_length(); const verify_writers_length_arrow = (): void => console.assert(writers.length > 0); verify_writers_length_arrow(); //Type of et never let value = 30; console.assert(typeof value === "number"); //never: qqchs qui n'arrive jamais function foo(x: String | Number): Boolean { if (typeof x === "string") { return true; } else if (typeof x === "number") { return false; } return fail("Error!") } function fail(message: String): never { throw new Error(message as string); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">Clases y interfaces</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les classes: * members, * visibility, * nommage, * accesseurs * scope identifier: static,private,protected * * convention de nommage : * Les membres private sont préfixés avec un _ * */ class Member { username: String = ""; email: String = ""; private _password: String = ""; readonly signup_date: Date = new Date(Date.now()); constructor(username: String, email: String) { this.username = username; this.email = email; } get password(): String { return this._password; } set password(new_password: String) { this._password = new_password; } /** * Une fonction static qui initilise un member, * à partir d'un author */ static fromAuthor(author: { first_name: String, last_name: String, lang: String, century: Number }): Member { return new Member( `${author.first_name}.${author.last_name}`, `${author.first_name}.${author.last_name}@acme.com`, ); } }; let domenico = Member.fromAuthor(author); domenico.password = "test"; console.assert(domenico.email === "Domenico.Losurdo@acme.com"); console.assert(domenico.password === "test"); // Héritage enum Forms { Undefined = 0, Polygones = 1, Circle = 2, Straight = 3, Segment = 4, }; class Form { type: Forms = Forms.Undefined; }; class Rectangle extends Form { h: Number = 0; w: Number = 0; }; class Square extends Rectangle { side: Number = 0; }; /** * Interface donne un contrat à un type. * Les interfaces permettent de définir la structure d'un objet. */ interface IPerson { username: String; email: String; readonly signup_date: Date; } const user1: IPerson = { username: Member.fromAuthor(author)["username"], email: Member.fromAuthor(author)["email"], signup_date: Member.fromAuthor(author)["signup_date"], }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">El archivo tsconfig.json</h2> <div class="sectionbody"> <div class="paragraph"> <p>tsconfig.json</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-json" data-lang="json">{ /* Visit https://aka.ms/tsconfig to read more about this file */ "compileOnSave": true, "compilerOptions": { "target": "es2016", "module": "CommonJS", "noEmitOnError": true, "strict": true, "noImplicitAny": true, "esModuleInterop": true } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">Módulos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los módulos permiten organizar el código en varios archivos.</p> </div> <div class="paragraph"> <p>Ejemplo de nota :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Dans un fichier math.ts export const add = (a: number, b: number): number => a + b; // Dans un autre fichier import { add } from './math'; let result = add(2, 3);</code></pre> </div> </div> <div class="paragraph"> <p>python import sys data = sys.stdin.read() sys.stdout.write(data)</p> </div> </div> </div> <div class="sect1"> <h2 id="promesas">Promesas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Las promesas se utilizan para realizar operaciones asíncronas.</p> </div> <div class="paragraph"> <p>Ejemplo de cotización:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const promise = new Promise<string>((resolve) => { // Code asynchrone ici resolve("Succès"); }); promise.then((result) => { console.log(result); });</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>El async/await simplifica la gestión de las promesas.</p> </div> <div class="paragraph"> <p>Ejemplo de calificación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const fetchData = async (): Promise<void> => { const result = await someAsyncFunction(); console.log(result); };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Introducción typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generiques">Genéricos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los genéricos permiten crear componentes reutilizables con tipos dinámicos.</p> </div> <div class="paragraph"> <p>Ejemplo de puntuación :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const identity = <T>(arg: T): T => arg; const output = identity<string>("hello"); console.log(output);</code></pre> </div> </div> </div> </div> https://cheroliv.com//blog/2023/0062_memo_css_post.html Mon, 14 Aug 2023 00:00:00 +0000 blog/2023/0062_memo_css_post.html <div class="sect1"> <h2 id="toc">Tabla de contenidos</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">Buenos enlaces</a></p> </li> <li> <p><a href="#repo">Repositorio y ejemplo de código</a></p> </li> <li> <p><a href="#toc_inicio">[toc_inicio]</a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">Buenos enlaces</h3> <div class="paragraph"> <p><a href="#toc">Tabla de contenidos</a></p> </div> </div> <div class="sect2"> <h3 id="repo">Repositorio y ejemplo de código</h3> <div class="paragraph"> <p>repositorio de GitHub:https://github.com/cheroliv/css-codebase[css-codebase, window = "_blank]</p> </div> </div> <div class="sect2"> <h3 id="toc_début"><span class="underline">Inicio CSS</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#inicio_intro">[inicio_intro]</a></p> </li> <li> <p><a href="#début_texts">Los textos</a></p> </li> <li> <p>inicio_background</p> </li> <li> <p>inicio_boxes</p> </li> <li> <p><a href="#inicio_flexbox">Flexbox</a></p> </li> <li> <p><a href="#inicio_grid">Grid</a></p> </li> <li> <p><a href="#inicio_abs_pos">[inicio_abs_pos]</a></p> </li> <li> <p><a href="#inicio_responsive">[inicio_responsive]</a></p> </li> <li> <p><a href="#principio_conclusion">[principio_conclusion]</a></p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">Tabla de contenidos</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="début_intro">Introducción y puesta en marcha</h2> <div class="sectionbody"> <div class="paragraph"> <p>Intro basado en este video:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/iSWjmVcfQGg?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> <div class="paragraph"> <p>repositorio de github:https://github.com/cheroliv/css-codebase/début_css/[inicio css, window = "_blank]</p> </div> <div class="paragraph"> <p>fuente de memo:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message" ></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p>Vincular el archivo style.css a la página html:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"></head> <link rel="stylesheet" href="style.css" /> </head></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">Los textos</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* import remote de font sur l'ensemble de la feuille*/ @import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); /* import local de font */ @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* body est le parent de toutes les balises, qu'il contient, donc je le déclare avant, pour la logique de précédence de parent */ body { /* si DMSerif n'est pas trouvé alors il se rabat sur Verdana*/ font-family: "DMSerif", Verdana; } /* va styliser toutes les balises h1, celles de body sont surchargés, par la déclaration présente */ h1 { text-transform: uppercase; /* espacement entre les lettres en pixel*/ letter-spacing: 3px; /* alignement du texte*/ text-align: center; /* Les tailles de polices doivent être en REM (rem = root em). Le REM se base pas sur l'élément parent pour obtenir sa taille mais sur l'élément racine. Ainsi 1rem prendra sa valeur de la font-size de votre document (body ou html).*/ font-size: 2.5rem; /* ombrage du texte */ text-shadow: 3px /* offset-x */ 3px /* offset-y */ 8px /* blur-radius */ #00000042/* color */; /* couleur du texte */ color: #ab0ef4; /*attibuer les polices(font): liste, ordonnée par priorité, de polices à utiliser pour mettre en forme le texte de l'élément ciblé.*/ font-family: "Oswald", sans-serif; /* surligner le text*/ text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_background">Fondo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; /* 100VH = 100% de la taille de l'écran (viewport height) min afin de ne pas bloquer la possibilité d'avoir un plus grand */ min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_boxes">Las cajas (boxes)</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* *: létoile donne du style a tous les éléments. Ensuite remettre un à un les parametres par defaut afin d'eviter les stylisation inattendu.*/ * { /* surcharge de base tous les elements à padding 0*/ margin: 0; /* surcharge de base tous les elements à padding 0*/ padding: 0; } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; /* quelque soit la taille de l'écran, la boite fait toujours 90% de la taille de la page, les 10% restant sont une marge à droite, pour avoir 5% de chaque coté on ajoute une margin, tel que [0, auto]*/ width: 90%; /* haut bas prend 0, et gauche droite prend auto(center cad meme de chaque cotés)*/ margin: 0 auto; /* on ajoute des bords a notre boite*/ border: 2px solid rgb(0, 140, 255); /* on arrondis les coins de la boite*/ border-radius: 20px 20px 0 0; /* ombrage sur la boite*/ box-shadow: 0px 0px 20px 4px #81cfc6; /* marge interrieure de la boite sur tous les cotés*/ padding: 15px; } h2 { /* afin de recuprer le comportement par defaut qui a ete surchargé par l'operateur étoile*/ margin: 0; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="inicio_flexbox">Flexbox</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } /* le point permet d'acceder à la classe d'un composant*/ .flexbox { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } /* FLEXBOX */ /* Sert à répartir équitablement des éléments sur la page */ .flexbox ul { padding: 0; /* aligne les éléments enfants de ul(les li)*/ display: flex; /* reparti convenablement(équitablement les li sur la page) */ justify-content: space-around; } /* ce style concerne les li de la classe, flexbox des balises qui y font referencent*/ .flexbox li { /* suprime les boules des éléments de la list li*/ list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; /* Centrer un unique élément verticalement et horizontalement */ display: flex; justify-content: center; align-items: center; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="inicio_grid">Grid</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para distribuir elementos de manera un poco más complejo que con flexbox, con un sistema de cuadrícula, entre otros.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } /* GRID */ .grid-container { display: grid; /* séparatuion de la grille en deux(à ses deux enfants), avec à gauche 30% pour l'image et à droite 70% pour le formulaire*/ grid-template-columns: 30% 70%; } /* sizing de l'image css-logo contenu dans la classe grid qui est dans le parent grid-container*/ .grid img { /* l'image remplt 80% de part de grille*/ width: 80%; margin: 20px auto; display: block; } form { display: grid; /* deux colonnes de chacune 1 fraction*/ grid-template-columns: 1fr 1fr; /* trois rangés de chacune 1 fraction*/ grid-template-rows: 1fr 1fr 1fr; /* structuration sous forme de template de notre repartition des composants enfants de la forme*/ grid-template-areas: "i1 i2"/* i1: input1, i2:input2*/ "ta ta"/*ta: text area */ "vi bt"/*vi:, bt: bouton */; } /* on donne du style sur deux éléments en meme temps en les listant avant les parentheses*/ input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } /* donner du style uniquement la textearea*/ textarea { /* renseigner le nommage pour le grid template area*/ grid-area: ta; height: 40px; /* empeche le cassage du style de la page en empechant le resizing de la textarea du formulaire*/ resize: none; } /* pour pointer un id d'élément html on utilise la notation préfixe # */ #btn-submit { /* renseigner le nommage*/ grid-area: bt; /* change le le symbole de curseur souris quand il survole sur le bouton*/ cursor: pointer; background: cyan; transition: 0.2s; } /* au survole(hover) de la souris le bouton change de comportement*/ #btn-submit:hover { background: darkblue; /* couleur de text du bouton devient blanc*/ color: white; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_début"><span class="underline">Inicio CSS</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">Position absolute</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } /* ABSOLUTE */ /* Sans élément en Relative, de base, l'élément en absolute l'est par rapport au Body */ /* Il faut mettre une position relative au parent pour contraindre l'élément en absolute dans ses frontières */ .absolute { /* position relative par rapport à son parent, donc contenu dans les frontieres de son parents*/ position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: /*traslate de 50% de la taille du cercle, pour etre centré par rapport au centre du cercle, plutot que sur son bord gauche par défaut.*/ translateX(-50%); top: 100px; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_responsive">El responsive</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; /* pour etre plus responsive on peut passer la taille en vw(view port width) pour qu'elle s'adapte à la taille de l'ecran*/ font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; /* permet en media query de la centrer en petit écran*/ display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } .absolute { position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: translateX(-50%); top: 100px; } /* RESPONSIVE: a partir des tailles d'ecran permet de surcharger les reglages definis plus haut */ @media screen and (max-width: 900px) { .grid-container { display: block; } .grid-container img { width: 40%; } } @media screen and (max-width: 610px) { .flexbox ul { flex-direction: column; align-items: center; } form { grid-template-columns: 1fr; grid-template-rows: 1fr; grid-template-areas: "i1" "i2" "ta" "bt"; } input, textarea { font-size: 0.8rem; } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inicio">[toc_inicio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_conclusion">Depuración & Conclusión</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* all elements: supprime les comportements par défaut*/ * { /* les marges à zéro*/ margin: 0; /* les parge internes(padding) à zéro*/ padding: 0; /* tous les bords avec un cadre rouge de 2px. qui est ou et qui fait quoi...*/ border: 2px solid red; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_début"><span class="underline">Inicio CSS</span></a></p> </div> </div> </div> https://cheroliv.com//blog/2023/0061_memo_html_post.html Sun, 13 Aug 2023 00:00:00 +0000 blog/2023/0061_memo_html_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_buenos_vínculos">buenos vínculos</a></li> <li><a href="#_repositorio_y_ejemplo_de_código">Repositorio y ejemplo de código</a></li> </ul> </div> <div class="sect1"> <h2 id="_buenos_vínculos">buenos vínculos</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">html</div> <ul> <li> <p><a href="https://htmlcheatsheet.com">htmlcheatsheet.com</a>: HTML Cheatsheet</p> </li> </ul> </div> <div class="ulist"> <div class="title">font</div> <ul> <li> <p><a href="https://fontawesome.com">fontawesome.com</a>biblioteca de iconos</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a>: Iconos nativos en HTML</p> </li> </ul> </div> <div class="ulist"> <div class="title">caracteres especiales y escapes</div> <ul> <li> <p><a href="https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/" class="bare">https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/3614344/13104550" class="bare">https://stackoverflow.com/a/3614344/13104550</a></p> </li> <li> <p><a href="https://html.spec.whatwg.org/multipage/named-characters.html" class="bare">https://html.spec.whatwg.org/multipage/named-characters.html</a></p> </li> </ul> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_repositorio_y_ejemplo_de_código">Repositorio y ejemplo de código</h2> <div class="sectionbody"> <div class="paragraph"> <p>repositorio de GitHub:https://github.com/cheroliv/html-codebase[html-codebase, ventana = "_blank]</p> </div> <div class="paragraph"> <p>memorándum fuente:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- Le titre de la page --> <title>Cours HTML</title> <!-- Icone de l'onglet --> <link rel="shortcut icon" href="html-logo.png" /> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" /> </head> <body> <header> <h1>Texte - Titre H1</h1> <p> <em>em pour mettre en italique</em>, <strong>strong pour mettre en gras</strong> <span>L'élement en span ne revient pas à la ligne</span>. </p> <p> Lorem ipsum dolor sit amet consectetur adipisicing elit. Exercitationem cumque ratione veniam officiis nulla a debitis at facilis sed dignissimos. </p> </header> <section> <div> <h2>Photo - Titre H2</h2> <img src="./img-1.jpg" alt="image-arbre" height="200" /> </div> <div> <h3>Liste - Titre H3</h3> <ul> <li>UL = unordered list</li> <li>UL = unordered list</li> <li>UL = unordered list</li> </ul> <ol> <li>OL = ordered list</li> <li>OL = ordered list</li> <li>OL = ordered list</li> </ol> </div> <div> <h4>Tableaux - Titre H4</h4> <table border="4" cellpadding="10" cellspacing="4" style="text-align: center"> <thead> <tr> <th>Col 1</th> <th>Col 2</th> <th>Col 3</th> </tr> </thead> <tbody> <tr> <td rowspan="2">Row 1 Cell 1</td> <td>Row 1 Cell 2</td> <td>Row 1 Cell 3</td> </tr> <tr> <td>Row 2 Cell 2</td> <td>Row 2 Cell 3</td> </tr> <tr> <td colspan="3">Row 3 Cell 1</td> </tr> </tbody> </table> </div> <div> <h5><span>♖</span> Liens - Titre H5</h5> <a href="https://htmlcheatsheet.com/" target="_blank">HTML Cheatsheet</a> <br /> <a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank">Icones natifs en HTML</a> </div> <div> <h6><i class="fas fa-video"></i> Vidéo - Titre H6</h6> <video src="video.mp4" height="150" autoplay loop muted></video> </div> </section> <br /> <!-- Formulaires en HTML --> <section> <h2>Formulaire</h2> <form action="/action.php" method="post"> <label for="name">Nom</label> <input id="name" type="text" placeholder="Entrez votre nom" /><br /> <label for="number">Entrez votre age</label> <input type="number" id="number-age" value="15" oninput="document.getElementById('range-age').value=this.value"> <input type="range" id="range-age" min="0" max="100" oninput="document.getElementById('number-age').value=this.value"><br /> <!-- Input select --> <label for="gender">Genre</label> <select id="gender"> <option selected="selected" value="Homme">Homme</option> <option value="Femme">Femme</option> </select><br /> <!-- Input radio --> <div> <input type="radio" name="type" id="human" checked /> <label for="human">Humain</label> <input type="radio" name="type" id="dog" /> <label for="dog">Chien</label> <input type="radio" name="type" id="cat" /> <label for="cat">Chat</label> </div> <textarea cols="20" rows="5" placeholder="Votre message..."></textarea><br /> <!-- Input Checkbox --> <label><input type="checkbox" />Accepter les CGV</label> <br /> <input type="submit" value="Submit" /> </form> </section> <br /> <!-- Mail & envoi de fichiers --> <footer> <a href="mailto:fs@gmail.com">Ecrivez-moi !</a> <br /> <a href="notice.txt" download="nom-du-fichier">Télécharger la notice</a> <details> <summary>Plus d'infos</summary> <p> Lorem ipsum dolor, sit amet consectetur adipisicing elit. Harum, repellendus. </p> </details> </footer> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> https://cheroliv.com//blog/2023/0060_memo_js_post.html Fri, 4 Aug 2023 00:00:00 +0000 blog/2023/0060_memo_js_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>repositorio github:https://github.com/cheroliv/js-codebase[js-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">Introducción JavaScript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#start">Variables, operadores aritméticos y cadenas de caracteres</a></p> </li> <li> <p><a href="#arrays">Los arrays</a></p> </li> <li> <p><a href="#funciones">[funciones]</a></p> </li> <li> <p><a href="#param_x_scope">Parámetros y alcances</a></p> </li> <li> <p><a href="#objects">Los objects</a></p> </li> <li> <p><a href="#bucles">[bucles]</a></p> </li> <li> <p><a href="#const_var_let">Const, var y let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">Rest y spread operators</a></p> </li> <li> <p><a href="#desestructuración">[desestructuración]</a></p> </li> <li> <p><a href="#import_export">Importación y exportación de módulos</a></p> </li> <li> <p><a href="#classes">Uso de las clases</a></p> </li> </ol> </div> <div class="paragraph"> <p>índice.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <title>Document</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> </head> <body> index <script src="01_start.js"></script> <script src="02_arrays.js"></script> <script src="03_functions.js"></script> <script src="04_param_x_scope.js"></script> <script src="05_objects.js"></script> <script src="06_loops.js"></script> <script src="07_const_var_let.js"></script> <script src="08_rest_and_spread_operators.js"></script> <script src="09_destructuring.js"></script> <script src="10_module_import_export.js"></script> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start">Variables, operadores aritméticos y cadenas de caracteres</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_start.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Variables */ //une variable stupide var my_variable = "dummy variable"; console.log(my_variable); //assertion console.assert(my_variable === "dummy variable"); var username = "cheroliv"; console.log(username); console.assert(username === "cheroliv"); //concaténation de string console.assert(username === "cher" + "oliv"); /** * Opérateur arithmétique: + - * / % */ //integer var x = 10; var y = 5; var z = 20; console.log(x + y); console.assert(x + y === 15); console.log(x + y - z); console.assert(x + y - z === -5); console.log(x - y); console.assert(x - y === 5); console.log(x * y); console.assert(x * y === 50); console.log(x / y); console.assert(x / y === 2); console.log("---------"); x = 20; y = 10; console.log(x + y); console.assert(x + y === 30); console.log(x + y - z); console.assert(x + y - z === 10); console.log(x - y); console.assert(x - y === 10); console.log(x * y); console.assert(x * y === 200); console.log(x / z); console.assert(x / z === 1); //Littéraux de gabarits pour string avec backstick ` //Template literals (Template strings) console.assert(`typeof z: ${typeof z}` === "typeof z: number"); console.log(`x is type of : ${typeof x}`); console.log(`y is type of : ${typeof y}`); console.log(`z is type of : ${typeof z}`); //typeof: donne le type de la variable console.assert(typeof x === "number"); console.assert(typeof y === "number"); console.assert(typeof z === "number"); console.log("---------"); /** * Incrémenation/décrémentation */ //incrémantation/décrémentation préfixe console.log(++x) //incrémenté puis affiché: 21 console.log(x) //la valeur incrémenté: 21 //incrémantation/décrémentation suffixe console.log(y++) //affiche la valeur sans incrémenation puis incrémente: 10 console.log(y) //la valeur incrémenté: 11 //décrémentation x--; y--; console.assert(x === 20); console.assert(y === 10); /** * String: chaine de caractères */ console.log(`username: ${username}`); //taille de la string console.log(`username.length: ${username.length}`); console.assert(username.length === 8); console.assert(username.length === "cheroliv".length); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">Los arrays</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_arrays.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les arrays */ // auteurs [["nom ", "prénom", "pays"]] var writers = [ ["Karl", "Marx", "de"], ["Jean-Jacques", "Rousseau", "fr"], ["Victor", "Hugo", "fr"], ["René", "Descartes", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["Georg", "Hegel", "de"], ["Friedrich", "Engels", "de"], ] console.table(writers); // accés aux élèments du tableau console.log(writers[0]); console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); //sauvegarder la valeur du prénom de Marx var karl = writers[0][0] //éditer un élement du tableau, le prénom de Marx writers[0][0] = "Karlito" console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karlito, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl" === karl); //remettre la valeur initale du prénom de Marx writers[0][0] = karl; console.assert(`${karl}, Marx (de)` === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.log("---------"); /** * Arrays: map/forEach/pop/push/slice/sort/shift/unshift */ var numbers = [1, 5, 4, 3, 2]; console.log("Iterate with forEach"); // parcourir avec array.forEach numbers.forEach((it) => console.log(it)); console.log("---------"); console.log("Iterate with map"); // parcourir avec array.map numbers.map((it) => console.log(it)); console.log("---------"); //afficher les éléments sur une ligne //génère la string avec le formatage des nombres const numbersString = (numberArray) => { var consoleOutput = new String(); numberArray.forEach(number => consoleOutput += `${number}, `); return consoleOutput = consoleOutput.substring(0, consoleOutput.length - 2); }; //affiche la chaine entre crochets dans la console const displayNumbers = (numbersStr) => { console.log(`[${numbersString(numbersStr)}]`); }; console.log("orginal number array") displayNumbers(numbers); console.log("---------"); //push: ajoute à la fin console.log("push"); numbers.push(6); displayNumbers(numbers); console.log("---------"); //pop: suprime le dernier console.log("pop"); numbers.pop(); displayNumbers(numbers); console.log("---------"); //unshift: ajouter le parametre au debut de l'array console.log("unshift"); numbers.unshift(0); displayNumbers(numbers); console.log("---------"); //shift: supprime le premier element de l'array console.log("shift"); numbers.shift(); displayNumbers(numbers); console.log("---------"); //slice: renvoi l'array entre les positions en argument console.log("slice"); var sliceNumbersResult = numbers.slice(2, 4); displayNumbers(sliceNumbersResult); console.log("---------"); //sort asc console.log("sort asc"); var ascSort = numbers.sort((a, b) => a - b); displayNumbers(ascSort); console.log("---------"); //sort desc console.log("sort desc"); var descSort = numbers.sort((a, b) => b - a); displayNumbers(descSort); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">Las funciones</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les fonctions */ //function style legacy function sayHelloWorldLegacy() { console.log("Hello world legacy!"); } sayHelloWorldLegacy(); function sayHelloLegacy(firstName, lastName, style) { console.log(`Hello ${firstName}, ${lastName} (${style})`); } sayHelloLegacy("Cher", "Oliv", "legacy"); console.log("---------"); //function style arrow const sayHelloWorld = () => console.log("Hello world!"); sayHelloWorld(); const sayHello = (firstName, lastName) => console.log(`Hello ${firstName}, ${lastName}`); sayHello("Cher", "Oliv"); console.log("---------"); var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ] const displayAuthors = (authorsArray) => authorsArray.forEach(author => console.log(`${author[0]} ${author[1]}, (${author[2]})`) ); displayAuthors(authors); console.log("---------"); /** * valeur par défaut des parametres d'une fonctions */ const add = (a = 0, b = 0) => a + b; console.assert(add() === 0) console.assert(add(1) === 1) console.assert(add(1, 1) === 2) console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">Parámetros y alcances</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_param_x_scope.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//global scope: visible partout, dans et hors functions var global; const foo = () => { //local scope: visible uniquement dans la fonction foo var bar = "bar" console.log(bar) } foo(); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">Los objects</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objects.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les objects */ var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; var hugo = { firstName: authors[7][0], lastName: authors[7][1], country: authors[7][2], }; var book = { author: hugo, title: "Les misérables" }; console.log(hugo); console.log(book); //accéder à un membre de l'objet par point console.log(hugo.country); //accéder à un membre de l'objet par crochet console.log(book["title"]); console.log(book.author.lastName); console.log(book["author"]["firstName"]); //ajouter une clé a un objet hugo.gender = "non binary"; console.assert(hugo.gender === "non binary"); //mettre à jour une clé hugo.gender = "male"; console.assert(hugo.gender !== "non binary"); console.assert(hugo["gender"] === "male"); //supprimer une clé delete hugo.gender; //verfier que l'objet ne contient pas la clé gender console.assert(!Object.keys(hugo).includes("gender")); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="loops">Los bucles</h2> <div class="sectionbody"> <div class="paragraph"> <p>06_loops.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les boucles: Itérer sur arrays et objets. */ console.log("for loop over array"); var numbers = [12, 10, 8, 6, 4, 2, 0]; for (number of numbers) { console.log(number); } console.log("---------"); console.log("for loop over object key"); var obj = { a: 1, b: 2, c: 3, d: 4 }; for (key in obj) { console.log(key); } console.log("---------"); console.log("for loop over object value"); for (value in obj) { console.log(obj[value]); } console.log("---------"); console.log("another for loop over authors array") var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; for (const [i, value] of authors.entries()) { console.log(`${value[0]}, ${value[1]} (${value[2]})`); } console.log("---------"); console.log("while loop over array") var i = 0 while (i < authors.length) { console.log(`${authors[i][0]}, ${authors[i][1]} (${authors[i][2]})`); i++; } console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var y let</h2> <div class="sectionbody"> <div class="paragraph"> <p>07_const_var_let.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * const X var X let */ //var x du if n'est pas confiné au scope du if const varTest = () => { var x = 1; console.log(x); console.assert(x === 1); if (true) { var x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x !== 1); console.assert(x === 2); } varTest(); console.log("---------"); //var x est global à tous les fichier js //chargés dans la page html //var x issue du fichier 1_start.js //ligne 46 console.log(x); console.assert(x === 20); console.log("---------"); //premier let x est confiné au scope de la fonction //le let x du if est confiné au scope du if const letTest = () => { let x = 1; console.log(x); console.assert(x === 1); if (true) { let x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x === 1); console.assert(x !== 2); } letTest(); console.log("---------"); /** * const: déclare un emplacement mémoire non réattribuable * c'est modifiable pour un array, * mais non réinitialisable; * ex: * const arr = [25, 27, 29] * arr = [5, 7] //impossible * arr[0]=20 // possible * ex: * const n = 1; * n = 3; //impossible */ const arr = [25, 27, 29] console.table(arr); arr[0] = 20 // possible console.table(arr); arr.pop() console.table(arr); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">Rest y spread operators</h2> <div class="sectionbody"> <div class="paragraph"> <p>08_resto_y_operadores_de_propagación.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateur de rest: * const add = (...operandes) => a + b; * ou avec parametres avec valeur par défaut * const add = (a=0, b=0, ...operandes) => a + b; */ /** * spread opérateur: * récupère l'ensemble des elements d'une collection, * dans un array */ const user_ages = [25, 56, 12, 58, 41, 62, 26]; const max_user_age = Math.max(...user_ages); const min_user_age = Math.min(...user_ages); console.assert(max_user_age == 62); console.assert(min_user_age == 12); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">Desestructuración</h2> <div class="sectionbody"> <div class="paragraph"> <p>09_destructuring.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * L'affectation par décomposition (destructuring) */ const user = { first_name: "Oliv", last_name: "Cher", nick_name: "cheroliv", gender: "male", is_adult: true }; console.log(user); //première façon d'initaliser des variables sans destructuration let first_name_legacy = user.first_name; let last_name_legacy = user.last_name; let nick_name_legacy = user.nick_name; let gender_legacy = user.gender; let is_adult_legacy = user.is_adult; console.assert("Oliv" === first_name_legacy); console.assert("Cher" === last_name_legacy); console.assert("cheroliv" === nick_name_legacy); console.assert("male" === gender_legacy); console.assert(true === is_adult_legacy); console.log("---------"); /** * Initialisation par déstructuration */ const { first_name, last_name, nick_name, gender, is_adult } = user; console.assert(user.first_name === first_name); console.assert(user.last_name === last_name); console.assert(user.nick_name === nick_name); console.assert(user.gender === gender); console.assert(user.is_adult === is_adult); /** * Intialisation par déstructuration des arrays */ //cible explicite const [a1, a2] = [15, 25, 17, 81, 51, 46]; console.assert(a1 === 15); console.assert(a2 === 25); //cible avec position par rapport aux index par virgules //je veux b3 à 46 const [b1, b2, , , , b3] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(b3 === 46); //déstructuration avec operateur de rest // je contruit un autre avec avec les elements // à partir du premier élèment non destructuré const [c1, c2, ...sub_arr] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(sub_arr.length === 4); console.assert(sub_arr[0] === 17); console.assert(sub_arr[1] === 81); console.assert(sub_arr[2] === 51); console.assert(sub_arr[3] === 46); // Une boucle pour comparer le resultat attendu for (const [i, value] of[15, 25, 17, 81, 51, 46].entries()) { //on reconstruit le tableau à chaque iteration console.assert([c1, c2].concat(sub_arr)[i] === value); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">Importación y exportación de módulos</h2> <div class="sectionbody"> <div class="paragraph"> <p>10_module_import_export.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Import et export de module * * Dans le fichier html * au niveau de la balise d'import de script * spécifier le type module * * 1er technique: import nommé des fonctions: * import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; * * 2eme technique: import global des fonction avec l'asterisque(*) * en préfixant l'import par un nommage du fichier importé: * import * as math from "./dummy_math_functions.js"; * * 3eme technique: import par alias avec le mot clé "as" * import { * sum as add, * minus as substract, * times as multiply, * div as divide, * rem as modulo * } from "./dummy_math_functions.js"; */ import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; console.assert(sum(1, 1) === 2); console.assert(minus(4, 2) === 2); console.assert(times(2, 2) === 4); console.assert(div(4, 2) === 2); console.assert(rem(4, 2) === 0);</code></pre> </div> </div> <div class="paragraph"> <p>dummy_math_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//sum const sum = (x, y) => x + y; // subtraction const minus = (x, y) => x - y; // multiplication const times = (x, y) => x * y; // division const div = (x, y) => x / y; // remainder: reste de la division euclidiene const rem = (x, y) => x % y; // log sum const sum_log = (x, y) => console.log(sum(x, y)); // log subtraction const minus_log = (x, y) => console.log(minus(x, y)); // log multiplication const times_log = (x, y) => console.log(times(x, y)); // log division const div_log = (x, y) => console.log(div(x, y)); // log remainder const rem_log = (x, y) => console.log(rem(x, y)); export { sum, minus, times, div, rem, sum_log, minus_log, times_log, div_log, rem_log };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">Uso de las clases</h2> <div class="sectionbody"> <div class="paragraph"> <p>11_clases.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Utilisation des classes */ //creation d'un objet class Account { constructor(username) { this.username = username; } }; const acc1 = new Account("cheroliv"); console.table(acc1); console.assert(acc1.username === "cheroliv"); console.log("---------"); //création d'un objet et ajout de getter et setter(accesseurs) class AccountInfo { constructor(username) { this._username = username; } get username() { return this._username; } /** * @param {(arg0: string) => void} new_username */ set new_username(new_username) { this._username = new_username; } }; const acc_info1 = new AccountInfo("cheroliv"); console.table(acc_info1); //accés au membre _username avec le getter username() console.assert(acc_info1.username === "cheroliv"); //update la valeur username de acc_info1 avec le setter acc_info1.new_username = "imrandeh"; console.assert(acc_info1.username === "imrandeh"); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introducción JavaScript</span></a></p> </div> </div> </div> https://cheroliv.com//blog/2022/0054_memo_cadrage_post.html Sat, 31 Dec 2022 00:00:00 +0000 blog/2022/0054_memo_cadrage_post.html <div class="sect1"> <h2 id="_encuadre">encuadre</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_taller_1_visión">Taller 1: Visión</h3> <div class="sect3"> <h4 id="_el_patrón_qqoqcp_quién_qué_dónde_cuándo_cómo_por_qué">El patrón “QQOQCP” – Quién, Qué, Dónde, Cuándo, Cómo, Por qué</h4> </div> <div class="sect3"> <h4 id="_2_el_product_vision_board">2. El Product Vision Board</h4> <div class="sect4"> <h5 id="_grupo_objetivo">Grupo objetivo</h5> <div class="paragraph"> <p>¿Quiénes son los usuarios que utilizan el producto o la oferta? (directo, indirecto)</p> </div> </div> <div class="sect4"> <h5 id="_necesidades">necesidades</h5> <div class="paragraph"> <p>¿Cuáles son las 5 necesidades principales de los usuarios clave de la aplicación?</p> </div> </div> <div class="sect4"> <h5 id="_producto">producto</h5> <div class="paragraph"> <p>¿Cuál es mi propuesta de valor? ¿Cuáles son las 5 funcionalidades principales del producto que permiten responder a los necesidades</p> </div> </div> <div class="sect4"> <h5 id="_objetivo_de_negocio">Objetivo de negocio</h5> <div class="paragraph"> <p>¿Cuáles son los criterios de éxito?</p> </div> </div> <div class="sect4"> <h5 id="_visión">Visión</h5> <div class="paragraph"> <p>Cuando las 4 columnas estén completas, deberás rellenar la parte vision del Product Vision Tablero en una frase completa.</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_taller_2_personasrecorridos_de_usuarios">Taller 2: Personas/Recorridos de usuarios</h3> <div class="ulist"> <div class="title">Definir para cada persona un recorrido de usuario:</div> <ul> <li> <p>¿Quién va a utilizar mi servicio? (objetivo)</p> </li> <li> <p>¿Qué quiere hacer? (Pero)</p> </li> <li> <p>¿Cómo va a hacerlo? (Recorrido del usuario)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_taller_3_zonificación_guion_gráfico_mapa_del_sitio">Taller 3: Zonificación, Guion gráfico, Mapa del sitio</h3> <div class="sect3"> <h4 id="_zonificación">Zonificación</h4> </div> <div class="sect3"> <h4 id="_2_storyboard">2. StoryBoard</h4> </div> <div class="sect3"> <h4 id="_3_mapa_del_sitio">3. Mapa del sitio</h4> </div> </div> <div class="sect2"> <h3 id="_taller_4_wireframemoodboard">Taller 4: Wireframe/Moodboard</h3> <div class="sect3"> <h4 id="_1_maquetas">1. Maquetas</h4> </div> <div class="sect3"> <h4 id="_2_moodboard">2. Moodboard</h4> </div> </div> <div class="sect2"> <h3 id="_taller_5_story_mapping_user_stories">Taller 5: Story Mapping/ User stories</h3> <div class="sect3"> <h4 id="_mapeado_de_historias_priorización_de_us">Mapeado de historias (priorización de US)</h4> </div> <div class="sect3"> <h4 id="_como_tipo_de_usuario_quiero_un_objetivo_para_que_una_razón">Como <tipo de usuario>, quiero <un objetivo> para que <una razón>.</h4> </div> </div> <div class="sect2"> <h3 id="_taller_6_backlog">Taller 6: Backlog</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">pendientes</a></p> </div> </div> <div class="sect2"> <h3 id="_taller_7_técnica_y_arquitectura">Taller 7: Técnica y Arquitectura</h3> </div> </div> </div> https://cheroliv.com//blog/2022/0053_memo_kotlin_post.html Sun, 29 May 2022 00:00:00 +0000 blog/2022/0053_memo_kotlin_post.html <div class="sect1"> <h2 id="_buenos_enlaces">Buenos enlaces</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">kotlinlang playground</a>+</p> </div> <div class="paragraph"> <p><a href="https://arrow-kt.io/">arrow.kt</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/MVIKotlin/">MVI:Model View Intent</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">esencial</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">Descomponer</a><br></p> </div> </div> </div> <div class="sect1"> <h2 id="_trozos_de_código_varios">Trozos de código varios</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_map_reduce">map reduce</h3> <div class="paragraph"> <p>Convertir una lista de mordida hacia una lista de cadena y resumir la lista de cadena<br> en una cadena que contiene la concatenación. Cómo registrar la solicitud enviada(requestBodyContent:byte[])</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">log.info( requestBodyContent!!.map { it.toInt().toChar().toString() } .reduce { request: String, s: String -> request + s } )</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_enum_y_clases_selladas">enum y clases selladas</h3> <div class="paragraph"> <p>post: <a href="0038_training_kotlin_enum_sealed_class_post" target=""_blank">entrenamiento kotlin enum clase sellada</a></p> </div> </div> <div class="sect2"> <h3 id="_interfaz_funcional_y_referencia_de_método">interfaz funcional y referencia de método</h3> <div class="paragraph"> <p>Se puede transformar una entidad en modelo de dominio de DTO con una referencia de método (estilo funcional - Java 8)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findAllByLoginNot( pageable:Pageable, login:String) :Page<UserDto> { return userDao.findAllByLoginNot( pageable, login).map(::fromEntity) }</code></pre> </div> </div> <div class="paragraph"> <p>unahttps://stackoverflow.com/a/22245383/837404[buena explicación]</p> </div> </div> <div class="sect2"> <h3 id="_capturar_la_salida_estándar">Capturar la salida estándar</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOF { private val standardOut: PrintStream? = out private val outputStreamCaptor = ByteArrayOutputStream() @BeforeTest fun setUp() = setOut(PrintStream(outputStreamCaptor)) @AfterTest fun tearDown() = setOut(standardOut) @Test fun `three times dope`() { 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_cuál_es_la_diferencia_en_kotlin_entre_apply_run_let_also_use_y_with">¿Cuál es la diferencia en Kotlin entre apply, run, let, also, use y with?</h3> <div class="paragraph"> <p><strong>Comparación de las funciones Kotlin y Uso de las Formas Lambda Reference</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_apply">apply</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Introducción Las funciones Kotlin`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`Ofrecen diferentes maneras de tratar los objetos. Cada una tiene sus propios casos de uso y comportamientos. Además, las formas de lambda por referencia permiten hacer el código más legible y reutilizable al referirse a funciones lambda existentes.</div> <p>La función`apply`se utiliza para configurar un objeto durante su creación. Devuelve el objeto sobre el cual se llama.</p> </div> <div class="paragraph"> <p>Ejemplo con referencia lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply(::configureObject)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply { // configuration des propriétés de someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ejecutar">ejecutar</h2> <div class="sectionbody"> <div class="paragraph"> <p>La función`run`se utiliza para ejecutar un bloque de código en un objeto y devuelve el resultado del bloque de código.</p> </div> <div class="paragraph"> <p>Ejemplo con lambda referencia :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run(::someFunction)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_let">let</h2> <div class="sectionbody"> <div class="paragraph"> <p>La función`let`se utiliza para ejecutar un bloque de código sobre un objeto y devuelve el resultado del bloque de código.</p> </div> <div class="paragraph"> <p>Ejemplo con lambda reference:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let(::processObject)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_también">también</h2> <div class="sectionbody"> <div class="paragraph"> <p>La función`also`se utiliza para realizar una acción adicional sobre un objeto y devuelve el objeto sobre el cual se llama.</p> </div> <div class="paragraph"> <p>Ejemplo con referencia lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also(::performAdditionalAction)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also { // action additionnelle sur someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_use">use</h2> <div class="sectionbody"> <div class="paragraph"> <p>La función`use`se utiliza para trabajar con recursos que deben cerrarse después de su uso. Llama automáticamente la función`close`al final del bloque.</p> </div> <div class="paragraph"> <p>Ejemplo con referencia lambda:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use(::useResource)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use { // travailler avec la ressource }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_con">con</h2> <div class="sectionbody"> <div class="paragraph"> <p>La función`with`se utiliza para llamar a varios métodos en un objeto sin repetir su nombre y devuelve el resultado de la última expresión.</p> </div> <div class="paragraph"> <p>Ejemplo con referencia lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject, ::processWithObject)</code></pre> </div> </div> <div class="paragraph"> <p>Ejemplo con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject) { // appeler des méthodes sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> <div class="paragraph"> <p>Utilizando las formas lambda reference o los bloques`{}`, puedes encapsular la lógica en funciones distintas, mejorando así la legibilidad y la reutilizabilidad del código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_let_function_en_kotlin">let Function en Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">¿Let devuelve el objeto con los efectos de borde aplicados sobre él o en el estado inicial de entrada según (let) ?</div> <p>La función`let`En Kotlin se utiliza para realizar operaciones en un objeto y devolver un resultado diferente. Sin embargo, es importante destacar que la función`let`no modifica el estado inicial del objeto sobre el que se llama.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>firma</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>inline fun <T, R> T.let(block: (T) → R): R</code></p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Uso</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La función`let`Se utiliza comúnmente para aplicar transformaciones a un objeto y obtener un resultado basado en estas transformaciones.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Resultado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">El valor devuelto por la función`let`es el resultado de la expresión lambda pasada como argumento, generalmente el resultado de las operaciones realizadas sobre el objeto.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Efectos de borde</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aunque la función`let`puede tener efectos secundarios en el objeto cuando se usa en la expresión lambda, no modifica el estado inicial del objeto mismo.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Así, la función`let`es una forma elegante de realizar operaciones sobre un objeto mientras se obtiene un resultado derivado, manteniendo al mismo tiempo la integridad del objeto original.</p> </div> </div> </div> https://cheroliv.com//blog/2022/0052_memo_jvm_post.html Sat, 28 May 2022 00:00:00 +0000 blog/2022/0052_memo_jvm_post.html <div class="sect1"> <h2 id="toc">tabla de contenidos</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">cadenas de caracteres y caracteres</a></p> </li> <li> <p><a href="#math">números y matemáticas</a></p> </li> <li> <p><a href="#fecha">[fecha]</a></p> </li> <li> <p><a href="#java8date">fechas y horas java8</a></p> </li> <li> <p><a href="#arrCol">arreglos y colecciones</a></p> </li> <li> <p><a href="#sysProp">System.Properties</a></p> </li> <li> <p><a href="#threads">Hilos</a></p> </li> <li> <p><a href="#regex">Expresiones regulares</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">cadenas de caracteres y caracteres</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.Collator import java.util.* import kotlin.test.* class StringsTest { @Test fun `chaines de caractères et caractères`() { //inférence de type val s = "C'est" assertEquals("C'est", s) //concaténation val t: String = s + " le moment." assertEquals("C'est le moment.", t) // StringBuilder val t1: String = s + buildString { append(" le moment.") } assertEquals("C'est le moment.", t1) //interpolation val t2 = "$s le moment." assertEquals("C'est le moment.", t2) //multiligne chaine de caractères val t3 = """$s le moment.""" assertEquals("C'est le moment.", t3) //conversion de type val t4 = t + " " + 23.4 assertEquals("C'est le moment. 23.4", t4) val t5 = 'C'.toString() assertEquals("C", t5) //taille de la chaine de caractères assertEquals(16, t.length) //sous-chaine d'une chaine de caractères //retourne une chaine de caractères contenant, //les caractères aux positions x à y-1 //sub = t.substring(x, y) //t = "C'est le moment." //retourne les caractères 6 et 7 var sub = t.substring(6, 8) assertEquals("le", sub) //retourne les caractères 0 à 4 sub = t.substring(0, 5) assertEquals("C'est", sub) //la longueur d'une sous-chaine est toujours égale (y-x) val numChars = sub.length assertEquals(5 - 0, numChars) //extraction des caractères d'une chaine assertEquals('e', t.elementAt(2)) assertEquals('e', t.get(2)) assertEquals('e', t[2]) //conversion d'une chaine en tableau de caractères val ca = t.toCharArray() assertEquals(t.length, ca.size) t.mapIndexed { index, char -> assertEquals(char, ca[index]) } //place les 4 premiers caractères de t1 //dans le tableau ca a la position 2 (t as java.lang.String).getChars( /* srcBegin = */ 0, /* srcEnd = */ 3, /* dst = */ ca, /* dstBegin = */ 1 ) assertEquals("CC'et le moment.", String(ca)) //colle tous les caractères dans un meme string assertEquals("CC'et le moment.", ca.concatToString()) //to lower case assertEquals("c'est le moment.", t.toLowerCase()) assertEquals("c'est le moment.", t.lowercase()) //to upper case assertEquals("C'EST LE MOMENT.", t.toUpperCase()) assertEquals("C'EST LE MOMENT.", t.uppercase()) //comparaison de chaines de caractères //t = "C'est le moment." assertFalse(t.equals("hello")) assertFalse(t == "hello") //ignore la casse assertTrue(t.equalsIgnoreCase("C'EST LE MOMENT.")) assertTrue(t.equals("C'EST LE MOMENT.", ignoreCase = true)) //démarre par assertTrue(t.startsWith("C'est")) //se finit par assertTrue(t.endsWith("le moment.")) //compareTo //retourne une valeur < 0, car s est //alphabétiquement avant "N'est" val r1: Int = s.compareTo("N'est") assertTrue(r1 < 0) //variante ignorant la casse val r1Prime: Int = (s as java.lang.String).compareToIgnoreCase("n'est") assertTrue(r1Prime < 0) //retourne 0 si les chaines sont equivalente val r2: Int = s.compareTo("C'est") assertEquals(0, r2) //retourne une valeur > 0 car s vient apres "B'est" val r3: Int = s.compareTo("B'est") assertTrue(r3 > 0) //Recherche de caractères et de sous-chaines de caractères //recherche de caractères //position du premier caractères 't' var pos = t.indexOf('t') assertEquals(4, pos) //position du suivant pos = t.indexOf('t', pos + 1) assertEquals(14, pos) //retour d'érreur -1 si absence de suivant pos = t.indexOf('t', pos + 1) assertEquals(-1, pos) //position du dernier 't' dans la chaine: 14 pos = t.lastIndexOf('t') assertEquals(14, pos) //recherche de 't' vers l'arrière a partir du caractères 13 pos = t.lastIndexOf('t', pos - 1) assertEquals(4, pos) //recherche de sous-chaines //retourne 2 pos = t.indexOf("est") assertEquals(2, pos) //"est" n'apparait qu'une seule fois: retourne -1 pos = t.indexOf("est", pos + 1) assertEquals(-1, pos) //recherche d'une sous-chaine depuis l'arrière //t = "C'est le moment." //retourne 6 pos = t.lastIndexOf("le ") assertEquals(6, pos) //extrait depuis la position 9, //renvoi toute la chaine après "le " val noun = t.substring(pos + 3) assertEquals(-1, noun.indexOf("le ")) //remplacement de toutes les instances d'un caractère //par un autre caractère //ne fonctionne que avec les caractères, pas les chaines val exclaim: String = t.replace('.', '!') assertEquals('!', exclaim.get(exclaim.length - 1)) assertEquals(exclaim.length - 1, exclaim.indexOf('!')) assertEquals(-1, exclaim.indexOf('.')) //suppression des espaces blancs //au début et à la fin d'une chaine val noextraspaces = t.trim() assertNotEquals(' ', noextraspaces.get(0)) assertNotEquals(' ', noextraspaces.get(noextraspaces.length - 1)) //extraction des instances uniques de chaines de caractères //avec intern() val s1 = s.intern() assertEquals(s, s1) val s2 = "C'est".intern() assertEquals("C'est", s2) assertEquals(s1, s2) //StringBuilder pour manipuler les caractères d'une chaine de caractères //crée un tampon StringBuilder à partir d'une chaine de caractères val b = StringBuilder("N'est") //extrait et définit des caractères individuel du tampon StringBuilder //le caractères à l'index 0 val c: Char = b.get(0) assertEquals('N', c) //modifier le premier caractère de la chaine b.setCharAt(0, 'C') assertEquals(s, b.toString()) //ajouter des données à un StringBuilder b.append(' ') b.append("le moment.") b.append(23) //insère des chaines de caractères ou autre dans le StringBuilder b.insert(6, "pas ") assertEquals("C'est pas le moment.23", b.toString()) //remplace un sous ensemble de caractères //avec une chaine de caractères donnée b.replace(2, 9, "est") assertEquals("C'est le moment.23", b.toString()) //supprime les caractères b.delete(15, 18) assertEquals("C'est le moment", b.toString()) b.deleteCharAt(2) assertEquals("C'st le moment", b.toString()) //insert à la postion 2 et décale reste à droite(sans perte de données) b.insert(2, 'e') //tronque la taille de la donnée b.setLength(5) assertEquals("C'est", b.toString()) //inverse les caractères de la chaine b.reverse() assertEquals("tse'C", b.toString()) //écrase le StringBuilder, pret à etre réutilisé b.setLength(0) assertEquals("", b.toString()) //java.util.StringTokenizer pour fragmenter une chaine //de caractères en un ensemble de mots var st = StringTokenizer(t) //nb d'items encore présentent dans la file assertEquals(3, st.countTokens()) //est ce que il y a encore des items dans la file assertTrue(st.hasMoreTokens()) //récupérer le token courrant assertEquals("C'est", st.nextToken()) assertEquals("le", st.nextToken()) assertEquals("moment.", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //extraire des occurences de mots délimités //par des caractères autres que des expaces. val str = "a:b:c:d" st = StringTokenizer(str, ":") assertEquals(4, st.countTokens()) assertTrue(st.hasMoreTokens()) assertEquals("a", st.nextToken()) assertEquals("b", st.nextToken()) assertEquals("c", st.nextToken()) assertEquals("d", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //text="C'est le moment." val text = t.toCharArray() var p = 0 //sauter les espaces de tete //pour ramener p à la position du premier caractère imprimable while ((p < text.size) && (Character.isWhitespace(text[p])) ) p++ assertEquals(0, p) assertEquals("C'est le moment.", text.concatToString()) //met le premier mot du texte en majuscule while (p < text.size && Character.isLetter(text[p])) { text[p] = Character.toUpperCase(text[p]) p++ } assertEquals(1, p) assertEquals('C', text[0]) assertTrue(Character.isUpperCase(text[0])) assertFalse(Character.isLetter(text[1])) //comparer des chaines de caractères // avec les contrainte la locale système val col = Collator.getInstance() //le résulat est négatif car chica //est avant chico dans l'ordre alphabétique assertTrue(col.compare("chica", "chico") < 0) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="math">números y matemáticas</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.math.BigInteger import java.security.SecureRandom import java.text.NumberFormat import java.util.* import kotlin.test.* class NumbersMathTest { @Test fun `Nombres et Math`() { //Constantes utiles Byte.MIN_VALUE Byte.MAX_VALUE Short.MIN_VALUE Short.MAX_VALUE Float.MIN_VALUE Float.MAX_VALUE Math.PI Math.E val s = "-42" //conversion de chaine de caractères //vers un nombre, si possible. var b: Byte = java.lang.Byte.parseByte(s) var sh: Short = java.lang.Short.parseShort(s) var i: Int = java.lang.Integer.parseInt(s) var l: Long = java.lang.Long.parseLong(s) var f: Float = java.lang.Float.parseFloat(s) var d: Double = java.lang.Double.parseDouble(s) //valeur exacte val f_exac = java.lang.Float.valueOf(s) val d_exac = java.lang.Double.valueOf(s) //les routines de conversions entière gérent //les nombres dans diverses bases. //1011 en binare est égal a 11 en base dix b = java.lang.Byte.parseByte("1011", 2) assertEquals(11, b) //ff en base 16(hexa) est égal à 255 en base dix. sh = java.lang.Short.parseShort("ff", 16) assertEquals(255, sh) //la méthode valueOf() peut gérer des bases arbitraires. i = java.lang.Integer.valueOf("egg", 17).toInt() assertEquals(4334, i) //la méthode decode() gére les representations octale, //décimal, hexadécimal, en fonction du préfixe numérique //de la chaine de caractères //un 0 de tete signifie base 8 //un 0x de tete signifie base 16 //les autres sont en base 10 val sho = java.lang.Short.decode("0377") //la classe Integer peut convertir les nombres //en diverses chaines de caractères. val decimal = java.lang.Integer.toString(42) assertEquals("42", decimal) val decimal_ = 42.toString() assertEquals("42", decimal_) val binary = java.lang.Integer.toBinaryString(42) assertEquals("101010", binary) val octal = java.lang.Integer.toOctalString(42) assertEquals("52", octal) val hex = java.lang.Integer.toHexString(42) assertEquals("2a", hex) val base36 = java.lang.Integer.toString(42, 36) assertEquals("16", base36) val base36_ = 42.toString(36) assertEquals("16", base36_) //java.text.NumberFormat effectue la conversion // d'une maniere spécifique aux parametres locaux //sans parametre prend la local systeme comme reference val nf = NumberFormat.getNumberInstance(Locale.FRANCE) val formatted_number = nf.format(9876543.21) assertNotEquals("9876543.21", formatted_number) //parse la chaine de caractères en fonction des parametres locaux(fr) val n = nf.parse("1234567,89") assertEquals(1234567.89, n) //les valeurs monétaires sont parfois formaté // d'une maniere differente des nombres val money_format = NumberFormat.getCurrencyInstance(Locale.FRANCE) assertEquals("123,40 €", money_format.format(1234.56)) //java.lang.Math d = Math.toRadians(27.0) d = Math.cos(d) d = Math.sqrt(d) d = Math.log(d) d = Math.exp(d) d = Math.pow(10.0, d) d = Math.atan(d) d = Math.toDegrees(d) //arrondi au dessus val up = Math.ceil(d) //arrondi au dessous val down = Math.floor(d) //arrondi au plus près val nearest = Math.round(d) //java.lang.Math.Random() val r = Math.random() assertTrue(r >= 0.0 && r < 1.0) //créé un nouvel objet Random, en l'initialisant //avec l'heure courante val generator = java.util.Random(System.currentTimeMillis()) //prochaine valeur aléatoire de taille double d = generator.nextDouble() assertTrue((d >= 0.0) && (d < 1.0)) //prochaine valeur aléatoire de taille float f = generator.nextFloat() assertTrue((f >= 0.0) && (f < 1.0)) //prochaine valeur aléatoire de taille long l = generator.nextLong() assertTrue( (Math.abs(l) <= Long.MAX_VALUE) && (Math.abs(l) >= 0) ) //prochaine valeur aléatoire de taille int i = generator.nextInt() assertTrue( (Math.abs(i) <= java.lang.Integer.MAX_VALUE) && (Math.abs(i) >= 0) ) val limit = 100 //prochaine valeur aléatoire de taille int //la limit max du ramdom est ramené à limit //et la limit min est 0 i = generator.nextInt(limit) assertTrue(i in 0 until limit) //prochaine valeur aléatoire de taille booléen val bool = generator.nextBoolean() assertNotNull(bool) //valeur moyenne 0.0, déviation standard 1.0 d = generator.nextGaussian() //randoms bytes //rempli un tableau avec des valeurs byte aléatoires val b_arr = ByteArray(128) generator.nextBytes(b_arr) b_arr.iterator().forEachRemaining { assertTrue( it <= Byte.MAX_VALUE && it >= Byte.MIN_VALUE ) } //java.security.SecureRandom pour les nombres aléatoires //utilisé en cryptographie val secure_generator = SecureRandom() //le générateur génère sa propre tete de liste sur 16 octets secure_generator.setSeed(secure_generator.generateSeed(16)) val sec_b_arr = ByteArray(128) secure_generator.nextBytes(sec_b_arr) sec_b_arr.iterator().forEachRemaining { assertTrue( it <= java.lang.Byte.MAX_VALUE && it >= java.lang.Byte.MIN_VALUE ) } //java.math.BigDecimal java.math.BigInteger //pour travailler sur des grandes valeurs. //calcule de la factorielle de 1000 var total = BigInteger.valueOf(1) (2..1000).forEach { total = total.multiply(BigInteger.valueOf(it.toLong())) } assertTrue(total.toString().length == 2568) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">fechas y horas</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.text.SimpleDateFormat import java.time.Instant import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertTrue class DatesHoursTest { @Test fun `Dates et heures`() { //l'heure courante en millisecondes val t0 = System.currentTimeMillis() //une autre représentation de la meme information val now = java.util.Date() //converti un objet java.util.Date en une valeur long. val t1 = now.getTime() assertTrue(t1 > Instant.EPOCH.toEpochMilli()) //kotlin property access syntaxe style val t1_prime = now.time //java.text.DateFormat //affiche la date d'aujourd'hui en utilisant le format //par défaut des parametres locaux val defaultDateFormat = DateFormat.getDateInstance() //personnalisation du formatage et de la locale val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE) val localeFormattedDate = df.format(Date()) //constantes pour les styles de pattern de formatage assertEquals(0, DateFormat.FULL) assertEquals(1, DateFormat.LONG) assertEquals(2, DateFormat.MEDIUM) assertEquals(3, DateFormat.SHORT) assertEquals(2, DateFormat.DEFAULT) //utilise pour l'heure un format abrégé avec //des parametres personnalisés val tf = DateFormat.getTimeInstance( DateFormat.SHORT, Locale.FRANCE ) //affiche l'heure en utilisant le format de tf val shortTime = tf.format(Date()) assertTrue(shortTime.contains(':')) //affiche la date et l'heure en utilisant //un format détaillé val longTimeStamp = DateFormat.getDateTimeInstance( DateFormat.FULL, DateFormat.FULL, ) assert(longTimeStamp.format(Date()).isNotEmpty()) //utilisez java.text.SimpleDateFormat //pour définir votre propre modele de formatage val customFormat = SimpleDateFormat("yyyy.MM.dd") assertEquals(10, customFormat.format(Date()).length) //DateFormat peut également parser les date contenu dans des chaines val kotlinAnnounceDate = customFormat.parse("2019.05.08") //la class Date et sa représentation en millisecondes //n'autorise qu'une forme trés simple d'arithmétique //on ajoute 3 600 000 millisecondes à l'heure courante val anHourFromNow = now.getTime() + (60 * 60 * 1000) assert(anHourFromNow > now.getTime()) //java.util.Calendar //pour manipuler les dates et heures de facon plus sophistiquée //instanciation selon les parametres locaux //et le fuseau horaire local val calendar = Calendar.getInstance() //initialisation du calendrier à la date de maintenant calendar.setTime(now) //détermine le jour de l'année auquel correspond la date courante val dayOfYear = calendar.get(Calendar.DAY_OF_YEAR) assert(dayOfYear < 366) //réinitialisation de la date courante calendar.set(2019, Calendar.MAY, 8) assertEquals(4, calendar.get(Calendar.DAY_OF_WEEK)) //à quel jour du mois correspond le deuxieme mercredi de mai 2019 //set(key,value) calendar.set(Calendar.YEAR, 2019) calendar.set(Calendar.MONTH, Calendar.MAY) calendar.set(Calendar.DAY_OF_WEEK, Calendar.WEDNESDAY) //defini à quel (n=2) semaine du mois est la date calendar.set(Calendar.DAY_OF_WEEK_IN_MONTH, 2) //extrait le jour du mois val dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH) assertEquals(8, dayOfMonth) calendar.setTime(kotlinAnnounceDate) //ajoute 30j à la date calendar.add(Calendar.DATE, 30) val monthAfter = calendar.getTime() //date est elle avant ou apres? assertTrue(monthAfter.after(kotlinAnnounceDate)) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">fechas y horas java8</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 introduce el nuevo paquete <strong><em>java.time</em></strong>, que contiene las clases de base que<br> la mayoría de los desarrolladores trabajan con. También contiene cuatro subpaquetes:<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> Cronologías alternativas que los desarrolladores que utilizan sistemas de calendario que no<br> cumplir con la norma ISO va a interactuar con. Un ejemplo sería un cal japonés<br> sistema perdurable<br> <strong><em>java.time.format</em></strong><br> Contiene el DateTimeFormatter utilizado para convertir los objetos de fecha y hora<br> en una cadena y también para analizar las cadenas en los objetos de datos y de tiempo.<br> <strong><em>java.time.temporal</em></strong><br> Contiene las interfaces requeridas por las clases de fecha y hora de base y también<br> abstracciones (tales como consultas y ajustadores) para operaciones avanzadas con fechas.<br> <strong><em>java.time.zone</em></strong><br> Clases utilizadas para las reglas de zona horaria subyacentes;<br> la mayoría de los desarrolladores no necesitarán este paquete.<br></p> </div> <div class="imageblock"> <div class="content"> <img src="../../img/java8-date-time.png" alt="java8 date time"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.time.LocalDate import java.time.Month import java.time.Period import java.time.YearMonth import java.time.temporal.* import java.util.HashMap import java.util.stream.Collectors import kotlin.test.Test class DatesHoursJava8Test { class BirthdayDiary { private val birthdays: MutableMap<String, LocalDate> init { birthdays = HashMap() } fun addBirthday( name: String, day: Int, month: Int, year: Int ): LocalDate { val birthday: LocalDate = LocalDate.of(year, month, day) birthdays[name] = birthday return birthday } fun getBirthdayFor(name: String): LocalDate? { return birthdays[name] } fun getAgeInYear(name: String, year: Int): Int { val period: Period = Period.between( birthdays[name], birthdays[name]!!.withYear(year) ) return period.getYears() } fun getFriendsOfAgeIn(age: Int, year: Int): Set<String> { return birthdays.keys.stream() .filter { p: String -> getAgeInYear(p, year) == age } .collect(Collectors.toSet()) } fun getDaysUntilBirthday(name: String): Int { val period: Period = Period.between( LocalDate.now(), birthdays[name] ) return period.getDays() } fun getBirthdaysIn(month: Month): Set<String> { return birthdays.entries.stream() .filter { (_, value): Map.Entry<String, LocalDate> -> value.getMonth() === month } .map<String> { (key): Map.Entry<String, LocalDate> -> key } .collect(Collectors.toSet()) } val birthdaysInCurrentMonth: Set<String> get() = getBirthdaysIn(LocalDate.now().getMonth()) val totalAgeInYears: Int get() = birthdays.keys.stream() .mapToInt { p: String -> getAgeInYear( p, LocalDate.now().getYear() ) } .sum() } //Les ajusteurs modifient les objets de date et d'heure. Supposons, par exemple, que nous voulions //renvoie le premier jour d'un trimestre qui contient un horodatage particulier : class FirstDayOfQuarter : TemporalAdjuster { override fun adjustInto(temporal: Temporal): Temporal? { val currentQuarter: Int = YearMonth.from(temporal) .get(IsoFields.QUARTER_OF_YEAR) return when (currentQuarter) { 1 -> LocalDate.from(temporal) .with(TemporalAdjusters.firstDayOfYear()) 2 -> LocalDate.from(temporal) .withMonth(Month.APRIL.value) .with(TemporalAdjusters.firstDayOfMonth()) 3 -> LocalDate.from(temporal) .withMonth(Month.JULY.value) .with(TemporalAdjusters.firstDayOfMonth()) 4 -> LocalDate.from(temporal) .withMonth(Month.OCTOBER.value) .with(TemporalAdjusters.firstDayOfMonth()) else -> null } } } enum class Quarter { FIRST, SECOND, THIRD, FOURTH } //Dans quel trimestre de l'année cette date se situe-t-elle ? class QuarterOfYearQuery : TemporalQuery<Quarter> { override fun queryFrom(temporal: TemporalAccessor): Quarter { val now = LocalDate.from(temporal) return if (now.isBefore(now.with(Month.APRIL).withDayOfMonth(1))) Quarter.FIRST else if (now.isBefore( now.with(Month.JULY) .withDayOfMonth(1) ) ) Quarter.SECOND else if (now.isBefore( now.with(Month.NOVEMBER) .withDayOfMonth(1) ) ) Quarter.THIRD else Quarter.FOURTH } } @Test fun `Dates et heures après java 8`() { val today = LocalDate.now() val currentMonth = today.month val firstMonthOfQuarter = currentMonth.firstMonthOfQuarter() val q = QuarterOfYearQuery() // Direct var quarter: Quarter? = q.queryFrom(LocalDate.now()) println(quarter) // Indirect quarter = LocalDate.now().query(q) println(quarter) val now = LocalDate.now() val fdoq: Temporal = now.with(FirstDayOfQuarter()) println(fdoq) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">arreglos y colecciones</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/collections_classes_inheritance.png" alt="Classes de collections et héritage"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package playground.programming import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertTrue class ArrayCollectionTest { @Test fun `Tableaux, collections`() { //Tableau //java.util.Arrays définit d'utiles méthodes de manipulation de tableaux, //y compris de tri et de recherche au sein d'un tableau val intArray = arrayOf(10, 5, 7, -3) //tri le tableau Arrays.sort(intArray) var pos = Arrays.binarySearch(intArray, 7) //la valeur 7 est trouvé a l'index 2 assertEquals(2, pos) //12 pas trouvé retourne une valeur negative assert(Arrays.binarySearch(intArray, 12) < 0) //les tableaux peuvent également etre triés //et faire l'objet d'une recherche val stringArray = arrayOf("le", "moment", "c'est") assertEquals("c'est", stringArray[2]) assertEquals("le", stringArray[0]) assertEquals("moment", stringArray[1]) Arrays.sort(stringArray) assertEquals("c'est", stringArray[0]) assertEquals("le", stringArray[1]) assertEquals("moment", stringArray[2]) //Arrays.equals() compare tous les éléments de deux tableaux //Arrays.clone() copie tous les elements du tableau dans un autre stringArray.forEachIndexed { i, it -> assertEquals(it, stringArray.clone()[i]) } val data = ByteArray(100) //Arrays.fill() initialise tous les éléments des deux tableaux //initalise tous les éléments à -1 Arrays.fill(data, -1) data.forEach { assertEquals(-1, it) } //attribue aux éléments 5, 6, 7, 8 et 9 la valeur -2 Arrays.fill(data, 5, 10, -2) ((5 until (10 - 1))).forEach { assertEquals(-2, data[it]) } //récupère le type de data val type = data::class.java //est ce que data est un tableau? assertTrue(type.isArray()) //est ce que data est un tableau de byte assertEquals(Byte::class.java, type.getComponentType()) //Collection val s = java.util.HashSet<String>() s.add("test") assertTrue(s.contains("test")) assertFalse(s.contains("test2")) s.remove("test") assertFalse(s.contains("test")) val ss = TreeSet<String>() ss.add("b") ss.add("a") ss.iterator().forEach { assertTrue(it == "a" || it == "b") } //liste doublement chainée var dll: List<String> = LinkedList<String>() //plus efficace val l = java.util.ArrayList<String>() l.addAll(ss) l.addAll(1, ss) val obj = l.get(1) val obj_prime = l[1] assertEquals(obj, obj_prime) l.set(3, "nouvel élément") l.add("test") l.add(0, "test2") l.removeAt(1) l.remove("a") assertFalse(l.contains("a")) l.removeAll(ss) assertFalse(l.containsAll(ss)) assertFalse(l.isEmpty()) assertTrue(l.isNotEmpty()) val sublist = l.subList(1, 3) val elements = l.toArray() l.clear() val m = HashMap<String, Integer>() m.put("clé", Integer(42)) m["clé"] = Integer(42) val value: Integer = m.get("clé")!! assertEquals(Integer(42), value) m.remove("clé") assertTrue(m.isEmpty()) val keys = m.keys assertTrue(keys.isEmpty()) val set = HashSet<String>() set.add("key_1") set.add("key_2") set.add("key_3") val members = set.toArray() assertEquals(3, members.size) val list = ArrayList<String>() list.add("items1") list.add("items2") list.add("items3") val items = list.toArray() assertEquals(3, items.size) //trie et recherche d'éléments sur les collections list.add("clé") //en premier on trie Collections.sort(list) //en kotlin list.sort() //en deuxieme on cherche //retourne l'index du premier trouvé sinon -1 pos = Collections.binarySearch(list, "clé") assertEquals(0, pos) val list1 = mutableListOf(1, 2, 3, 4, 5) val list2 = mutableListOf<Int>(0, 0, 0, 0, 0) //d'autres méthodes intéressantes concernant Collections //copie list1 dans list2, 2e parametre dans 1er parametre Collections.copy(list2, list1) //comparaison de la copy avec filter assertTrue(list1.filterIndexed { i: Int, it: Int -> it != list2[i] }.isEmpty()) //comparaison de la copy avec map list1.mapIndexed { index: Int, it: Int -> assertEquals(it, list2[index]) } //rempli avec des 0 Collections.fill(list2, 0) assertTrue(list2.none { it != 0 }) //le maximum assertEquals(5, Collections.max(list1)) //le minimum assertEquals(1, Collections.min(list1)) //renverse Collections.reverse(list) listOf("items3", "items2", "items1", "clé").mapIndexed { i: Int, it: String -> assertEquals(it, list[i]) } //mélange la list Collections.shuffle(list) //retourne un ensemble immuable possédant un seul élément 0 Collections.singleton(0) //renvoi un emballage immuable autour d'une liste Collections.unmodifiableList(list) //renvoi un emballage synchronisé autour d'une map, ensemble clé valeur Collections.synchronizedMap(m) //java.util.Properties un est objet key value } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="sysProp">System.Properties</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">System.Properties documento oficial</a></p> </div> <div class="paragraph"> <p>aquí tiene una tabla de algunas propiedades interesantes<br> Estas propiedades son interesantes para tener información<br> en el sistema host de la JVM.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3343%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>clé</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Significado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">separador de archivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carácter que separa los componentes de un camino de archivo. Es '/' en UNIX y '\' en Windows.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ruta utilizada para encontrar directorios y archivos JAR que contienen archivos de clase. Los elementos de la ruta de clase se separan mediante un carácter específico de la plataforma especificado en la propiedad path.separator.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directorio de instalación para Java Runtime Environment (JRE)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.proveedor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nombre del proveedor de JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor.url</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL del proveedor de JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Número de versión de JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">separador de línea</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secuencia utilizada por el sistema operativo para separar líneas en archivos de texto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.arch</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Arquitectura del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Versión del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">path.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carácter separador de ruta utilizado en java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.dir</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directorio de trabajo del usuario</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">usuario.inicio</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directorio de inicio del usuario</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre de cuenta de usuario</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">Hilos</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.util.* import kotlin.test.Test class ThreadsTest { @Test fun `threads test`() { //java.lang.Thread représente le thread fondamentale de l'API java //il existe deux manière de définir un thread //1) étendre la classe Thread ou une lambda en kotlin //2) implémenter l'interface Runnable, // puis passer une instance de cet objet Runnable au constructeur de Thread. val list1: List<Int> = List( size = 45, init = { (1..31).random() } ) println("list1$list1") //facon 1 val t = Thread { Collections.sort(list1) println("list1 sorted$list1") } t.start() val list2 = List( size = 45, init = { (1..31).random() } ) println("list2$list2") //facon 2 val sorter = BackgroundSorter(list2) sorter.start() //priorité des threads //tant qu'un thread de niveau de priorité supérieure n'est pas fini //alors celui de niveau inférieur ne peut s'exécuter //on définit un thread avec une priorité inférieur à la normale t.setPriority(Thread.NORM_PRIORITY - 1) //ici on définit un thread avec une priorité inférieur à la priorité //du thread courant t.setPriority(Thread.currentThread().getPriority() - 1) //Thread.yield() fait une pause pour laisser les autres threads de meme priorité s'exécuter } class BackgroundSorter(private val l: List<Int>) : Thread() { override fun run() { Collections.sort(l) println("list2 sorted$l") } } //pour l'arrêt du thread, plutôt qu'utiliser la fonction Thread.stop() // qui laisse la memoire dans un état non controlé. //utiliser la méthode tel que l'exemple pleaseStop() class DummyClock( private val df: DateFormat = DateFormat.getTimeInstance(DateFormat.MEDIUM), private var keepRunning: Boolean = true ) : Thread() { init { isDaemon = true start() } override fun run() { while (keepRunning) { println(df.format(Date())) try { sleep(1000) } catch (e: InterruptedException) { println(e.message) } } } fun pleaseStop() { keepRunning = false } } //java.util.Timer //java.util.TimerTask //ces classes permettent l'exécution de taches répétitives @Test fun `Timer et TimerTask test`() { DummyClock() } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">tabla de contenidos</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">Expresiones regulares</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.util.* import java.util.regex.Matcher import java.util.regex.Pattern import java.util.stream.Collectors import kotlin.test.Test import kotlin.test.assertEquals class RegularExpressionsTest { @Test fun `expressions régulières`() { val p: Pattern = Pattern.compile("honou?r") val caesarUK = "For Brutus is an honourable man" val mUK: Matcher = p.matcher(caesarUK) assertEquals(true, mUK.find(), "Should matches UK spelling") val caesarUS = "For Brutus is an honorable man" val mUS: Matcher = p.matcher(caesarUS) assertEquals(true, mUS.find(), "Should matches US spelling") } @Test fun `expressions régulières plus complexes`() { //Notez que nous devons utiliser \\ car nous avons besoin d'un littéral \ //et Java utilise un seul \ comme caractère d'échappement var pStr = "\\d" // Un chiffre numérique var text = "Apollo 13" var p = Pattern.compile(pStr) var m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) pStr = "[a..zA..Z]" //N'importe quelle lettre p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) //N'importe quel nombre de lettres, qui doivent toutes être comprises entre 'a' et 'j' //mais peut-être en majuscule ou en minuscule. pStr = "([a..jA..J]*)" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) text = "abacab" //'a' suivi de quatre caractères quelconques, suivi de 'b' pStr = "a....b" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) } @Test fun `Quelles chaînes correspondent à la regex ?`() { val pStr = "\\d" // Un chiffre numérique val p = Pattern.compile(pStr) val ls: List<String> = Arrays.asList("Cat", "Dog", "Ice-9", "99 Luftballoons") val containDigits: List<String> = ls.stream() .filter(p.asPredicate()) .collect(Collectors.toList()) assert(containDigits.contains("Ice-9")) assert(containDigits.contains("99 Luftballoons")) assertEquals(2, containDigits.size) } }</code></pre> </div> </div> <div class="sect2"> <h3 id="_tabla_de_metacaracteres_regex">Tabla de metacaracteres regex</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7592%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">metacarácter</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">funcionalidad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Notas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carácter opcional—cero o una instancia</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cero o más del carácter anterior</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Uno o varios de los caracteres anteriores</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">{M,N}</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Entre M y N instancias del carácter anterior</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\d</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un número</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\D</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carácter no numérico</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\w</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carácter de palabra</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Números, letras y _</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\W</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carácter sin palabra</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carácter de espaciado</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\S</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carácter no blanco</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carácter de salto de línea</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\t</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">carácter de tabulación</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cualquier carácter</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No incluye el salto de línea en Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cualquier carácter contenido entre corchetes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Llamado una clase de caracteres</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[^ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cualquier carácter no contenido entre corchetes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Llamado una clase de caracteres invertida</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Construir un grupo de elementos de patrón</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Llamado un grupo (o grupo de captura)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Definir posibilidades alternativas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implementa el O lógico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Inicio de cadena $ Fin de cadena</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>completarhttps://www.codeurjava.com/2015/05/les-expressions-regulieres-avec-regex.html[con]</p> </div> </div> </div> </div> https://cheroliv.com//blog/2022/0047_memo_gradle_post.html Mon, 23 May 2022 00:00:00 +0000 blog/2022/0047_memo_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_mostrar_la_ayuda">Mostrar la ayuda</a></li> <li><a href="#_definir_la_propiedad_del_sistema_de_la_jvm_d_system_prop">Definir la propiedad del sistema de la JVM: `-D, --system-prop</a></li> <li><a href="#_definir_la_propiedad_del_proyecto_para_el_script_de_construcción_pmypropmyvalue">Definir la propiedad del proyecto para el script de construcción: `-Pmyprop=myvalue</a></li> <li><a href="#_especifica_el_directorio_de_inicio_de_gradle_el_valor_predeterminado_es_el_directorio_actual">Especifica el directorio de inicio de Gradle. El valor predeterminado es el directorio actual.</a></li> <li><a href="#_sobreescribir_la_property_param_component_mediante_la_línea_de_comando">Sobreescribir la property 'param_component' mediante la línea de comando :</a></li> <li><a href="#_agregar_una_carpeta_a_un_source_set_en_un_proyecto_normal_con_kotlin_dsl">Agregar una carpeta a un source-set en un proyecto normal con Kotlin DSL</a></li> <li><a href="#_añadir_una_carpeta_a_un_conjunto_de_fuentes_en_un_proyecto_android_con_el_dsl_de_groovy">Añadir una carpeta a un conjunto de fuentes en un proyecto Android con el DSL de Groovy</a></li> <li><a href="#_evitar_construir_y_probar_un_submódulo">Evitar construir y probar un submódulo</a></li> <li><a href="#_tar_una_carpeta">Tar una carpeta</a></li> <li><a href="#_mostrar_las_dependencias_de_una_compilación">Mostrar las dependencias de una compilación</a></li> <li><a href="#_ejemplo_de_uso_de_reduce_concatenación_de_una_lista_en_una_cadena">Ejemplo de uso de reduce : concatenación de una lista en una cadena</a></li> <li><a href="#_obtener_la_descripción_de_una_tarea_en_particular">Obtener la descripción de una tarea en particular</a></li> <li><a href="#_para_lanzar_una_tarea_desde_el_workingdir_root_entonces_prefija_la_tarea_con_un">Para lanzar una tarea desde el workingDir root, entonces prefija la tarea con un `:</a></li> <li><a href="#_para_volver_a_ejecutar_las_tareas_que_fallaron_utilice_la_opción_rerun_tasks">Para volver a ejecutar las tareas que fallaron, utilice la opción `--rerun-tasks</a></li> <li><a href="#_lanzar_una_tarea_en_un_proyecto_específico_desde_otro_directorio">Lanzar una tarea en un proyecto específico desde otro directorio</a></li> </ul> </div> <div class="sect1"> <h2 id="_mostrar_la_ayuda">Mostrar la ayuda</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew --help</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definir_la_propiedad_del_sistema_de_la_jvm_d_system_prop">Definir la propiedad del sistema de la JVM: `-D, --system-prop</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Dmyprop=myvalue #ou ./gradlew --system-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definir_la_propiedad_del_proyecto_para_el_script_de_construcción_pmypropmyvalue">Definir la propiedad del proyecto para el script de construcción: `-Pmyprop=myvalue</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pmyprop=myvalue #ou ./gradlew --project-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_especifica_el_directorio_de_inicio_de_gradle_el_valor_predeterminado_es_el_directorio_actual">Especifica el directorio de inicio de Gradle. El valor predeterminado es el directorio actual.</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/src/next_startup #ou ./gradlew --project-dir ~/src/next_startup</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_sobreescribir_la_property_param_component_mediante_la_línea_de_comando">Sobreescribir la property 'param_component' mediante la línea de comando :</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pparam_component=CUSTOM_VALUE</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_agregar_una_carpeta_a_un_source_set_en_un_proyecto_normal_con_kotlin_dsl">Agregar una carpeta a un source-set en un proyecto normal con Kotlin DSL</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sourceSets { getByName("test"){ java.srcDir("src/scripts/groovy") } getByName("test"){ java.srcDir("src/scripts/kscript") } getByName("test"){ java.srcDir("src/test/javascript") } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_añadir_una_carpeta_a_un_conjunto_de_fuentes_en_un_proyecto_android_con_el_dsl_de_groovy">Añadir una carpeta a un conjunto de fuentes en un proyecto Android con el DSL de Groovy</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">android { sourceSets { main.java.srcDirs += "src/main/../../../../ceelo/domain/src/main/java/" test.java.srcDirs += "src/test/../../../../ceelo/domain/src/test/java/" } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_evitar_construir_y_probar_un_submódulo">Evitar construir y probar un submódulo</h2> <div class="sectionbody"> <div class="paragraph"> <p>gradle build -x :excluded-module:check -x :excluded-module:assemble -x :excluded-module:build</p> </div> <div class="listingblock"> <div class="title">Mover archivos</div> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("moveWebappNode") { doLast { ant.withGroovyBuilder { "move"( "webapp/node_modules" to "$rootDir/webapp-src/node_modules", ) } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tar_una_carpeta">Tar una carpeta</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register<Tar>("tarWebapp") { dependsOn("moveWebappNpm") group = WEBAPP description = "tar webapp" doLast { setOf( "build", "target", "node_modules" ).forEach { dir -> exclude { it.name .dir } } archiveFileName.set("webapp.tar") destinationDirectory.set(File("${rootDir.absolutePath}$sep$WEBAPP_SRC")) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_mostrar_las_dependencias_de_una_compilación">Mostrar las dependencias de una compilación</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printDependencies") { description = "print project dependencies" group = WEBAPP doLast { println("${project.name} dependencies") mutableMapOf<String, Map<String, String>>( "buildDependencies" to buildDependencies, "domainDeps" to domainDeps, "domainTestDeps" to domainTestDeps, ).apply { putAll(appModules) } .forEach { module -> if (module.value.isNotEmpty()) { println("${module.key}:") module.value.forEach { println(dependency(it)) } println() } } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ejemplo_de_uso_de_reduce_concatenación_de_una_lista_en_una_cadena">Ejemplo de uso de reduce : concatenación de una lista en una cadena</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printWebappSrc") { description = "print webapp sources" group = WEBAPP doLast { webAppSrc .reduce { acc, s -> "$acc\n\t$s" } .run { println("$WEBAPP_SRC: $this\n") } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_obtener_la_descripción_de_una_tarea_en_particular">Obtener la descripción de una tarea en particular</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -q help --task foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_lanzar_una_tarea_desde_el_workingdir_root_entonces_prefija_la_tarea_con_un">Para lanzar una tarea desde el workingDir root, entonces prefija la tarea con un `:</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew :foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_volver_a_ejecutar_las_tareas_que_fallaron_utilice_la_opción_rerun_tasks">Para volver a ejecutar las tareas que fallaron, utilice la opción `--rerun-tasks</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew check --rerun-tasks</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lanzar_una_tarea_en_un_proyecto_específico_desde_otro_directorio">Lanzar una tarea en un proyecto específico desde otro directorio</h2> <div class="sectionbody"> <div class="paragraph"> <p>La opción`-p` (ou <code>--project-dir</code>) permite especificar la ruta de acceso a un proyecto Gradle y ejecutar una tarea en él, incluso si el directorio actual es diferente.</p> </div> <div class="paragraph"> <p>Por ejemplo, para lanzar la tarea`build`del proyecto situado en`~/projets/mon-autre-projet`mientras se encuentra en otro directorio :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/projets/mon-autre-projet build</code></pre> </div> </div> <div class="paragraph"> <p>Esto es particularmente útil para scriptar acciones en varios proyectos desde una ubicación central.</p> </div> <div class="ulist"> <div class="title">ver también :</div> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_warnings">ref</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_options">ref</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">discusión</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com//blog/2022/0038_training_kotlin_enum_sealed_class_post.html Tue, 17 May 2022 00:00:00 +0000 blog/2022/0038_training_kotlin_enum_sealed_class_post.html <div class="paragraph"> <p>las sealed classes, no son enumeraciones(palabra clave:enum).<br> Viniendo de Java, usted podría estar tentado de sobrecargar su enumeración de aportes de funcionalidades: // Java code</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-java" data-lang="java">enum PizzaOrderStatus { ORDER_RECEIVED, PIZZA_BEING_MADE, OUT_FOR_DELIVERY, COMPLETED; public PizzaOrderStatus nextStatus() { switch (this) { case ORDER_RECEIVED: return PIZZA_BEING_MADE; case PIZZA_BEING_MADE: return OUT_FOR_DELIVERY; case OUT_FOR_DELIVERY: return COMPLETED; case COMPLETED:return COMPLETED; } } }</code></pre> </div> </div> <div class="paragraph"> <p>En lugar de eso, puedes usar la clase sellada:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sealed class PizzaOrderStatus(protected val orderId: Int) { abstract fun nextStatus() : PizzaOrderStatus class OrderReceived(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return PizzaBeingMade(orderId) } } class PizzaBeingMade(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return OutForDelivery(orderId) } } class OutForDelivery(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return Completed(orderId) } } class Completed(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return this } } }</code></pre> </div> </div> <div class="paragraph"> <p>La ventaja de este enfoque es que ahora podemos transmitir datos con el estado:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">var status: PizzaOrderStatus = OrderReceived(123) while (status !is Completed) { status = when (status) { is OrderReceived -> status.nextStatus() is PizzaBeingMade -> status.nextStatus() is OutForDelivery -> status.nextStatus() is Completed -> status } }</code></pre> </div> </div> <div class="paragraph"> <p>En general, las sealed classes son buenas si quieres tener datos asociados a un Estado</p> </div> https://cheroliv.com//blog/2022/0036_training_kotlin_post.html Thu, 12 May 2022 00:00:00 +0000 blog/2022/0036_training_kotlin_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Programación en kotlin, plan.</p> </div> </div> </div> <div class="sect1"> <h2 id="_mapa_mental">Mapa mental</h2> <div class="sectionbody"> <div class="paragraph"> <p><span class="image"><img src="../../diagram/training_kotlin.png" alt="training_kotlin"></span></p> </div> </div> </div> <div class="sect1"> <h2 id="_programación_funcional">Programación funcional</h2> <div class="sectionbody"> <div class="paragraph"> <p>Los ejercicios son tomados del libro:<br> Funcional programación en Kotlin por tutoriales<br> Escrito por Massimo Carli<br> repositorio: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_sintaxis">sintaxis</h3> <div class="sect3"> <h4 id="_firstprogramtest">FirstProgramTest</h4> <div class="paragraph"> <p>nociones: pantalla de visualización, función<br> FirstProgramTest:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/FirstProgramTest.kt[fuente]+</p> </div> </div> <div class="sect3"> <h4 id="_concatfunctiontest">ConcatFunctionTest</h4> <div class="paragraph"> <p>conceptos: memoria, variable, valor, objeto, extensión de función<br> ExampleUnitTest: <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt">fuente</a>+</p> </div> </div> <div class="sect3"> <h4 id="_birthdaymessagetestoutput">BirthdayMessageTestOutput</h4> <div class="paragraph"> <p>noções: conjuntos, bucles<br> <a href="https://developer.android.com/codelabs/basic-android-kotlin-training-first-kotlin-program?continue=https%3A%2F%2Fdeveloper.android.com%2Fcourses%2Fpathways%2Fandroid-basics-kotlin-one%23codelab-https%3A%2F%2Fdeveloper.android.com%2Fcodelabs%2Fbasic-android-kotlin-training-first-kotlin-program">Introducción a Kotlin</a><br> BirthdayMessageTestOutput:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[source]+</p> </div> </div> </div> <div class="sect2"> <h3 id="_curso_de_kotlin">Curso de kotlin</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/YRjY3jRrQYY?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_tutorial_sobre_las_colecciones_en_java">Tutorial sobre las colecciones en java</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">Colecciones</a></p> </div> <div class="paragraph"> <p>El corazón de las interfaces de colección<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="Colecciones"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_básicos_funcionales">Básicos funcionales</h3> <div class="sect3"> <h4 id="_declarativo_x_imperativo_enfoque">declarativo X imperativo enfoque</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals class DeclarativeTests { val input = listOf( "123", "abc", "1ds", "987", "abdf", "1d3", "de1", "88", "101" ) fun imperativeSum(list: List<String>): Int { var sum = 0 for (item in list) { try { sum += item.toInt() } catch (_: NumberFormatException) { } } return sum } @Test fun `test imperative approach`() { imperativeSum(input).run { println("Sum $this") assertEquals(1299, this) } } fun isValidNumber(s: String) = try { s.toInt() true } catch (_: NumberFormatException) { false } fun declarativeSum(list: List<String>) = list .filter(::isValidNumber) .map(String::toInt) .sum() @Test fun `test declarative approach`() { assertEquals(1299, declarativeSum(input).apply { println("Sum $this") }) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_ejercicio_1_1">Ejercicio 1.1</h4> <div class="paragraph"> <p>Implementar la función sumInRange, que suma los valores en<br> una List<String> dentro de un intervalo dado. La firma es:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun sumInRange(input: List<String>, range: IntRange): Int</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_1`() { assertEquals(4, sumInRange( listOf("1", "10", "a", "7", "ad2", "3"), 1..5 ).apply { println("sumInRange 1..5: $this") } ) }</code></pre> </div> </div> <div class="paragraph"> <p>Pruebalo y verifica tu respuesta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/DeclarativeTests.kt[solución, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_funciones_de_orden_superior">Funciones de orden superior</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.* import java.lang.Thread.sleep import kotlin.math.sign import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOFTests { val ONE_SECOND = 1000L @Test fun `high order function`() { //capture de la sortie standard val standardOut: PrintStream? = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) //libération de la sortie standard setOut(standardOut) } fun Int.times1(fn: () -> Unit) { for (i in 1..this) { fn() } } fun Int.times2(fn: () -> Unit) { for (i in 1..this) fn() } fun Int.times3(fn: () -> Unit) = (1..this).forEach { fn() } fun Int.times4(fn: () -> Unit) = repeat((1..this).count()) { fn() } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_ejercicio_1_2">Ejercicio 1.2</h4> <div class="paragraph"> <p>Implementar chrono, que acepta una función de tipo`() →`<br> Unidad de entrada y devuelve el tiempo transcurrido al ejecutarla. La firma es :<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>Pruebe y verifique su respuesta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solución, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_composición">Composición</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals fun double(x: Int): Int = 2 * x fun square(x: Int): Int = x * x fun squareAndDouble1(x: Int) = double(square(x)) infix fun <A, B, C> ((A) -> B).compose(g: (B) -> C) : (A) -> C = { a -> g(this(a)) } class CompositionTests { @Test fun composition_impure() { assertEquals(200, double(square(10))) assertEquals(200, squareAndDouble1(10)) } @Test fun composition_pure() { val squareAndDouble = ::square compose ::double assertEquals(200, squareAndDouble(10)) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_funciones_puras_y_testabilidad">Funciones puras y testabilidad</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.Test import kotlin.test.assertEquals var count = 0 //impure car une variable global subit un effet de bord fun impure(value: Int): Int { count++ return value + count } //impure car utilisation de la sortie standard qui fait muter le system fun addOneAndLog(x: Int): Int { val result = x + 1 println("New Value is $result") return result } //pure fun addOne(x: Int) = (x + 1).run { Pair(this, "New Value is $this") } class PureTests { @Test fun `impure fonction`() { assertEquals(3, impure(2)) val standardOut = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) addOneAndLog(3) assertEquals( "New Value is 4", outputStreamCaptor .toString() .trim() ) setOut(standardOut) } @Test fun `pure fonction`() { addOne(3).run { assertEquals(4, first) assertEquals("New Value is 4", second) } } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_manejo_de_excepciones">Manejo de excepciones</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import org.junit.jupiter.api.assertThrows import kotlin.Result.Companion.failure import kotlin.Result.Companion.success import kotlin.test.Test import kotlin.test.assertEquals //NumberFormatException est un effet de bord qui rend la fonction impure fun strToInt(str: String) = str.toInt() //pure fun strToIntOrNull(str: String) = try { str.toInt() } catch (nfe: NumberFormatException) { null } //pure avec gestion de l'exception plus élégante fun strToIntResult(str: String): Result<Int> = try { success(str.toInt()) } catch (nfe: NumberFormatException) { failure(nfe) } class ExceptionHandlingTests { @Test fun impure() { assertThrows<NumberFormatException> { strToInt("foo") } assertEquals(1, strToInt("1")) } @Test fun pure() { assertEquals(null, strToIntOrNull("foo")) assertEquals(1, strToIntOrNull("1")) } @Test fun `pure avec result`() { assertEquals(1, strToIntResult("1").getOrNull()) assertEquals( "For input string: \"foo\"", strToIntResult("foo") .exceptionOrNull() ?.message ) } }</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_puntos_clave">Puntos clave</h3> <div class="ulist"> <ul> <li> <p>Mientras que la programación orientada a objetos significa programar con objetos,</p> </li> </ul> </div> <div class="paragraph"> <p>la programación funcional significa programar con funciones. Usted descompone un problema en varios subproblemas, que modela con las funciones.</p> </div> <div class="ulist"> <ul> <li> <p>Las funciones de orden superior aceptan otras funciones como entrada o devuelven otras</p> </li> </ul> </div> <div class="paragraph"> <p>funcionan como valores de retorno. La teoría de las categorías es la teoría de la composición, y la utiliza para comprender cómo componer tus funciones en un programa de trabajo. El valor de salida de una función pura depende únicamente de sus parámetros de entrada, y ella no tiene efectos secundarios.</p> </div> <div class="ulist"> <ul> <li> <p>Un efecto secundario es algo que una función hace al mundo exterior. Este</p> </li> </ul> </div> <div class="paragraph"> <p>puede ser un registro en la salida estándar o la modificación del valor de una variable global. La programación funcional funciona para las funciones puras, pero también proporciona los herramientas para transformar funciones impuras en funciones puras. Puedes hacer que una función impura sea pura desplazando los efectos para hacerlos parte del valor de retorno</p> </div> <div class="ulist"> <ul> <li> <p>La programación funcional es una cuestión de composición.</p> </li> </ul> </div> <div class="paragraph"> <p>La gestión de errores es un caso típico de efectos secundarios, y Kotlin te brinda las herramientas para gestionarlos de forma funcional</p> </div> </div> <div class="sect2"> <h3 id="_profundizar_java8_expresiones_lambda_y_interfaces_funcionales">Profundizar java8: expresiones lambda y interfaces funcionales</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/20waNRw6wMA?rel=0&list=PLzzeuFUy_Cng0wZhqbnkvWAW0d2fdVfyQ" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_teoría_de_las_categorías">Teoría de las categorías</h3> <div class="paragraph"> <p>La teoría matemática de las categorías:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/LVHoROSF3KA?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_fundamentos_de_las_funciones">Fundamentos de las funciones</h3> <div class="sect3"> <h4 id="_ejercicio_2_1">Ejercicio 2.1</h4> <div class="paragraph"> <p>¿Puedes escribir un ejemplo de función que mapee valores distintos?<br> cuyo dominio toma valores no distintos en el intervalo, como f(b) y f(c) en la figura de abajo?<br></p> </div> <div class="paragraph"> <p>Pruébalo, luego verifica el proyecto del desafío para una solución y ver cómo lo hiciste.<br> Encontrará consejos y una explicación siguiendo el enlace hacia la <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">solución</a>.<br></p> </div> </div> <div class="sect3"> <h4 id="_ejercicio_2_2">Ejercicio 2.2</h4> <div class="paragraph"> <p>¿Puedes escribir la función inversa de dos veces?<br> ¿Cuáles son el dominio y el rango de la función inversa?<br> Consulta el proyecto del desafío y el Apéndice B para la solución.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>Prueba-lo y verifica tu respuesta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solución, windows="_blank].</p> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2022/0031_memo_design_system_post.html Sun, 9 Jan 2022 00:00:00 +0000 blog/2022/0031_memo_design_system_post.html <div class="sect1"> <h2 id="_herramientas">herramientas</h2> <div class="sectionbody"> <div class="paragraph"> <p></think> herramientas</p> </div> <div class="dlist"> <div class="title"><strong>Ilustraciones</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>Ilustraciones de código abierto para todas las ideas que puedas imaginar y crear.</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">absurd.design</a></dt> <dd> <p>Ilustraciones absurdas que tienen sentido.</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>Magníficas ilustraciones gratuitas. Actualizaciones semanales.</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>Iconos, ilustraciones, fotos, música y herramientas de diseño.</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">blush.design</a></dt> <dd> <p>Iconos, ilustraciones, fotos, música y herramientas de diseño</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>Mezcle y combine ilustraciones de personas con una biblioteca de diseño.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Colores</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>¡El generador de esquemas de colores ultra-rápido!</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Tendencias</strong></div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">pinterest</a></dt> <dd> <p>Descubrimiento visual de ideas: imágenes, videos, colecciones temáticas.</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">Regate</a></dt> <dd> <p>Plataforma para diseñadores compartiendo sus creaciones e interactuando.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI y Sistemas de Diseño</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">Google Material Design</a></dt> <dd> <p>Sistema de diseño de Google para interfaces de usuario unificadas y adaptables.</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Directrices de Interfaz Humana de Apple</a></dt> <dd> <p>Recomendaciones de Apple para diseñar aplicaciones iOS y macOS intuitivas.</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>Plataforma de diseño y colaboración para crear prototipos y sistemas de diseño.</p> </dd> <dt class="hdlist1"><a href="https://www.frontify.com/">Frontify</a></dt> <dd> <p>Plataforma de gestión de marca y de sistemas de diseño para asegurar la coherencia.</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">Repositorio de sistemas de diseño</a></dt> <dd> <p>Colección de recursos y ejemplos de sistemas de diseño para inspiración.</p> </dd> </dl> </div> <div class="paragraph"> <p>Desarrollo Frontend</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a></dt> <dd> <p>Hoja de trucos de HTML</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com">fontawesome.com</a></dt> <dd> <p>biblioteca de iconos</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/">toptal.com/designers/htmlarrows/symbols</a></dt> <dd> <p>Iconos nativos en HTML</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>Esencial para CSS, con artículos, tutoriales y consejos frontend modernos.</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">Frontend Mentor</a></dt> <dd> <p>Desafíos de código frontend basados en proyectos reales para mejorar tus habilidades.</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>Comunidad de desarrolladores para compartir artículos, tutoriales y proyectos.</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">CodePen</a></dt> <dd> <p>Editor de código en línea y comunidad para compartir fragmentos de código y demos.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Desarrollo Frontend asistido por IA</strong></div> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0 convierte las descripciones en lenguaje natural en código y interfaz de usuario.</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">Uizard</a></dt> <dd> <p>Uizard se centra en la transformación de maquetas (imágenes, bocetos) en código HTML, CSS y React.</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI le permite describir la interfaz que desea en lenguaje natural, y la IA genera diseños de Figma editables.</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ es una plataforma de desarrollo front-end low-code que utiliza la IA para ayudarte a construir y desplegar sitios web de forma visual.</p> </dd> </dl> </div> </div> </div> https://cheroliv.com//blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html Tue, 3 Nov 2020 00:00:00 +0000 blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://microk8s.io/docs/">documentación oficial de microk8s</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_instalación_del_paquete_microk8s">Instalación del paquete microk8s:</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com//blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html Mon, 28 Sep 2020 00:00:00 +0000 blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html <div class="sect3"> <h4 id="_gradle_kotlin_dsl">Gradle-Kotlin-DSL:</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin"></code></pre> </div> </div> </div> https://cheroliv.com//blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html Sun, 27 Sep 2020 00:00:00 +0000 blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html <div class="paragraph"> <p>NotImplementedException NotImplementedError, utilidad para las pruebas, permite saber dónde estamos, y la causa del fallo.<br> Aún no implementado, permite lanzar la excepción correcta.<br> Il y a :<br> <a href="http://commons.apache.org/proper/commons-lang/javadocs/api-release/org/apache/commons/lang3/NotImplementedException.html">org.apache.commons.lang3.NotImplementedException</a><br> <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-not-implemented-error/">kotlin.NotImplementedError</a>+</p> </div> https://cheroliv.com//blog/2020/0026_untar_post.html Sat, 26 Sep 2020 00:00:00 +0000 blog/2020/0026_untar_post.html <div class="sect3"> <h4 id="_enlaces_interserver_net">Enlaces: <a href="https://www.interserver.net/tips/kb/extract-tar-gz-files-using-linux-command-line/">interserver.net</a></h4> </div> https://cheroliv.com//blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html Fri, 25 Sep 2020 00:00:00 +0000 blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html https://cheroliv.com//blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html Thu, 24 Sep 2020 00:00:00 +0000 blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html <div class="sect3"> <h4 id="_hackernoon_com"><a href="https://hackernoon.com/dont-install-postgres-docker-pull-postgres-bee20e200198">hackernoon.com</a></h4> </div> https://cheroliv.com//blog/2020/0023_gherkin_en_francais_post.html Wed, 23 Sep 2020 00:00:00 +0000 blog/2020/0023_gherkin_en_francais_post.html https://cheroliv.com//blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html Tue, 22 Sep 2020 00:00:00 +0000 blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ ./gradlew -Pparam_component=CUSTOM ---- ----</code></pre> </div> </div> https://cheroliv.com//blog/2020/0021_memo_git_post.html Mon, 21 Sep 2020 00:00:00 +0000 blog/2020/0021_memo_git_post.html <div class="sect3"> <h4 id="_fuentes">Fuentes:</h4> <div class="paragraph"> <p>*https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[xenovación] *https://intellipaat.com/community/3102/git-show-remote-url-how-can-i-determine-the-url-that-a-local-git-repository-was-originally-cloned-from[intellipaat]</p> </div> </div> <div class="sect3"> <h4 id="_cambiar_de_repositorio_remoto_en_git">cambiar de repositorio remoto en git</h4> <div class="paragraph"> <p>mostrar la URL del repo remoto actual:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com//blog/2020/0021_aspirer_depuis_une_URL_post.html Sun, 20 Sep 2020 00:00:00 +0000 blog/2020/0021_aspirer_depuis_une_URL_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ wget -r -k -np http://site.com/docs/manual/ ---- Para definir un directorio objetivo, agregue el argumento -P y proporcione la ruta. ----</code></pre> </div> </div> https://cheroliv.com//blog/2020/0020_creer_un_disk_bootable_post.html Sat, 19 Sep 2020 00:00:00 +0000 blog/2020/0020_creer_un_disk_bootable_post.html <div class="sect3"> <h4 id="_enlaces_etcher">Enlaces: <a href="https://www.balena.io/etcher/">etcher</a></h4> </div> https://cheroliv.com//blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html Fri, 18 Sep 2020 00:00:00 +0000 blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html <div class="sect3"> <h4 id="_enlaces_askubuntu">Enlaces: <a href="https://askubuntu.com/questions/86849/how-to-unzip-a-zip-file-from-the-terminal">askubuntu</a></h4> <div class="paragraph"> <p>Si desea extraer a una carpeta de destino específica, puede usar : <code>` $ unzip archivo.zip -d carpeta_destino </code>` Si los directorios de origen y de destino son idénticos, puedes simplemente hacer: <code>` $ unzip file.zip </code>`</p> </div> </div> https://cheroliv.com//blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html Thu, 17 Sep 2020 00:00:00 +0000 blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html <div class="sect3"> <h4 id="_enlaces_stackexchange">Enlaces: <a href="https://unix.stackexchange.com/questions/72661/show-sum-of-file-sizes-in-directory-listing">stackexchange</a></h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ du -ach --exclude "./.*" /home/troll/ ---- ----</code></pre> </div> </div> </div> https://cheroliv.com//blog/2020/0017_detruire_une_branch_sur_github_post.html Wed, 16 Sep 2020 00:00:00 +0000 blog/2020/0017_detruire_une_branch_sur_github_post.html <div class="sect3"> <h4 id="_destruir_una_rama_en_github">Destruir una rama en GitHub</h4> </div> <div class="sect3"> <h4 id="_enlace_gist">Enlace: <a href="https://gist.github.com/cheroliv/921a13ed23ae6d4d66af8d43dd536987">gist</a></h4> </div> https://cheroliv.com//blog/2020/0016_asciidoc_markdown_memo_post.html Tue, 15 Sep 2020 00:00:00 +0000 blog/2020/0016_asciidoc_markdown_memo_post.html <div class="paragraph"> <div class="title">¿Por qué asciidoc o markdown? Aquí, me inclino hacia asciidoc, ya que ya tengo algunos tickets escritos en asciidoc.<br></div> <p>Asciidoc es un lenguaje de marcado, que permite producir contenido, aportando un diseño que mantiene el texto legible para un ser humano.<br> Es una forma de estandarizar el procesamiento de textos para contenidos simples sin software adicional.</p> </div> <div class="ulist"> <div class="title">Enlaces :</div> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/" target=""_blank">@jmdoudoux en blog.oxiane.com</a>[asciidoc]</p> </li> <li> <p><a href="https://powerman.name/doc/asciidoc" target=""_blank">powerman.name</a>[asciidoc]</p> </li> </ul> </div> https://cheroliv.com//blog/2019/0013_how-to-install-a-deb-file_post.html Mon, 19 Aug 2019 00:00:00 +0000 blog/2019/0013_how-to-install-a-deb-file_post.html <div class="paragraph"> <p>Para instalar un paquete Debian desde un archivo .deb desde la línea de comandos.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo dpkg -i /chemin/du/fichier/deb/</code></pre> </div> </div> <div class="paragraph"> <p>ver aquí para lahttps://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[referencia]+</p> </div> https://cheroliv.com//blog/2019/0011_gradle_configuration_ide_jbake_content_post.html Fri, 16 Aug 2019 00:00:00 +0000 blog/2019/0011_gradle_configuration_ide_jbake_content_post.html <div class="paragraph"> <p>En un proyecto de aplicación impulsado por el gestor de compilación Gradle<br> es más agradable disponer de la visibilidad sobre todas las carpetas<br> participante en el desarrollo de la aplicación,<br> como carpetas de recursos que no son<br> en los caminos por convención.<br> Por ejemplo quiero que el directorio src/jbake,<br> sea visible como ‘resource folder’<br> es posible hacerlo ingresando en la configuración del proyecto,<br> en los asistentes del IDE. Sin embargo, esta opción no se guarda en la siguiente recarga<br> del proyecto Gradle en el IDE. Para añadir esta configuración de forma permanente<br> La solución es sobrescribir la configuración de las rutas de fuentes<br> en el archivo de configuración build.gradle tal como en las líneas 18, 19, 20 y 21 :<br> build.gradle<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">plugins { id "java" id "groovy" id "org.jbake.site" version "5.0.0" id "org.ajoberstar.git-publish" version "2.1.1" } repositories { mavenCentral() jcenter() } group project_group version project_version sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =[ "src/main/resources", "src/jbake"//in order to get site src content in the IDE ] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } test { useJUnitPlatform() } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" implementation "org.asciidoctor:asciidoctor-java-integration:$asciidoctor_java_integration_version" implementation "org.freemarker:freemarker:$freemarker_version" testImplementation "org.junit.jupiter:junit-jupiter-api:$junit5_version" testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junit5_version" } gitPublish { repoUri = github_pages_blog_repository branch = git_branch contents { from(file(jbake_content_from)) { into jbake_content_to } } } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> https://cheroliv.com//blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html Wed, 14 Aug 2019 00:00:00 +0000 blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html <div class="paragraph"> <p>El tema del ticket es la configuración de un script de compilación Gradle.<br> Quiero poder utilizar un script Groovy sin hacer referencia<br> al proyecto Gradle al que lo adjunté<br> Quiero tener la posibilidad de ejecutar este script Groovy fuera de Gradle.<br> sin que las anotaciones ivy de recuperación de dependencia externa<br> no causan problemas de rendimiento o de compilación<br> del script de build de Gradle.<br> Para ilustrar la configuración me baso en dos scripts:<br> un script de build Gradle y un script Groovy.<br> El script Groovy contiene al inicio en la línea 2,<br> una instrucción para tirar una dependencia externa<br> con el gestor de dependencias ivy.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import org.apache.commons.io.FileUtils static String getSeparator() { System.getProperty("file.separator") } String from = "${System.getProperty("user.home")}${separator}.config${separator}transmission${separator}torrents" String to = "${System.getProperty("user.home")}${separator}Documents${separator}torrents_completed" File fromDlDir = new File("${System.getProperty("user.home")}${separator}Téléchargements") File fromDir = new File(from) File toDir = new File(to) Collection<File> torrentFiles = FileUtils.listFiles( fromDir, ["torrent"] as String[], false) torrentFiles.addAll(FileUtils.listFiles( fromDlDir, ["torrent", "torrent.added"] as String[], false)) torrentFiles.empty ?: torrentFiles.each { it -> FileUtils.copyFileToDirectory(it, toDir) } println torrentFiles.size()</code></pre> </div> </div> <div class="paragraph"> <p>En el archivo build.gradle, ahora veamos cómo armonizar<br> los dos gestores de dependencias, ivy y Gradle. El acuerdo entre los dos se hace en las líneas :<br> 26, 30, 37, 38 et 39<br> Así puedo lanzar mi script Groovy manualmente,<br> y la compilación de Gradle no se ve obstaculizada por el @Grab.<br> Las dependencias del script Groovy no se deben proporcionar en Gradle.<br> Por otro lado, no puedo lanzar el script Groovy desde Gradle.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">plugins { id "java" id "groovy" } repositories { mavenCentral() jcenter() } sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =["src/main/resources"] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> <div class="paragraph"> <p>referencia del ticket enhttps://stackoverflow.com/a/18174033/837404[stackoverflow]</p> </div> https://cheroliv.com//blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html Tue, 13 Aug 2019 00:00:00 +0000 blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html <div class="sect2"> <h3 id="_el_ppmc">El PPMC</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">wiki MCM o Mínimo Común Múltiplo</a></p> </div> <div class="paragraph"> <p>AlgebraUtils.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">package com.cheroliv.misc import groovy.transform.CompileStatic @CompileStatic class AlgebraUtils { /** * Great common divisor * Plus grand commun diviseur(pgcd) * Great Common Divisor * @param a * @param b * @return */ static Integer gcd(Integer a, Integer b) { !b ? a : gcd(b, a % b) } /** * Least common multiple * Plus petit commun multiplicateur(ppmc) * @param a * @param b * @return */ static BigInteger lcm(Integer a, Integer b) { (a * b / gcd(a, b)) as BigInteger } static void main(String... args) { Integer a = 96 Integer b = 28 println "gcd($a, $b) = ${gcd(a, b)}" a = 790 b = 990 println "lcm($a, $b) = ${lcm(a, b)}" } }</code></pre> </div> </div> <div class="paragraph"> <p>resultado:</p> </div> <div class="paragraph"> <p>gcd(96, 28) = 4 mcm(790, 990) = 78210</p> </div> </div> https://cheroliv.com//blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html Mon, 12 Aug 2019 00:00:00 +0000 blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html <div class="paragraph"> <p>Busco archivos por criterios de nombre: la lista de los archivos que tienen la extensión .h y .cpp</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' + +</code></pre> </div> </div> <div class="paragraph"> <p>la lista de los archivos que tienen la extensión .h y .cpp<br> el resultado se guarda en el archivo list_of_txt_files.list</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' -print > list_of_txt_files.list</code></pre> </div> </div> <div class="paragraph"> <p>Estoy buscando la lista de archivos cuya extensión es .chm<br> y yo destruye esta lista.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name "*.chm" -type f -delete</code></pre> </div> </div> https://cheroliv.com//blog/2019/0015_projet_avec_methodologie_en_cascade_post.html Thu, 1 Aug 2019 00:00:00 +0000 blog/2019/0015_projet_avec_methodologie_en_cascade_post.html <div class="sect2"> <h3 id="_analizar_y_recopilar_los_requisitos">Analizar y recopilar los requisitos</h3> </div> <div class="sect2"> <h3 id="_definir_la_gestión_de_proyecto">Definir la gestión de proyecto</h3> <div class="imageblock"> <div class="content"> <img src="../../diagram/definir_projet.png" alt="definir la gestion de projet"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/triangle_qcd.png" alt="triangle_qcd"> </div> </div> </div> <div class="sect2"> <h3 id="_contextualizar_el_proyecto">Contextualizar el proyecto</h3> </div> <div class="sect2"> <h3 id="_analizar_y_recopilar_requisitos">Analizar y recopilar requisitos</h3> <div class="sect3"> <h4 id="_formular_los_objetivos_y_entregables">Formular los objetivos y entregables</h4> </div> </div> <div class="sect2"> <h3 id="_descifrar_una_cuadrícula_de_lectura">Descifrar una cuadrícula de lectura</h3> </div> <div class="sect1"> <h2 id="_define_el_proyecto_con_tu_equipo">Define el proyecto con tu equipo</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/conductor.png" alt="chef d’orchestre"> </div> </div> <div class="sect2"> <h3 id="_consultar_a_los_expertos_para_encontrar_la_solución">Consultar a los expertos para encontrar la solución</h3> </div> <div class="sect2"> <h3 id="_elegir_una_metodología_de_gestión_de_proyectos">Elegir una metodología de gestión de proyectos</h3> <div class="imageblock"> <div class="content"> <img src="../../img/cascading_planning.png" alt="planning en cascade"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/Cycle_V_details.jpeg" alt="cycle en V"> </div> </div> </div> </div> </div> https://cheroliv.com//blog/2019/0014_list_all_databases_in_postgresql_post.html Tue, 30 Jul 2019 00:00:00 +0000 blog/2019/0014_list_all_databases_in_postgresql_post.html <div class="paragraph"> <p>No tengo ganas de instalarhttps://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a> mientras que todo está presente en la línea de comandos<br> Para ello debemos lanzar el terminal y conectarnos como el usuario postgres.<br> el usuario postgres es el único que tiene por defecto el derecho de ejecutar la aplicación psql, que es el cliente de línea de comandos [Nothing – output remains empty]<a href="https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande">CLI</a>) postgresql,<br> para poder hablar con la base de datos en línea de comandos desde el terminal<br> Para conectarse, abrir el terminal y escribir esto:<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres</code></pre> </div> </div> <div class="paragraph"> <p>Para conectarse y llegar directamente al prompt de comandos de PostgreSQL, escriba esto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres psql</code></pre> </div> </div> <div class="paragraph"> <p>Para listar las bases de datos de una instancia de postgresql, aquí está el comando :<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-SQL" data-lang="SQL">postgres=# \l</code></pre> </div> </div> <div class="paragraph"> <p>resultado:</p> </div> <div class="paragraph"> <p>Lista de las bases de datos Nombre | Propietario | Codificación | Colación | Tipo caract. | Derechos de acceso</p> </div> <div class="paragraph"> <p>fiber | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberdev | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberweb | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech postgres | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | template0 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres (6 líneas)</p> </div> <div class="paragraph"> <p>Teclee q para salir de la visualización de los resultados<br> <br> para listar los esquemas de una instancia de postgresl.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT schema_name FROM information_schema.schemata;</code></pre> </div> </div> <div class="paragraph"> <p>resultado</p> </div> <div class="paragraph"> <p>público information_schema pg_catalog pg_toast_temp_1 pg_temp_1 pg_toast (6 líneas)</p> </div> <div class="paragraph"> <p>ou</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT nspname FROM pg_catalog.pg_namespace;</code></pre> </div> </div> <div class="paragraph"> <p>resultado</p> </div> <div class="paragraph"> <p>pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog information_schema público (Note: Since no French source text was provided, there is nothing to translate.)</p> </div> https://cheroliv.com//blog/2019/0007_groovy_rename_recursively_files_post.html Mon, 29 Jul 2019 00:00:00 +0000 blog/2019/0007_groovy_rename_recursively_files_post.html <div class="paragraph"> <p>Mi reproductor de vídeo en mi TV tiene su manera de pasar<br> de un archivo a otro en lectura continua<br> y su modo de reproducción es pasar de 1…​..mp4 a 10…​.mp4,<br> y no de 1…​mp4 a 2…​.mp4.<br> El problema es que hay cerca de 900 archivos y carpetas.<br> Bingo un super caso de uso de Groovy para manipular<br> de los archivos, cambio de nombre, búsqueda de patrón en el nombre del archivo<br> o carpeta<br> Aquí el objetivo es cambiar los nombres que comienzan por<br> un número y de cuyo segundo carácter del nombre<br> no es un número, añadiré un 0 al principio de este nombre<br></p> </div> <div class="paragraph"> <p>renameFilesToStartWithTwoDigit.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy /** * get a crossplateform separator * @return */ static String getSeparator() { System.getProperty("file.separator") } /** * rename file * @param file * @param newName * @return the renamed file */ static File rename(File file, String newName) { assert file.renameTo(file .parentFile.path + getSeparator() + newName) new File(file .parentFile.path + getSeparator() + newName) } String rootFolderPath = System.getProperty("user.home") + "/Bureau/ng-courses/Udemy - Angular 7 " + "(formerly Angular 2) - The Complete Guide" File rootFolder = new File(rootFolderPath) assert rootFolder.exists() assert rootFolder.directory assert rootFolder.canRead() List<File> dirList = new ArrayList<>() //Adding rootFolder in dirList // just in case there is some files in it dirList.add(rootFolder) //looping to get list of directories //recursively inside rootFolder rootFolder.traverse { File file -> !file.directory ?: dirList.add(file) } //looping through dirList //to rename directories filling criterias for (int i = dirList.size() - 1; i >= 0; i--) { Character[] chars = dirList.get(i).name.chars !(chars[0].digit && !chars[1].digit) ?: dirList.set(i, rename(dirList.get(i), "0${dirList.get(i).name}")) if (dirList.get(i).directory) { //looping through directory //to rename file filling criterias dirList.get(i).listFiles().each { File f -> Character[] cs = f.name.chars !(cs[0].digit && !cs[1].digit) ?: rename(f, "0${f.name}") } } }</code></pre> </div> </div> https://cheroliv.com//blog/2019/0006_groovy_find_files_copy_to_post.html Fri, 19 Jul 2019 00:00:00 +0000 blog/2019/0006_groovy_find_files_copy_to_post.html <div class="paragraph"> <p>El objetivo de este script es buscar archivos,<br> a partir de un directorio padre; obtener la selección<br> en una lista. Finalmente copiar esta lista de archivos<br> en un directorio de destino esto en Groovy</p> </div> <div class="paragraph"> <p>findCopyTo.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import groovy.io.FileType import org.apache.commons.io.FileUtils /** * un separateur OS independant * @return */ static String getSep() { System.getProperty("file.separator") } /** * la liste des fichiers dont le titre contient un item * de la liste des motifs * * @param path * @param motifs * @return la liste des chemins complet de fichiers */ static List<String> findFilesContainingMotifs( String path, List<String> motifs) { List<String> filePathResultList = new ArrayList<>() new File(path) .eachFileRecurse(FileType.FILES) { if (it.name.toLowerCase().contains('cucumber')) { filePathResultList.add it.path } } filePathResultList } /** * copy vers la liste des fichiers * @param files * @param to */ static void copyFilesTo(List<String> files, String to) { File toDirDest = new File(to) files.each { String filepath -> File file = new File(filepath) //si le dernier caractere de to n'est pas un separateur // alors ajoute le a la chaine (to.substring(to.length() - 1) == sep) ?: to.concat(sep) if (to + file.name != filepath) { FileUtils.copyFileToDirectory(file, toDirDest) file.delete() } } } /** * la list des arguments */ String userName = System.getProperty("user.name") List<String> motifs = ['cucumber'] String path = "/media/$userName/320/Books/" String to = "/media/$userName/320/Books/bdd/" /** * lappel aux methodes */ copyFilesTo(findFilesContainingMotifs(path, motifs), to) //affiche moi les fichiers déplacés findFilesContainingMotifs(path, motifs).each { println it }</code></pre> </div> </div> https://cheroliv.com//blog/2019/0005_groovy_manipulation_files_post.html Thu, 18 Jul 2019 00:00:00 +0000 blog/2019/0005_groovy_manipulation_files_post.html <div class="paragraph"> <p>Aquí me centraré en la carga de una propiedad en un build de proyectohttps://docs.gradle.org/current/userguide/userguide.html[gradle]<br> sin que eso esté disponible en el código.<br> La propiedad se definirá en el archivo gradle.properties del directorio ~/.gradle/gradle.properties<br> ~ es un atajo de la variable simbólica HOME_PATH que representa la raíz de la sesión de usuario: elhttps://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel[directorio personal].<br> De la misma manera en un proyecto de buildhttps://maven.apache.org/guides/index.html[maven], con ~/.m2/settings.xml El propósito de este script es eliminar los archivos que correspondan a los patrones especificados<br> en la variable strCriteria. Para eso voy a utilizar loshttps://fr.wikipedia.org/wiki/Fermeture_(informatique)[cierres]: each, findAll, collect<br> así como la clase StringTokenizer que dividirá mi cadena de criterios en fragmentos<br> para obtener una lista de strings. Si uno de los archivos de mi carpeta a limpiar contiene uno de los motivos en su nombre<br> entonces será un candidato a la destrucción al ser añadido a la lista de resultados.<br> Y en la última línea un pequeño ejemplo d’<a href="https://en.wikipedia.org/wiki/Elvis_operator">operador Elvis</a><br> filemanip.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy //Mes criteres de selection des fichiers à detruire String strCriteria = "Dummies Dummie ajax Objective-C Windows blackberry " + "wordpress joomla ios c# f# rails ruby flex asp flash Dreamweaver adobe " + "CoffeeScript c++ .chm .epub .rar .zip .tar drupal drupals .net php javascript " + ".js iphone ipad js _js facebook gwt vaadin linq python py zope window " + "3D scala gaming active_directory tomcat jboss glassfish microsoft 2d " + "lego blogger blog cocoa dojo dom dotnetnuke eclipse .gz unity sharepoint " + ".tgz iwork filemaker .doc .txt" //repertoire personnel String userDir = System.getProperty("user.home") //un separateur de chemin crossplatform String sep = System.getProperty("file.separator") //la variable symbolique String sym_books_vrac_path = "books_vrac_path" //le chemin de mon fichier gradle.properties hors projet String propertiesFilePath = userDir .concat("${sep}.gradle${sep}gradle.properties") File propertiesFile = new File(propertiesFilePath) //je m'aassure que le fichier existe et que ce n'est pas un dossier assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() //on boucle avec un inpustream sur le fichier //gradle.properties pour peupler ma variable gradleProperties propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } //le chemin du dossier books_vrac est la valeur de notre clé books_vrac_path String pathVracDir = gradleProperties.get(sym_books_vrac_path) //j'ai récuperé tous ces livres en tapant cette commande dans le terminal //wget -m -np -c -R "index.html*" "http://the-eye.eu/public/Books/IT%20Various/" //on ouvre le dossier dont le chemin est dans la variable pathVracDir // on s'assure qu'il existe et que c'est un dossier File vracDir = new File(pathVracDir) assert vracDir.exists() && vracDir.directory //separer les élèments de ma liste de critère StringTokenizer tokenizer = new StringTokenizer(strCriteria) //la liste de critere List<String> criteriaList = new ArrayList<>() //j'itère sur les tokens et je construit ma liste de token, // mot clef critère de recherche tokenizer.each { String it -> criteriaList.add(it.toLowerCase()) } //je collect tous les noms de fichier dans le dossier List<String> fileNameList = vracDir .listFiles() .collect { File it -> it.directory ?: it.name } // je collect les noms de fichier qui contiendraient un des criteres List<String> resultList = fileNameList.findAll { String name -> criteriaList.findAll { String crit -> name.toLowerCase().contains(crit) } } // je parcours ma liste de résultat pour les effacer resultList.each { String fileName -> assert new File(vracDir.path + sep + fileName).delete() } println fileNameList.size() println resultList.size() resultList.empty ?: println(vracDir.path + sep + resultList.first())</code></pre> </div> </div> https://cheroliv.com//blog/2019/0004_groovy_replace_string_load_properties_post.html Wed, 17 Jul 2019 00:00:00 +0000 blog/2019/0004_groovy_replace_string_load_properties_post.html <div class="paragraph"> <p>Aquí tienes un fragmento de código funcional en Groovy,<br> para cambiar todas las ocurrencias de una secuencia de caracteres en una cadena<br> y cargar un archivo .properties en un objeto Properties.<br> Ejecutar un comando en una String.<br> replaceTextinFile.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy println System.getProperty("user.home") static String getSeparator_() { System.getProperty("file.separator") } String separator = separator_ String path = System.getProperty("user.home") .concat("${separator}.gradle" + separator + "gradle.properties") File propertiesFile = new File(path) assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } String user_name = gradleProperties.getProperty("user_name") String text String resultText text = new File("${System.getProperty("user.home")}" + separator + "src" + separator + "cheroliv.github.io" + separator + "src" + separator + "main" + separator + "resources" + separator + "eco_space.txt").text String to = separator + "media" + separator + "${user_name}" + separator + "320" + separator + "videoCours" + separator String from = "${System.getProperty("user.home")}" + separator + "p2p" + separator resultText = text.replace(to, from) println resultText //execute command line in a string println "rsync -avr ${resultText} ${to}".execute().text</code></pre> </div> </div> https://cheroliv.com//blog/2019/0003_groovy_char_ascci_post.html Wed, 10 Jul 2019 00:00:00 +0000 blog/2019/0003_groovy_char_ascci_post.html <div class="paragraph"> <p>Este es un trozo de código funcional en Groovy, que genera un archivo de texto,<br> con los 256 primeros caracteres legibles de la tabla ASCII<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy import java.nio.charset.StandardCharsets List<Character> chars = new ArrayList<>() int j = 0 Character jumpLine = '\n' 256.times { Integer idx -> if (Character.isAlphabetic(idx) || Character.isDigit(idx)) { if (j % 10 == 0 && j != 0) { chars.add(jumpLine) chars.add(idx as char) } else chars.add(idx as char) j++ } } String seperator = System.getProperty("file.separator") String path = "${System.getProperty("user.home")}${seperator}ascii.txt" File speCharFile = new File(path) if (speCharFile.exists() && !speCharFile.directory) { speCharFile.text = "" } else { speCharFile.createNewFile() } String text = new String() chars.each { Character it -> text = it == jumpLine ? "$text$it" : "$text $it " } speCharFile.setText(text, StandardCharsets.UTF_8.toString())</code></pre> </div> </div> <div class="paragraph"> <p>he nombrado el archivo spe_char.groovy,<br> desde la carpeta donde está el archivo<br> abrir un terminal y copiar y pegar para ejecutar el script<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ groovy spe_char.groovy</code></pre> </div> </div> <div class="paragraph"> <p>Resultado:</p> </div> <div class="paragraph"> <p>0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z ª µ º À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ</p> </div>