https://cheroliv.com/ JBake Bootstrap Template en-gb Fri, 25 Sep 2026 01:41:36 +0000 Fri, 25 Sep 2026 01:41:36 +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="#_o_buraco_no_pipeline_de_vídeo">O Buraco no Pipeline de Vídeo</a></li> <li><a href="#_hyperframes_o_motor">HyperFrames : O Motor</a></li> <li><a href="#_a_arquitetura_do_plugin">A Arquitetura do Plugin</a> <ul class="sectlevel2"> <li><a href="#_o_pipeline_em_quatro_etapas">O Pipeline em Quatro Etapas</a></li> <li><a href="#_o_dsl_asciidoc">O DSL AsciiDoc</a></li> <li><a href="#_o_bridge_node_js">O Bridge Node.js</a></li> </ul> </li> <li><a href="#_dois_plugins_de_vídeo_dois_usos">Dois plugins de vídeo, dois usos</a></li> <li><a href="#_os_6_epics_da_roadmap">Os 6 EPICs da Roadmap</a></li> <li><a href="#_por_que_funciona">Por que funciona</a></li> <li><a href="#_conclusão_o_elo_faltante">Conclusão: O elo faltante</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 8 minutes</div> <p>Há duas semanas, eu lancei`capsule-gradle`— um plugin que transforma um deck reveal.js em cápsula de vídeo WebM com TTS. Hoje, estou adicionando um novo plugin : <code>hyperframes-gradle</code>. Ele faz algo que o capsule-gradle não faz : transformar o AsciiDoc <strong>diretamente</strong> em vídeo MP4, sem passar por reveal.js.</p> </div> <div class="paragraph"> <p>Aqui está por que esse plugin existe, como ele se articula com o existente, e o que o motor HyperFrames da HeyGen traz para o pipeline de produção de conteúdo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_buraco_no_pipeline_de_vídeo">O Buraco no Pipeline de Vídeo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Meu pipeline documental produz dois tipos de vídeos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Cápsula de revisão</strong> (capsule-gradle) — um deck reveal.js capturado em WebM com</p> </li> </ol> </div> <div class="paragraph"> <p>narration TTS. Perfeito para rever um módulo.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Slides de animação</strong> (slider-gradle) — um deck reveal.js HTML interativo para</p> </li> </ol> </div> <div class="paragraph"> <p>o formador presencial</p> </div> <div class="paragraph"> <p>Mas falta um terceiro formato: o <strong>vídeo standalone</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">solução atual</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 do 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 revisão</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 teaser</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Nenhuma</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>Nenhuma</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>Doc-para-vídeo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Nenhuma</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O primeiro caso de uso é crítico: como gerar automaticamente um vídeo de 60 segundos que apresenta um projeto ou um módulo, com animações GSAP, narration TTS, música de fundo — tudo desde o mesmo arquivo AsciiDoc os slides ?</p> </div> <div class="paragraph"> <p>Capsule-gradle não pode responder: ele <strong>já</strong> precisa de um deck reveal.js. slider-gradle produz bem esse deck, mas não foi projetado para a renderização de vídeo. Precisava de um pipeline <strong>direto</strong>: AsciiDoc → vídeo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_o_motor">HyperFrames : O Motor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Descobrihttps://github.com/heygen-com/hyperframes[HyperFrames] il y a alguns dias. É um framework open-source (Apache 2.0) criado pelo HeyGen, o unicórnio do vídeo IA. 22 700 estrelas no GitHub. O pitch se encaixa em uma frase :</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>Escreva HTML. Renderize vídeo. Construído para agentes.</strong></p> </div> </blockquote> </div> <div class="paragraph"> <p>O princípio: você escreve HTML com`data-*`attributes, você referencia uma animação GSAP (ou CSS, Lottie, Three.js…), e o motor renderiza tudo em MP4 via Puppeteer (headless Chrome) + FFmpeg. Resultado determinístico: mesmo input, mesmas frames, mesmo vídeo.</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>O que torna o HyperFrames diferente do Remotion? Sem React, sem bundler, sem JSX. HTML simples que os agentes de IA sabem escrever nativamente. É exatamente ajustado para o meu pipeline: planner-gradle com deepseek pode gerar esse HTML a partir de um plano SPG/SPD, e um plugin Gradle pode convertê-lo para MP4.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_arquitetura_do_plugin">A Arquitetura do Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle segue o mesmo padrão que todos os meus plugins: o <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">padrão « Plugin Indépendant + Racine Consommateur »</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="_o_pipeline_em_quatro_etapas">O Pipeline em Quatro Etapas</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 fonte" as adoc #LightYellow ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Pipeline hyperframes-gradle rectangle "AsciiDoc fonte" as adoc #LightYellow rectangle "AsciidoctorJ" as asciidoctorj #LightBlue rectangle "HTML HyperFrames (data-* attrs)" as html #LightGreen rectangle "HyperFrames CLI\n(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> analisa o fonte AsciiDoc e extrai os blocos personalizados</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> gera o HTML HyperFrames com as</p> </li> </ol> </div> <div class="paragraph"> <p>`data-*`atributos correspondentes.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RenderHyperframesTask</strong> chama a CLI HyperFrames via`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>O MP4 é implantado em`output/`com um`metadata.json`para a orquestração.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_o_dsl_asciidoc">O DSL AsciiDoc</h3> <div class="paragraph"> <p>O verdadeiro valor agregado do plugin é o DSL AsciiDoc. O usuário nunca escreve HTML. Ele anota seu 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>Os atributos docinfo (<code>:hyperframes-width:</code>) configuram as dimensões. Os blocos personalizados definem as composições e as faixas. O bloco `[hyperframes-animation]`contém o código GSAP bruto — que o agente IA pode gerar a partir de uma descrição em linguagem natural</p> </div> </div> <div class="sect2"> <h3 id="_o_bridge_node_js">O Bridge Node.js</h3> <div class="paragraph"> <p>O único ponto de atrito técnico: HyperFrames está em Node.js/TypeScript, e meus plugins são em Kotlin/JVM. A solução é um`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>Zero acoplamento código JVM ↔ Node.js. O contrato é por linha de comando e arquivos no disco. É o mesmo padrão que`plantuml-gradle` (que chama a CLI PlantUML) ou`slider-gradle`(que chama AsciidoctorJ). Nada de novo sob o sol — apenas aplicado a uma ferramenta mais recente.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dois_plugins_de_vídeo_dois_usos">Dois plugins de vídeo, dois 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">cápsula-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">Source</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">caso de uso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cápsula de revisão</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">vídeo explicativo standalone</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">natureza</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 → vídeo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">entregue</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">Animação</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transições reveal.js nativas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">atributos de dados GSAP/CSS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pilha</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 + Node.js CLI externo</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Eles não se substituem. Eles se complementam. A cadeia de valor completa:</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ slider-gradle ──→ deck reveal.js ──→ capsule-gradle ──→ WebM (cápsula de revisão)</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ hyperframes-gradle ──→ MP4 (vídeo autônomo)</p> </div> <div class="paragraph"> <p>O utilizador escreve um único ficheiro AsciiDoc. slider-gradle produz os slides. capsule-gradle produz a cápsula de revisão. hyperframes-gradle produz o vídeo teaser e as demonstrações técnicas</p> </div> </div> </div> <div class="sect1"> <h2 id="_os_6_epics_da_roadmap">Os 6 EPICs da Roadmap</h2> <div class="sectionbody"> <div class="paragraph"> <p>O plugin é estruturado em 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">EPIC</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Descrição</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Prioridade</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 governança + enquadramento da arquitetura</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ CONCLUÍDO</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 + Integração 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">Bridge 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">Costumes do DSL AsciiDoc (blocos, docinfo, modelos)</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">Integração 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">Modelos prontos para uso (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 + publicação Maven Central / Gradle Portal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>A sessão 000 (bootstrap) já terminou. A sessão 001 atacará HF-1 : o stub do plugin Gradle e a integração AsciidoctorJ.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_funciona">Por que funciona</h2> <div class="sectionbody"> <div class="paragraph"> <p>Três razões :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HyperFrames é "built for agents</strong>". Meu pipeline depende de agentes de IA</p> </li> </ol> </div> <div class="paragraph"> <p>(planner-gradle + deepseek) que geram conteúdo. HyperFrames aceita de HTML bruto — o formato que os LLMs dominam melhor. Sem React, não de JSX, sem curva de aprendizagem para o agente.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>O DSL AsciiDoc é natural</strong>. Todo o meu ecossistema fala AsciiDoc.</p> </li> </ol> </div> <div class="paragraph"> <p>slider-gradle, codex-gradle, training-gradle — todos consomem do`.adoc`. Adicionar blocos personalizados`[hyperframes-composition]`é uma extensão lógico, não uma ruptura.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>O bridge Node.js é um padrão comprovado</strong>. ProcessBuilder fora da JVM,</p> </li> </ol> </div> <div class="paragraph"> <p>isso é o que eu já faço para PlantUML, Graphviz, Piper. Adicionar HyperFrames não muda nada na arquitetura — é mais uma ferramenta externa, pilotado a partir do 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>A verdadeira força do padrão é que não há <strong>nenhuma</strong> dependência npm em o build Gradle. O plugin não importa código Node.js. Ele executa uma comando shell. Se HyperFrames evolui ou quebra, o plugin não está acoplado — basta atualizar o comando.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_elo_faltante">Conclusão: O elo faltante</h2> <div class="sectionbody"> <div class="paragraph"> <p>Com hyperframes-gradle, meu pipeline de vídeo está completo. Eu tenho :</p> </div> <div class="ulist"> <ul> <li> <p>As <strong>slides interativas</strong> (slider-gradle)</p> </li> <li> <p>As <strong>capsules de revisão</strong> (capsule-gradle)</p> </li> <li> <p><strong>vídeos standalone</strong> (hyperframes-gradle)</p> </li> </ul> </div> <div class="paragraph"> <p>Três formatos. Um único arquivo fonte: o AsciiDoc.</p> </div> <div class="paragraph"> <p>O próximo objetivo é HF-1 : compilar o plugin e gerar um primeiro HTML HyperFrames a partir de um documento AsciiDoc anotado. A sessão 001 já está enquadrada.</p> </div> <div class="paragraph"> <p>hyperframes-gradle existe. A governança está instalada. O backlog est escrito. A arquitetura está documentada. O plugin nasceu.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">Artigo 0124 — Arquitetura do Plugin Independente + Raiz do 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 — Documentação</a></p> </li> <li> <p><code>foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc</code>— Arquitetura detalhada</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="#_compreender_a_stack_quem_faz_o_que">Compreender a Stack: Quem Faz o Que?</a></li> <li><a href="#_introdução_por_que_realizar_uma_auditoria">Introdução : Por que realizar uma auditoria ?</a></li> <li><a href="#_a_base_de_dados_opencode_uma_mina_de_ouro">A Base de Dados OpenCode : Uma Mina de Ouro</a> <ul class="sectlevel2"> <li><a href="#_o_esquema">O esquema</a></li> <li><a href="#_o_código_de_extração">O Código de Extração</a></li> </ul> </li> <li><a href="#_os_resultados_73_dias_de_consumo">Os Resultados: 73 Dias de Consumo</a> <ul class="sectlevel2"> <li><a href="#_visão_global">Visão Global</a></li> <li><a href="#_ventilação_por_modelo_e_fornecedor">Ventilação por Modelo e Fornecedor</a></li> <li><a href="#_os_modelos_intra_sessão_o_que_a_tabela_de_sessão_não_vê">Os Modelos Intra-Sessão: O Que a Tabela de Sessão Não Vê</a></li> </ul> </li> <li><a href="#_comparativo_tarifário_fornecedores_ocidentais">Comparativo Tarifário — Fornecedores Ocidentais</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="#_provedores_de_inferência_huggingface">Provedores de Inferência HuggingFace</a></li> <li><a href="#_groq">Groq</a></li> </ul> </li> <li><a href="#_comparativo_tarifário_fornecedores_chineses">Comparativo Tarifário — Fornecedores Chineses</a> <ul class="sectlevel2"> <li><a href="#_deepseek_api_direct_platform_deepseek_com">DeepSeek API Direct (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="#_tabela_resumo_todos_providers">Tabela Resumo — Todos Providers</a></li> <li><a href="#_o_custo_oculto_engenharia_de_prompts_e_iterações">O Custo Oculto : Engenharia de Prompts e Iterações</a></li> <li><a href="#_acumular_as_assinaturas_ollama_cloud_pro_o_método_docker">Acumular as Assinaturas Ollama Cloud Pro: O Método Docker</a></li> <li><a href="#_o_que_a_auditoria_não_mede">O Que a Auditoria Não Mede</a></li> <li><a href="#_conclusão_o_veredito_dos_números">Conclusão: O Veredito dos Números</a></li> <li><a href="#_referências">Referências</a> <ul class="sectlevel2"> <li><a href="#_fontes_das_tarifas">Fontes das tarifas</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 22 minutes</div> <p>Muitas vezes me perguntam quanto custa meu consumo de IA. Eu respondo « 20 euros por mês » e eles me olham com os olhos arregalados. Então hoje, eu abro a caixa preta para vocês. Este artigo é a auditoria completa dos meus 73 dias de vibe coding : a metodologia para extrair os dados da base SQLite d’OpenCode, o código SQL para consultar as tabelas, e a comparação exaustiva com <strong>todos</strong> os fornecedores do mercado — ocidentais como chineses. O resultado é tão assimétrico que tive que verificar meus cálculos três vezes.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p></think></p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_compreender_a_stack_quem_faz_o_que">Compreender a Stack: Quem Faz o Que?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de mergulhar nos números, vamos esclarecer a arquitetura. Há três atores distintos no meu setup, e é importante não confundir os três :</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 Os Três Atores da Minha Stack LLM left to right direction actor "Eu (Desenvolvedor)" 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 Os Três Atores da Minha Stack LLM left to right direction actor "Eu (Desenvolvedor)" as Dev package "OpenCode\n(github.com/anomalyco/opencode)" as OC { rectangle "CLI de vibe coding Código aberto, 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 (Instalação Local)" as OL { rectangle "Cliente de inferência\nInstalado na minha 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 "Serviço de inferência em nuvem Assinatura Pro : 20€/mês" 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 : "Eu digito prompts" CLI --> Client : "Chame este modelo" Client --> Cloud : "Chave SSH + requisição\n(modelos :cloud)" Client --> Client : "Execução local (modelos sem :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 NÃO é um fornecedor de modelos.</strong>É um CLI de código aberto (<a href="https://github.com/anomalyco/opencode">github.com/anomalyco/opencode</a>) que orquestra agentes de IA. Ele não vende assinatura, ele não fornece inferência. É o equivalente de`git`para versionamento: uma ferramenta, não um serviço. <strong>Ollama Cloud é o fornecedor da inferência.</strong>Minha instalação local do Ollama atua como <strong>client</strong> — ela se autentica nos servidores do Ollama por meio de uma chave SSH única (Device Key) e delega a execução dos modelos marcados a eles`:cloud`. A assinatura Pro (20€/mês) desbloqueia quotas superiores e permite acumular várias contas na mesma máquina via Docker.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_introdução_por_que_realizar_uma_auditoria">Introdução : Por que realizar uma auditoria ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Há dois meses, estava usando modelos gratuitamente na minha instalação local do Ollama. Então assinei um primeiro plano Ollama Cloud Pro de 20€/mês, que me permite usar os modelos em nuvem (aqueles com a tag`:cloud`) via o provider`ollama-cloud`. Uma segunda assinatura ocorreu um mês depois, em uma instância Docker separada com sua própria conta e chave SSH — o método de acumulação descrito em <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">meu artigo sobre a acumulação de assinaturas</a></p> </div> <div class="paragraph"> <p>A pergunta que me atormentava : <strong>será que esses 20€ por mês são justificados ?</strong> Não de bate-pronto. Com números.</p> </div> <div class="paragraph"> <p>Para responder, eu precisava de dados precisos. Não eram estimativas. Não eram médias. Meu consumo <strong>real</strong>, token por token, modelo por modelo, sessão por sessão.</p> </div> <div class="paragraph"> <p>E OpenCode — a CLI — armazena tudo isso em um banco de dados SQLite.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_base_de_dados_opencode_uma_mina_de_ouro">A Base de Dados OpenCode : Uma Mina de Ouro</h2> <div class="sectionbody"> <div class="paragraph"> <p>OpenCode persiste a integralidade do histórico de suas sessões em um arquivo SQLite localizado em`~/.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="_o_esquema">O esquema</h3> <div class="paragraph"> <p>A base contém cerca de vinte tabelas, mas três delas são cruciais para nossa auditoria:</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>A mesa`session`é perfeita para uma auditoria global: cada sessão tem sua contagem agregada de tokens, o modelo utilizado e seu custo. O campo`model`é 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>o campo`cost`na base OpenCode reflete apenas as <strong>taxas de API externas</strong> pagas por consumo via chave de API (Google Gemini, OpenAI, etc.). As chamadas via Ollama — seja localmente ou via Ollama Cloud Pro — são marcadas`cost=0`Porque o custo é fixo (assinatura), não por token. O verdadeiro custo dessas chamadas é a assinatura mensal.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_o_código_de_extração">O Código de Extração</h3> <div class="paragraph"> <p>Não é preciso instalar nada. Node.js 22+ inclui um módulo SQLite experimental (<code>node:sqlite</code>) que funciona perfeitamente. Aqui está o script que me deu tudo:</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>O flag`--experimental-sqlite`É necessário no Node.js 22.x. No Node.js 24+, o módulo é estável e não requer mais nenhum sinalizador.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_os_resultados_73_dias_de_consumo">Os Resultados: 73 Dias de Consumo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_visão_global">Visão 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étrica</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>Sessões 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 sessões por dia em média</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>tokens de entrada</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,62 bilhões</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dont 94,5M em acertos de cache</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 milhões</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">Negligível — quase nenhum pensamento</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Custo da 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">Custos fora da assinatura (Gemini + free tiers)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Este número de $0,22 é crucial: representa tudo o que eu paguei <strong>além</strong> da minha assinatura Ollama Cloud Pro. Ou seja, praticamente nada. A assinatura cobre o essencial.</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 Evolução Mensal — Tokens de Entrada rectangle "Março 2026 9 sessões ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Evolução Mensal — Tokens de Entrada rectangle "Março 2026 9 sessões 37,7M tokens" as MARS #FFE082 rectangle "Abril 2026 486 sessões 1,33 Md tokens" as AVR #81C784 rectangle "Maio 2026 527 sessões 1,25 bi 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>O decolagem entre março e abril é espetacular: ×35 em um mês. É a transição do uso « teste » para o uso « produção » — quando comecei a fazer rodar agentes OpenCode continuamente para meus plugins Gradle.</p> </div> </div> <div class="sect2"> <h3 id="_ventilação_por_modelo_e_fornecedor">Ventilação por Modelo e Fornecedor</h3> <div class="paragraph"> <p>O campo`model`da mesa`session`sendo JSON,`json_extract()`permite ventilar adequadamente :</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">Sessões</th> <th class="tableblock halign-left valign-top">[No output, as no French text was provided for translation]</th> <th class="tableblock halign-left valign-top">Output</th> <th class="tableblock halign-left valign-top">Custo</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>Três provedores diferentes para exatamente o mesmo modelo DeepSeek V4 Pro : * <code>ollama-cloud</code>→ via <strong>assinatura Pro paga</strong> (cloud gerenciado por Ollama) * <code>ollama-b</code>→ <strong>segunda assinatura Pro</strong>, isolado em um contêiner Docker separado * <code>ollama</code>→ instance native locale, <strong>gratuita</strong> (executa diretamente na minha máquina) O somatório das três dá 936M de entrada, 8,4M de saída — é o meu consumo total DeepSeek V4 Pro, todos os provedores combinados. Só`ollama-cloud`(220M input) custa uma assinatura. Os 716M restantes são gratuitos (local ou acúmulo de assinaturas).</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_os_modelos_intra_sessão_o_que_a_tabela_de_sessão_não_vê">Os Modelos Intra-Sessão: O Que a Tabela de Sessão Não Vê</h3> <div class="paragraph"> <p>A mesa`session`Captura apenas o modelo <strong>principal</strong> da sessão. Mas durante a mesma sessão, um agente OpenCode pode alternar entre vários modelos. A tabela`message`o 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>Não uso mais Qwen, GLM, Kimi nem os outros modelos. Eles aparecem no histórico porque testei muitas coisas em abril. Desde meados de maio, estou bloqueado no DeepSeek V4 Pro — é o único que sustenta a carga em contextos longos com governança de agente (cf. <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">minha comparação Kimi/GLM/DeepSeek</a>). Os 32% de mensagens deepseek no histórico são enganosos: hoje é 100%.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparativo_tarifário_fornecedores_ocidentais">Comparativo Tarifário — Fornecedores Ocidentais</h2> <div class="sectionbody"> <div class="paragraph"> <p>A questão que fere : quanto custaria esse mesmo consumo junto aos fornecedores tradicionais?</p> </div> <div class="paragraph"> <p>Minha base de cálculo para o comparativo :<strong>220M tokens de entrada + 1,9M tokens de saída</strong>— <strong>apenas</strong> o volume passado por`ollama-cloud`(o único que corresponde ao meu plano pago). Os 716M restantes são gratuitos (Ollama local e instância 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">fornecedor</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">Output \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">× minha assinatura</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Minha configuração</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">Saída \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">× minha assinatura</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>Mesmo o Haiku 4.5, o modelo mais « econômico » da Claude, custa 11× a minha assinatura. E ele não sabe nada do meu código base, não gera nada no meu estilo e alucina nas 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</th> <th class="tableblock halign-left valign-top">Sortie \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">× minha assinatura</th> </tr> </thead> <tbody> <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">\$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"><strong>58×</strong></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">\$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"><strong>29×</strong></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">\$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"><strong>9×</strong></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">Saída \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">minha assinatura</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€ é o único concorrente « próximo » em preço puro — mas é um modelo denso leve, não um MoE 1.6T como o DeepSeek V4 Pro. A qualidade do código gerado não tem nada a ver.</p> </div> </div> <div class="sect2"> <h3 id="_provedores_de_inferência_huggingface">Provedores de Inferência HuggingFace</h3> <div class="paragraph"> <p>HuggingFace não realiza inferência por conta própria — ele agrega <strong>fornecedores</strong> terceiros (Novita, Together, DeepInfra, Cerebras, SambaNova, Fireworks, Groq…) via uma API unificada. Escolhe-se o fornecedor mais barato ou o mais rápido. Os tarifos coletados em maio de 2026 para DeepSeek V4 Pro são os seguintes:</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">Provedor HF</th> <th class="tableblock halign-left valign-top">$/M</th> <th class="tableblock halign-left valign-top">Preservar TODO os spans de código entre crases (<code>…​</code>) exatamente como estão — nunca modifique o conteúdo, o espaçamento ou a posição das crases. Este texto pode ser um fragmento de uma frase maior — traduza o fragmento sem solicitar mais contexto. Apresente apenas o texto traduzido — sem explicação, sem comentário, sem introdução, sem alternativas, sem opções. Saída \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">× minha assinatura</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Novita (o mais 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">junto</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">Fogos de artifício</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">tarifa não 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">(Empty)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Mesmo o provedor mais barato na HuggingFace (Novita) cobra 19× o preço da minha assinatura. E, ao contrário do Ollama Cloud, a HuggingFace também cobra <strong>em mais</strong> as tarifas de plataforma se você não tiver uma assinatura PRO HF ($9/mês).</p> </div> </div> <div class="sect2"> <h3 id="_groq">Groq</h3> <div class="paragraph"> <p>Groq não tem <strong>nenhum</strong> dos modelos que eu uso — o catálogo deles se limita a GPT-OSS, Llama e Qwen 32B. Impossível de comparar.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparativo_tarifário_fornecedores_chineses">Comparativo Tarifário — Fornecedores Chineses</h2> <div class="sectionbody"> <div class="paragraph"> <p>O verdadeiro teste é o mercado chinês. Se o DeepSeek é um modelo chinês, a sua API nativa deveria ser mais barata, não é?</p> </div> <div class="sect2"> <h3 id="_deepseek_api_direct_platform_deepseek_com">DeepSeek API Direct (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">Saída \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Promo -75% (fim 31 de maio)</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 cheia (a partir de junho)</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>Mesmo com a promo agressiva da DeepSeek (-75% prolongada), a API direta custa<strong>5 vezes</strong>mais caro. À tarifa normal,<strong>20×</strong>. E isso é <strong>apenas</strong> DeepSeek — sem acesso a outros 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 apenas oferece seus próprios modelos. Sem DeepSeek.</p> </div> </div> <div class="sect2"> <h3 id="_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</h3> <div class="paragraph"> <p>Somente fornecedor que agrega todos os modelos chineses — mas por meio de revenda com margem. Os preços são carregados dinamicamente em JavaScript, tornando o scraping impossível.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tabela_resumo_todos_providers">Tabela Resumo — Todos Providers</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">Fornecedor</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">Saída \$/M</th> <th class="tableblock halign-left valign-top">Custo/mês</th> <th class="tableblock halign-left valign-top">× minha assinatura</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Nuvem 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">API DeepSeek (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">Together 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 Custo Mensal Projetado — 220M Input + 1,9M Output rectangle "Ollama Cloud Pro ~20€" as OC #4CAF50 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title Custo Mensal Projetado — 220M Input + 1,9M Output rectangle "Ollama Cloud Pro ~20€" as OC #4CAF50 rectangle "Gemini Flash $69" as GF #8BC34A rectangle "DeepSeek promoção $98" as DSP #FFC107 rectangle "GPT Mini $174" as GM #FF9800 rectangle "Claude Haiku \$230" as CH #FF5722 rectangle "HF/Novita \$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="_o_custo_oculto_engenharia_de_prompts_e_iterações">O Custo Oculto : Engenharia de Prompts e Iterações</h2> <div class="sectionbody"> <div class="paragraph"> <p>O custo do token é apenas uma parte da equação. O verdadeiro custo é o tempo do desenvolvedor.</p> </div> <div class="paragraph"> <p>Com o OpenCode + Ollama Cloud Pro + meu agente de governança (EAGER/LAZY/Hot/Warm/Cold, descrito em <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">o artigo sobre governança</a>), obtenho:</p> </div> <div class="ulist"> <ul> <li> <p><strong>0 prompt engineering repetitivo</strong>: o contexto é injetado automaticamente</p> </li> <li> <p><strong>90%+ de acerto na primeira tentativa</strong>: o código compila de primeira</p> </li> <li> <p><strong>Zero alucinação deepseek em 8 sessões consecutivas</strong>(documentado em <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">la comparaison Kimi/GLM/DeepSeek</a>)</p> </li> </ul> </div> <div class="paragraph"> <p>Com Claude ou GPT <strong>sem</strong> ajuste fino nem governança:</p> </div> <div class="ulist"> <ul> <li> <p>2-3 iterações por tarefa em média</p> </li> <li> <p>Prompt engineering sistemática</p> </li> <li> <p>Alucinações nas APIs Kotlin/Gradle assim que o contexto ultrapassar 30K tokens</p> </li> </ul> </div> <div class="paragraph"> <p>O custo « efetivo » mensal — tokens × iterações × tempo de correção — é de 27× a 54× o da minha solução, como eu demonstrei no <a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">artigo sobre a relação de eficiência</a>.</p> </div> <div class="paragraph"> <p><em><em>_ Não é apenas uma questão de preço por token. Um Claude Opus a 57× o preço que requer 3× mais iterações, resultando em um custo efetivo ~170× maior. Para falar francamente: pagar a um estagiário o salário de um parceiro da McKinsey. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_acumular_as_assinaturas_ollama_cloud_pro_o_método_docker">Acumular as Assinaturas Ollama Cloud Pro: O Método Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se uma única assinatura não for suficiente, acumulamos‑nas. O princípio é isolar cada assinatura em sua própria instalação Ollama, com sua própria chave SSH de autenticação. Docker torna isso trivial.</p> </div> <div class="paragraph"> <p>O método completo está detalhado em <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">o artigo sobre o cumul Docker</a>, aqui está o princípio :</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 Arquitetura — Duas Assinaturas Ollama Cloud Pro em Uma Máquina left to right direction node "Minha Máquina Física" { frame "Ollama Instância A (nativo) ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 title Arquitetura — Duas Assinaturas Ollama Cloud Pro em Uma Máquina left to right direction node "Minha Máquina Física" { frame "Ollama Instância A (nativo) porta :11434 Ollama Instância A (nativo) porta :11434" as Native { database "Identidade A /usr/share/ollama/.ollama/id_ed25519" } frame "Ollama Instance B (Docker) porta :11435" as Docker { database "Identidade B ~/ollama-b-data/id_ed25519" } } cloud "Ollama Nuvem" { actor "Conta Pro A (e‑mail 1)" as A actor "Conta Pro B\n(email 2)" as B } Native --> A : "Chave de dispositivo A" Docker --> B : "Chave de dispositivo 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>O padrão é simples :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Criar um volume`~/ollama-b-data`</p> </li> <li> <p>Iniciar um contêiner Docker`ollama/ollama:0.20.2`mapeado em`11435:11434`</p> </li> <li> <p>Recuperar a chave SSH do contêiner → registrá‑la em ollama.com</p> </li> <li> <p>fazer`ollama signin`com um segundo e-mail</p> </li> <li> <p>Configurar OpenCode com dois providers (`ollama`em :11434,`ollama-b`em :11435)</p> </li> </ol> </div> <div class="paragraph"> <p>Duas contas, um cartão azul, zero conflito.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_a_auditoria_não_mede">O Que a Auditoria Não Mede</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">Ponto cego</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>Qualidade do código produzido</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,6 bilhões de tokens não dizem se o código compila. As minhas 8 sessões DeepSeek V4 Pro têm uma taxa de first-shot >90%.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ecossistema OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O CLI é gratuito, mas o seu valor (agentes, sandboxes, histórico, caching de prompt) é imenso. Não está incluído no preço da assinatura — é uma ferramenta separada.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Custo de oportunidade</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Passar 2h/dia depurando as alucinações de um modelo inferior custa mais caro do que 20€/mês.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tranquilidade de espírito</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tarifa fixa = sem surpresa. Com o modelo de preço por token, um pico de atividade pode fazer muito mal.</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>Os preços citados são os de maio de 2026. Daqui a seis meses, tudo terá baixado. Mas a relação de força estrutural — assinatura fixa vs pagamento por uso — permanecerá favorável à assinatura para os grandes consumidores.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_veredito_dos_números">Conclusão: O Veredito dos Números</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depois de 73 dias, 1 022 sessões OpenCode e 2,6 bilhões 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étrica</th> <th class="tableblock halign-left valign-top">veredicto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo acumulado da API externa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>$0,22</strong>(quase nulo)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo assinatura Ollama Cloud Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20€/mês</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/mês</strong>— 57 vezes mais 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/mês</strong>— 58 vezes mais 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/mês</strong>— 19× mais caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente direto da API DeepSeek</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$390/mês</strong>— 20 vezes mais caro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Equivalente mais barato (Gemini Flash)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$69/mês</strong>— 3,5× mais caro, modelo inferior</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Melhor oferta do mercado</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro por 20€/mês</strong>— invencível</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>__</em> A 20€ por mês para acessar o DeepSeek V4 Pro (1.6T params, MoE, CSA+HCA, 1M contexto) via Ollama Cloud, tenho a melhor relação custo-benefício do mercado mundial. Mesmo os fornecedores chineses diretos são 5× a 20× mais caros. Mesmo o HuggingFace, com sua agregação de providers low-cost, é 19× mais caro. O mercado ocidental (Claude, GPT) está em 50-60× — outro planeta.</p> </div> <div class="paragraph"> <p>Esta razão é tão desequilibrada que não pode durar para sempre. Aproveite enquanto isso existir. <em>__</em></p> </div> <div class="paragraph"> <p>Então sim, meus 20 reais por mês, é o melhor investimento técnico da minha vida de desenvolvedor. E agora você tem os números para provar isso.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Artigo 0108 — Governança 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">Artigo 0112 — DeepSeek V4 Pro vs Kimi K2.6 vs GLM 5.1</a></p> </li> <li> <p>Artigo 0119 — Benchmark DGX Spark vs Cloud vs Assinaturas LLM</p> </li> <li> <p><a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">Article 0120 — Cumuler Deux Abonnements Ollama Cloud Pro avec Docker</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Artigo 0121 — Plugin Gradle para Pilotar Duas Instâncias Ollama</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Artigo 0122 — Razão de Eficiência 27× a 54×</a></p> </li> </ul> </div> <div class="sect2"> <h3 id="_fontes_das_tarifas">Fontes das tarifas</h3> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/pricing">Ollama Cloud — Tarifas Pro \$20/mês</a></p> </li> <li> <p><a href="https://api-docs.deepseek.com/quick_start/pricing">DeepSeek API — Tarifas oficiais 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 — Preços da API Claude</a></p> </li> <li> <p><a href="https://openai.com/api/pricing/">OpenAI — Tarifas da API GPT</a></p> </li> <li> <p><a href="https://together.ai/pricing">Together AI — Taxas de inferência</a></p> </li> <li> <p><a href="https://groq.com/pricing">Groq — Preços da API</a></p> </li> <li> <p><a href="https://deepinfra.com/pricing">DeepInfra — Preços de GPU e modelos</a></p> </li> <li> <p><a href="https://help.aliyun.com/zh/model-studio/text-generation-model/">Alibaba Bailian — Modelos disponíveis</a></p> </li> <li> <p><a href="https://github.com/anomalyco/opencode">OpenCode — CLI de código aberto no 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="#_o_problema_três_arquiteturas_que_me_fizeram_perder_tempo">O Problema : Três Arquiteturas Que Me Fizeram Perder Tempo</a> <ul class="sectlevel2"> <li><a href="#_opção_1_o_plugin_isolado_sem_dogfooding">Opção 1 : O Plugin Isolado (sem dogfooding)</a></li> <li><a href="#_opção_2_o_monorepo_clássico_includeplugin">Opção 2: O Monorepo Clássico (<code>include(":plugin")</code>)</a></li> <li><a href="#_opção_3_a_build_composto_includebuild">Opção 3 : a Build Composto (<code>includeBuild()</code>)</a></li> </ul> </li> <li><a href="#_a_solução_dois_builds_independentes_uma_raiz_do_consumidor">A Solução : Dois Builds Independentes, Uma Raiz do Consumidor</a> <ul class="sectlevel2"> <li><a href="#_o_fluxo_de_trabalho">O Fluxo de Trabalho</a></li> <li><a href="#_o_workflow_concreto">O Workflow Concreto</a></li> </ul> </li> <li><a href="#_por_que_essa_arquitetura_me_conquistou">Por que essa arquitetura me conquistou</a> <ul class="sectlevel2"> <li><a href="#_1_dogfooding_nativo_feedback_instantâneo">1. Dogfooding Nativo, Feedback Instantâneo</a></li> <li><a href="#_2_clonagem_zero_config">2. Clonagem Zero-Config</a></li> <li><a href="#_3_builds_isolados_ci_independentes">3. Builds Isolados, CI Independentes</a></li> </ul> </li> <li><a href="#_a_anatomia_do_subdiretório_name_plugin">A Anatomia do Subdiretório `{name}-plugin/</a> <ul class="sectlevel2"> <li><a href="#_o_catálogo_de_versões_dois_arquivos_distintos">O Catálogo de Versões: Dois Arquivos Distintos</a></li> </ul> </li> <li><a href="#_o_que_não_se_faz">O Que Não Se Faz</a></li> <li><a href="#_comparação_as_três_arquiteturas_face_ao_dogfooding">Comparação: As Três Arquiteturas Face ao Dogfooding</a></li> <li><a href="#_o_contrato_dag_um_build_racin_nunca_de_um_subdiretório">O Contrato DAG : Um Build Racin Nunca de um Subdiretório</a></li> <li><a href="#_conclusão_a_duplicação_aparente_que_faz_ganhar_tempo">Conclusão: a duplicação aparente que faz ganhar tempo</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 11 minutes</div> <p>Você clona um repositório de plugin Gradle. Você abre um terminal. O que você está digitando? depois?<code>./gradlew tasks</code>, claro. Mas em qual pasta? A raiz? O submódulo? Deve-se primeiro ler um README para saber como compilar ? Se você hesitar não seria Em um segundo, a arquitetura do projeto está quebrada.</p> </div> <div class="paragraph"> <p>Eis como resolvi esse problema de vez — e por que isso padrão é hoje a assinatura de todos os meus plugins Gradle em`foundry/public/`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_três_arquiteturas_que_me_fizeram_perder_tempo">O Problema : Três Arquiteturas Que Me Fizeram Perder Tempo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de convergir para o padrão atual, eu tateei entre três abordagens. clássicos para organizar um plugin Gradle. Cada um tinha um defeito redhibitório.</p> </div> <div class="sect2"> <h3 id="_opção_1_o_plugin_isolado_sem_dogfooding">Opção 1 : O Plugin Isolado (sem dogfooding)</h3> <div class="paragraph"> <p>O projeto contém apenas o plugin. Sem exemplo de consumo. Sem projeto que o exerce. Para testá-lo, é necessário criar um projeto externo, lá referenciar o plugin via`mavenLocal`ou um build composto, e somente lá para 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>Um plugin Gradle sem exemplo de consumo, é uma biblioteca sem testes de integração. Você nunca sabe se a última modificação tem quebrou a experiência do usuário.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_opção_2_o_monorepo_clássico_includeplugin">Opção 2: O Monorepo Clássico (<code>include(":plugin")</code>)</h3> <div class="paragraph"> <p>Gradle`init`gera`settings.gradle.kts`com`include("plugin")`. O root e o submódulo compartilham o mesmo daemon, as mesmas configurações, os mesmos catálogos. Prático, mas 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>O que trava:</p> </div> <div class="ulist"> <ul> <li> <p>a raiz<strong>deve</strong>ter a mesma versão do Gradle que o submódulo.</p> </li> <li> <p>`libs.versions.toml`é compartilhado — catálogos de versão comuns, dependências</p> </li> </ul> </div> <div class="paragraph"> <p>que fogem de um módulo para outro.</p> </div> <div class="ulist"> <ul> <li> <p>Impossível construir o plugin independentemente do root.</p> </li> <li> <p>O CI deve construir os dois módulos, mesmo que apenas o plugin tenha mudado.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_opção_3_a_build_composto_includebuild">Opção 3 : a Build Composto (<code>includeBuild()</code>)</h3> <div class="paragraph"> <p>Separamos os dois em builds Gradle distintos e os conectamos via <code>includeBuild("mon-plugin")`em`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>Já está melhor. O build do plugin está isolado. Mas o consumidor deve explicitamente referenciar o build externo — e a saída de `./gradlew tasks`na raiz depende da configuração correta do composite. A clonagem não é zero-config: é preciso saber que o plugin está em um diretório separado, o root faz referência a ele, 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>Eu estava procurando melhor. Muito melhor.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_dois_builds_independentes_uma_raiz_do_consumidor">A Solução : Dois Builds Independentes, Uma Raiz do Consumidor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este é o padrão que acabei por adotar :</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>A chave:`{name}-plugin/`é um projeto Gradle <strong>completo e autônomo</strong>. Ele tem o próprio wrapper, o próprio settings, o próprio católico de versões. Ele é clonado, buildado, testado e publicado sem que o root seja ciente de sua existência</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>O root, ele, só faz <strong>uma</strong> coisa : aplicar o 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>Três linhas no caso de`bakery-gradle`. Nada mais Zero`include()<code>, zero`includeBuild()</code>, zero subprojeto. Um build Gradle clássico que aplica um plugin como qualquer qual consumidor faria isso</p> </div> <div class="sect2"> <h3 id="_o_fluxo_de_trabalho">O Fluxo de Trabalho</h3> <div class="imageblock"> <div class="content"> <img src="./images/architecture-deux-builds.svg" alt="architecture deux builds" width="1267" height="151"> </div> </div> </div> <div class="sect2"> <h3 id="_o_workflow_concreto">O 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_que_essa_arquitetura_me_conquistou">Por que essa arquitetura me conquistou</h2> <div class="sectionbody"> <div class="paragraph"> <p>Três benefícios que, combinados, valem o custo da «duplicação»:</p> </div> <div class="sect2"> <h3 id="_1_dogfooding_nativo_feedback_instantâneo">1. Dogfooding Nativo, Feedback Instantâneo</h3> <div class="paragraph"> <p>O melhor teste de um plugin Gradle é usá-lo. Não é um teste unitário mockado. Não é um`GradleRunner`com um projeto de teste. Um <strong>verdadeiro</strong> build que aplica o plugin em arquivos reais.</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>Se o plugin estiver quebrado, o build raiz diz isso. Não é necessário ir procurar um projeto de teste externo. O dogfooding é a <strong>primeira</strong>. tarefa que lança um novo contribuidor. É o teste de fumaça definitivo.</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>A regra é simples: se a raiz compila e que`./gradlew tasks` exibe suas tarefas de plugin, o plugin está funcional. Sem surpresa em produção.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_clonagem_zero_config">2. Clonagem Zero-Config</h3> <div class="paragraph"> <p>Un `git clone && ./gradlew tasks`e o recém-chegado vê tudo caminhar sem configurar nada. O`build.gradle.kts`raiz é a documentação viva de uso do plugin. O`site.yml`ao lado Mostra a configuração esperada.</p> </div> <div class="paragraph"> <p>Compare com a alternativa: um README de três parágrafos que explica como construir o plugin e como construir o projeto de teste. Um novo colaborador lê o README na diagonal, está enganado, abre uma issue — enquanto a informação poderia ser <strong>executável</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>A documentação mais robusta não é aquela que se lê. É aquela que a gente<strong>executa</strong>. O build raiz é a documentação executável do plugin.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3_builds_isolados_ci_independentes">3. Builds Isolados, CI Independentes</h3> <div class="paragraph"> <p>O plugin tem seu próprio wrapper Gradle, seu próprio ciclo de vida, seus próprios testes. Você pode :</p> </div> <div class="ulist"> <ul> <li> <p>Atualizar o Gradle no plugin sem tocar na raiz</p> </li> <li> <p>Adicionar uma dependência no plugin sem que ela vaze para a raiz</p> </li> <li> <p>Quebrar o plugin sem afetar o build raiz (enquanto você não</p> </li> </ul> </div> <div class="paragraph"> <p>não publique a versão quebrada)</p> </div> <div class="ulist"> <ul> <li> <p>Ter uma CI que build/test o plugin, e outra que exerce o</p> </li> </ul> </div> <div class="paragraph"> <p>root — independentemente</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="_a_anatomia_do_subdiretório_name_plugin">A Anatomia do Subdiretório `{name}-plugin/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Vamos dar uma olhada mais atenta no que vive na pasta do 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>Tudo está aqui. Não há dispersão entre a raiz e o subdiretório. O desenvolvedor que trabalha no plugin nunca precisa de sair`codebase-plugin/`. O desenvolvedor que usa o plugin só olha a raiz — e o`build.gradle.kts`de 3 linhas ele lhe diz tudo o que ele precisa saber</p> </div> <div class="sect2"> <h3 id="_o_catálogo_de_versões_dois_arquivos_distintos">O Catálogo de Versões: Dois Arquivos 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>(raiz)</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 dependências</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">30+ (langchain4j, pgvector, cucumber…​)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">papel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consumir o plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Construa o plugin</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Quem o lê</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O utilizador do plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O desenvolvedor do plugin</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O root tem um catálogo intencionalmente mínimo. O plugin tem um catálogo completo. A confusão é impossível: cada build tem seu próprio scope de dependências.</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>Se já passou uma hora depurando uma colisão de dependências entre o seu plugin e o seu projeto de teste, você compreende o valor de esta separação. Os catálogos independentes eliminam esse problema por construção.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_não_se_faz">O Que Não Se Faz</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este padrão não é mágico. Ele impõe uma restrição que eu Me inflige voluntariamente:</p> </div> <div class="paragraph"> <p><strong>O root não constrói o plugin.</strong> Você deve`publishToMavenLocal` ou implantar em um repositório antes que o root possa consumi‑lo.</p> </div> <div class="paragraph"> <p>É um custo mínimo, e é a <strong>boa</strong> restrição. O root Consome o plugin como um cliente externo — via Maven. Exatamente como faria um projeto de terceiros. Se o plugin não for publicável, o root lhe diz imediatamente.</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="_comparação_as_três_arquiteturas_face_ao_dogfooding">Comparação: As Três Arquiteturas Face ao 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 isolado</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">Composto`includeBuild()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Raiz + plugin ind.</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`git clone && gradlew tasks`dá as tarefas do 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">[No output]</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">Construir plugin independente do 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 versões separado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(empty)</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">(No output, as no French text was provided for translation)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Não`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">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dogfood nativo sem config</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">Could you please provide the French text you would like translated?</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">plugin CI 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">O root é um exemplo 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">[No output]</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>A coluna da direita marca todas as caixas. É por isso que eu não Voltarei mais para trás</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_contrato_dag_um_build_racin_nunca_de_um_subdiretório">O Contrato DAG : Um Build Racin Nunca de um Subdiretório</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta arquitetura integra-se naturalmente no DAG N0→N3 do meu workspace. O padrão é : <strong>o plugin N2 é o hub de suas próprias dependências, a raiz N3 é um terminal que aplica *hubs</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/contrat-dag-architecture.svg" alt="contrat dag architecture" width="1751" height="5508"> </div> </div> <div class="paragraph"> <p>Le <code>codebase-gradle/build.gradle.kts`faz 6 linhas. Não`src/</code>, não`buildSrc/<code>, não`gradle/rag-bench.gradle.kts</code>. Justo <code>plugins { alias(libs.plugins.codebase) }`e os repositórios. Toda a complexidade vive em`codebase-plugin/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_a_duplicação_aparente_que_faz_ganhar_tempo">Conclusão: a duplicação aparente que faz ganhar tempo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando eu mostro esta estrutura a alguém, a primeira reação é frequentemente : « Mas tu tens dois`gradlew`, dois`settings.gradle.kts`, dois`libs.versions.toml`— é duplicação!</p> </div> <div class="paragraph"> <p>Sim. E não.</p> </div> <div class="paragraph"> <p>A « duplicação », é reproduzir a mesma informação em dois locais. Aqui, são dois arquivos <strong>distintos</strong> que servem dois usos <strong>distintos</strong> : o catálogo do plugin (30+ dependências para builder) e o catálogo da raiz (2-3 dependências para consumir). O wrapper do plugin (versão bloqueada para o desenvolvimento) e o wrapper da raiz (versão potencialmente diferente, para o exercício do plugin).</p> </div> <div class="paragraph"> <p>Não é duplicação. É de <strong>separação dos responsabilidades</strong> aplicada ao sistema de build. Cada build Faz uma coisa, e apenas uma. A raiz consome. O plugin se constrói.</p> </div> <div class="paragraph"> <p>O custo? Uma ordem`publishToMavenLocal`entre o build do plugin e o build da raiz. O ganho? Uma clareza arquitetural que elimina horas de depuração a jusante</p> </div> <div class="paragraph"> <p>Desde que eu implementei este padrão em`bakery-gradle`, <code>plantuml-gradle</code>, <code>codebase-gradle</code>, e os outros plugins de`foundry/public/<code>, não tenho nunca mais hesitei ao abrir um terminal em um dos meus repositórios. O primeiro reflexo —</code>./gradlew tasks`— anda sempre, dá sempre as boas tarefas, e me diz instantaneamente se tudo está sadio.</p> </div> <div class="paragraph"> <p>É isso, a boa arquitetura. Ela não se lê num README. Ela é testada em um terminal, em menos de dez segundos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Artigo 0105 — Integrar Graphify em um fluxo de trabalho Gradle</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Artigo 0117 — A Granularização OSS/CSS</a></p> </li> <li> <p><a href="0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html">Artigo 0123 — O Knowledge Graph como motor de recomendação</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="#_a_cena_terça_feira_12_de_maio_17h30">A Cena : Terça-feira, 12 de Maio, 17h30</a></li> <li><a href="#_o_diagnóstico_três_tipos_de_relações_que_nenhum_modelo_vê">O Diagnóstico : Três Tipos de Relações Que Nenhum Modelo Vê</a></li> <li><a href="#_a_solução_um_pipeline_gradle_não_uma_chamada_llm_a_quente">A Solução: Um Pipeline Gradle, Não uma chamada LLM a quente</a> <ul class="sectlevel2"> <li><a href="#_a_arquitetura_bakery_importa_graphify_não_engine">A Arquitetura: Bakery importa Graphify, não Engine</a></li> <li><a href="#_o_pipeline_scan_grafo_modelo">O Pipeline: Scan → Grafo → Modelo</a></li> <li><a href="#_fallback_cronológico">Fallback cronológico</a></li> </ul> </li> <li><a href="#_a_ontologia_emergente_quando_os_artigos_se_agrupam_sem_se_conhecer">A Ontologia Emergente: Quando os Artigos se Agrupam sem se Conhecer</a></li> <li><a href="#_o_contrato_dag_quem_importa_quem">O Contrato DAG: Quem Importa Quem</a></li> <li><a href="#_o_que_ganhamos_e_o_que_não_ganhamos">O Que Ganhamos (E O Que Não Ganhamos)</a></li> <li><a href="#_perspectivas_o_blog_como_knowledge_graph_público">Perspectivas: O Blog Como Knowledge Graph Público</a></li> <li><a href="#_conclusão_o_sistema_de_arquivos_sabe_o_que_o_modelo_ignora">Conclusão: O Sistema de Arquivos Sabe o Que o Modelo Ignora</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 14 minutes</div> <p>Você está lendo um artigo sobre a integração do pgvector com o LangChain4j. Na parte inferior da página, JBake Sugere-lhe « Artigos relacionados ». Você clica. É um artigo sobre…​ a configuração de Kitty Terminal. O único ponto em comum entre os dois? Eles foram publicados a menos de quinze dias de diferença. Não é uma recomendação. É um calendário disfarçado de editorial.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_terça_feira_12_de_maio_17h30">A Cena : Terça-feira, 12 de Maio, 17h30</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estou relendo um dos meus artigos — <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">aquele sobre o Knowledge Graph como ferramenta de compreensão de codebase</a> O conteúdo é denso: nós, arestas, comunidades, PlantUML, onboarding. Um artigo técnica de 15 minutos de leitura que mobiliza`graphify-gradle`, <code>plantuml-gradle</code>, e os conceitos de topologia de grafo.</p> </div> <div class="paragraph"> <p>Na parte inferior da página, os « Artigos relacionados » me sugerem :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Um artigo sobre Firebase Contact Form (0113)</p> </li> <li> <p>Um artigo sobre o mecanismo Eager/Lazy (0108)</p> </li> <li> <p>Um artigo sobre a migração de script Gradle → plugin (0102)</p> </li> <li> <p>Um artigo sobre o acúmulo de assinaturas Ollama Pro (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>Três desses quatro artigos não têm <strong>nenhuma</strong> relação com o Knowledge Graph. Eles estão lá porque são os últimos publicados — proximidade temporal, não vizinhança semântica</p> </div> <div class="paragraph"> <p>Estou olhando para o template`post.thyme`[No output]</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`é uma lista cronológica.`postStat.index lt 4`pega os Os quatro primeiros que não são o post atual. É isso. Nenhuma lógica. de similaridade. Nenhuma noção de conteúdo. Só um laço.`for`disfarçada de recomendação.</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>Não é um bug do JBake. É o comportamento padrão de tudo gerador de site estático : a lista de posts é plana e ordenada por data. O template faz o que pode com o que tem.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Mas isso não é um motivo para aceitá-lo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_diagnóstico_três_tipos_de_relações_que_nenhum_modelo_vê">O Diagnóstico : Três Tipos de Relações Que Nenhum Modelo Vê</h2> <div class="sectionbody"> <div class="paragraph"> <p>Meu corpus de artigos — 23 posts em 4 meses — tem uma estrutura rica que o modelo cronológico esmaga completamente :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Referências explícitas</strong>: eu uso`xref:`massivamente em meus artigos</p> </li> </ol> </div> <div class="paragraph"> <p>O artigo 0122 referência 0106 (knowledge graph) e 0116 (compartimentamento) epistemológico). Estes links são <strong>hard linking</strong> editorial — eu tenho Decidiu deliberadamente conectar esses conceitos.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Tags compartilhados</strong> : cada artigo tem alguns`:jbake-tags:`. O artigo sobre</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) tem`gradle, graphify, plantuml, knowledge-graph`. O artigo sobre o Knowledge Graph (0106) tem <code>knowledge-graph, graphify, plantuml</code>. Três tags em comum de sete — 43% de cobertura.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Entidades nomeadas co‑occurrentes</strong>: « pgvector », « RAG », « embedding</p> </li> </ol> </div> <div class="paragraph"> <p>aparecem juntos em quatro artigos diferentes. « LangChain4j », Ollama », « plugin Gradle » em outros seis. Não são tags declarados — são os <strong>padrões emergentes</strong> do corpus que apenas um NLP pode detectar.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/trois-couches-relation-articles.svg" alt="trois couches relation articles" width="1736" height="5492"> </div> </div> <div class="paragraph"> <p>Hoje, meu site não usa <strong>nenhuma</strong> dessas três camadas. Ele usa a camada zero: a ordem de inserção numa lista Java.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_um_pipeline_gradle_não_uma_chamada_llm_a_quente">A Solução: Um Pipeline Gradle, Não uma chamada LLM a quente</h2> <div class="sectionbody"> <div class="paragraph"> <p>A primeira tentação seria chamar um LLM no momento do bake : « Para Este artigo, encontra os três artigos mais semelhantes no corpus. Não faça isso</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>Uma chamada LLM para cada`./gradlew bake`custa tempo, dinheiro e introduz não-determinismo na sua construção. A resposta do LLM pode alternar entre duas builds sem que o conteúdo tenha sido alterado. Seu CI se torna não reproduzível, seus testes ficam instáveis.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>A solução é determinística: um pipeline Gradle que pré-calcula o grafo de similaridade e o armazena em`graph.json`. O modelo lê o resultado — Ele nunca desencadeia um cálculo.</p> </div> <div class="sect2"> <h3 id="_a_arquitetura_bakery_importa_graphify_não_engine">A Arquitetura: Bakery importa Graphify, não Engine</h3> <div class="paragraph"> <p>Este é o ponto de arquitetura mais importante. A tentação seria de cablear a colaboração em`engine/build.gradle.kts`: motor aplica graphify para o scan, bakery para o bake, e o engine faz a ponte entre os dois</p> </div> <div class="paragraph"> <p>É um anti-padrão. Engine é um <strong>terminal consumidor</strong> — ele aplica dos plugins, ele não implementa lógica de negócio. A regra é: <strong>A carga da prova está no plugin proprietário.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/bakery-import-graphify.svg" alt="bakery import graphify" width="1738" height="5700"> </div> <div class="title">Figure 1. Arquitetura correta — Bakery importa Graphify</div> </div> <div class="paragraph"> <p>O contrato DAG é respeitado: bakery (N2) importa graphify (N0), N2 > N0, nenhuma violação. Motor (N3) importa padaria (N2), N3 > N2, OK.</p> </div> <div class="paragraph"> <p>Engine não tem <strong>nenhuma</strong> linha de código que referencia`graph.json`, <code>relatedPosts</code>, ou qualquer outra noção de similaridade. Ele aplica bakery, ponto. a A colaboração é interna à padaria.</p> </div> </div> <div class="sect2"> <h3 id="_o_pipeline_scan_grafo_modelo">O Pipeline: Scan → Grafo → Modelo</h3> <div class="paragraph"> <p>Este é o pipeline completo em três etapas :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Scan</strong> (graphify) :`graphify-plugin`escaneia o workspace. No seu</p> </li> </ol> </div> <div class="paragraph"> <p>forma atual, ele já detecta os`xref:`entre`.adoc`e os expõe em`graph.json`como das edges de tipo`reference`.<br> Nós o enriquecemos para o conteúdo editorial: * Analisa os metadados do JBake (<code>:jbake-tags:</code>, <code>:jbake-description:</code>) de cada`.adoc`do blog * Calcula as co-ocorrências de tags → arestas`tag_cooccurrence`com peso * Extrai as entidades nomeadas das descrições via TF-IDF → edges`entity_overlap` * Injeta uma seção`blog_articles`no`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> (padaria) : no momento do`./gradlew bake`, `BakeryPlugin`cama</p> </li> </ol> </div> <div class="paragraph"> <p>`graph.json`e resolve os artigos relacionados para cada post.<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><strong>Template</strong> (<code>post.thyme</code>) : o modelo JBake agora recebe um mapa</p> </li> </ol> </div> <div class="paragraph"> <p>estruturada em vez de uma 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>O modelo é o mesmo — ele não sabe <strong>de onde</strong> vêm os dados. Só o contrato entre bakery e JBake mudou :`published_posts`(lista cronológico) torna-se`relatedPosts`(mapa ponderado pelo 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>O selo « razão » (ex:`xref 0122`, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) Explique ao leitor <strong>por que</strong> este artigo é relacionado. Isto não é justo de transparência — é pedagogia sobre a topologia de seu próprio conteúdo.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_fallback_cronológico">Fallback cronológico</h3> <div class="paragraph"> <p>Si <code>graph.json</code> está ausente (build local sem scan prévio, primeiro implantação, CI que ainda não integrou o scan graphify), o modelo deve degradar graciosamente :</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>O comportamento padrão é idêntico ao comportamento atual. O motor de recomendação é uma <strong>melhoria progressiva</strong> — não é alteração quebra</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_ontologia_emergente_quando_os_artigos_se_agrupam_sem_se_conhecer">A Ontologia Emergente: Quando os Artigos se Agrupam sem se Conhecer</h2> <div class="sectionbody"> <div class="paragraph"> <p>A camada mais interessante é a terceira: a ontologia emergente. Artigos que não são citados, que não têm as mesmas tags, mais que <strong>falam da mesma coisa</strong> sem saber.</p> </div> <div class="paragraph"> <p>Vamos considerar um exemplo concreto. Três artigos do meu corpus:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — Benchmark DGX Spark vs Cloud Assinatura LLM</p> </li> <li> <p>0121 — Plugin Gradle Pilotar Duas Instâncias Ollama Pro</p> </li> <li> <p>0122 — Razão Eficiência 27x 45x Frota Especialistas IA</p> </li> </ol> </div> <div class="paragraph"> <p>Estes três artigos não têm <strong>nenhum</strong> xref entre eles. As tags deles não se coincidem apenas em 20% (« ollama », « llm » comuns). Mas um NLP leve sobre as descrições revela um cluster evidente: « custo », « assinatura », nuvem », « GPU », « chave da API », « Ollama Pro », « eficiência », « razão</p> </div> <div class="paragraph"> <p>Eles formam um cluster ontológico : <strong>a economia do LLM self-hosted vs cloud</strong>. Este cluster não é declarado em nenhum lugar. Ele emerge do corpus.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cluster-ontologique-exemple.svg" alt="cluster ontologique exemple" width="697" height="405"> </div> </div> <div class="paragraph"> <p>Este cluster ontológico torna-se um edge composto em`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>O NLP é intencionalmente leve — TF-IDF + similaridade cosseno sobre os descrições. Não é necessário BERT, não é necessário modelo de linguagem. O corpus contém 23 artigos, a matriz de similaridade cabe em um arquivo JSON de 50 Ko.</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>O poder do NLP não vem da sofisticação do algoritmo, mais do <strong>tamanho do corpus</strong> e da <strong>qualidade das descrições</strong>. Uma `:jbake-description:`bem escrita de 150 caracteres contém mais de sinal para TF-IDF que um artigo inteiro de 3000 palavras.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_contrato_dag_quem_importa_quem">O Contrato DAG: Quem Importa Quem</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este é o ponto onde a disciplina arquitetônica paga. O DAG N0→N3 definido em`engine/build.gradle.kts`dá uma regra simples : nenhum projeto importa um projeto de nível 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">Nível do consumidor</th> <th class="tableblock halign-left valign-top">Nível 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, mas <strong>conceitualmente errado</strong> — a colaboração é interna à bakery</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Motor aplica padaria. Padaria aplica graphify. É tudo. Se um dia Eu quero adicionar o codebase do vector store (N1) para pesquisa. semântica cross-corpus, bakery também o importa. Engine não muda.</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>O padrão é : <strong>o plugin N2 é o hub de suas próprias dependências</strong> Engine N3 não é um hub — é um terminal que aplica hubs.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_ganhamos_e_o_que_não_ganhamos">O Que Ganhamos (E O Que Não Ganhamos)</h2> <div class="sectionbody"> <div class="paragraph"> <p>O ganho principal é editorial, não técnico :</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">Depois</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Artigos relacionados = últimos 4 posts</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Artigos relacionados = top 4 por peso no Knowledge Graph</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Lecteur lê do RAG → recomendação Kitty Terminal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Leitor lê do RAG → recomendação pgvector, chunking, vector store</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero transparência sobre o porquê</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">crachá`xref 0122`, <code>tag:gradle</code>, `cluster:rag`visível</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake padrão, zero esforço, zero valor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pipeline Gradle determinístico, reprodutível, testável</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma curva de aprendizagem para o leitor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O leitor descobre a <strong>topologie</strong> do meu conteúdo</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O que <strong>não</strong> se ganha :</p> </div> <div class="ulist"> <ul> <li> <p>Não é um « verdadeiro » motor de recomendação (sem colaborativo</p> </li> </ul> </div> <div class="paragraph"> <p>filtragem, sem teste A/B, sem loop de feedback)</p> </div> <div class="ulist"> <ul> <li> <p>A qualidade depende da riqueza dos metadados JBake — se seus</p> </li> </ul> </div> <div class="paragraph"> <p>as descrições estão vazias, TF-IDF não vê nada</p> </div> <div class="ulist"> <ul> <li> <p>Le NLP est offline — les nouveaux articles ne sont clusterisés qu’au</p> </li> </ul> </div> <div class="paragraph"> <p>próxima varredura (isso está bom: o build permanece determinístico)</p> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_o_blog_como_knowledge_graph_público">Perspectivas: O Blog Como Knowledge Graph Público</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta funcionalidade abre uma perspectiva mais ampla: e se`cheroliv.com` estava se tornando ele mesmo um <strong>knowledge graph navigável</strong>?</p> </div> <div class="paragraph"> <p>Os artigos são nós. As tags são comunidades. Os xref são as arestas. O leitor não lê mais um artigo isolado — ele navega em um <strong>grafo de conhecimento</strong> do qual o artigo corrente é o ponto de entrada.</p> </div> <div class="paragraph"> <p>Imagine uma página inicial que exibe não a lista cronológica dos últimos posts, mas um <strong>mapa do corpus</strong> : clusters ontológicos, artigos pivô (aqueles com o maior número de arestas), caminhos de leitura recomendados (« Se você gostou do artigo sobre Graphify, leia em seguida aquele sobre o Knowledge Graph como ferramenta de compreensão «)</p> </div> <div class="paragraph"> <p>Não é mais um blog. É um <strong>atlas semântico</strong>.</p> </div> <div class="paragraph"> <p>E isso não é ficção científica. O`graph.json`já existe. Só lhe falta a interface de navegação.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_sistema_de_arquivos_sabe_o_que_o_modelo_ignora">Conclusão: O Sistema de Arquivos Sabe o Que o Modelo Ignora</h2> <div class="sectionbody"> <div class="paragraph"> <p>O que eu projetei na terça-feira à noite é a substituição de uma heurística preguiçosa (a ordem cronológica) por uma representação fiel da estrutura do meu corpus (o Knowledge Graph)</p> </div> <div class="paragraph"> <p>O modelo`post.thyme`não muda. O que muda, é o que a gente Antes: uma lista Java ordenada por`date`. Depois : um grafo ponderado proveniente de três camadas de análise — xrefs, co-ocorrências de tags, e ontologia emergente por NLP.</p> </div> <div class="paragraph"> <p>O laço está fechado. graphify escaneia o workspace. Bakery lê o gráfico e alimenta o modelo. O leitor vê recomendações. pertinentes. E o motor — o maestro — nem sabe que Tudo isso existe.</p> </div> <div class="paragraph"> <p>É isso, a boa arquitetura. Cada plugin faz uma coisa. E o terminal do consumidor não precisa saber como.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Artigo 0105 — Integrar o Graphify em um workflow Gradle</a></p> </li> <li> <p><a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Artigo 0106 — O Knowledge Graph como ferramenta de compreensão</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Artigo 0117 — A Granularização OSS/CSS</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Artigo 0121 — Plugin Gradle para Pilotar Duas Instâncias Ollama Pro</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Artigo 0122 — 27× a 45× mais eficaz : frota de especialistas em 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="#_o_problema_por_que_fine_tune_e_não_rag">O problema: por que fine-tune e não RAG?</a></li> <li><a href="#_a_ideia_uma_frota_de_especialistas_não_um_único_modelo">A ideia: uma frota de especialistas, não um único modelo.</a></li> <li><a href="#_o_código_base_sob_a_lupa_7_900_arquivos_144_000_linhas">O código base sob a lupa : 7 900 arquivos, 144 000 linhas</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura: 22 minutes</div> <p>Quando se usa um LLM para desenvolvimento de software no dia a dia, acabamos sempre batendo na mesma parede: o modelo não conhece <strong>seu</strong> código‑base. Ele não sabe que você usa esse padrão dehttps://fr.wikipedia.org/wiki/Graphe_orient%C3%A9_acyclique[DAG], tal convenção Gradle, tal estratificação epistêmica em seushttps://fr.wikipedia.org/wiki/AsciiDoc[.adoc]. Então se injeta contexto nele, repete-se, corrige-se, itera-se. E o tempo — e o dinheiro — passam.</p> </div> <div class="paragraph"> <p>Portanto, eu coloquei a pergunta brutalmente: quanto custaria uma equipe de modelos fine-tunados no meu workspace, capazes de cuspir código <strong>no meu estilo</strong> sem precisar explicar a cada vez? E, principalmente: como essa abordagem se compara às soluções proprietárias clássicas — Claude, GPT, Gemini, Grok?</p> </div> <div class="paragraph"> <p>A resposta me surpreendeu. Muito menos do que eu imaginava. E o relação custo/eficácia frente aos gigantes do setor é indecente. Eis o detalhe completo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_por_que_fine_tune_e_não_rag">O problema: por que fine-tune e não RAG?</h2> <div class="sectionbody"> <div class="paragraph"> <p>O RAG, é bom. <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Meu knowledge graph</a> e <a href="0116_compartimentage_epistemique_automatise_llm_post.html">meu compartimentamento epistêmico</a> funcionam. Mas o RAG tem um defeito fundamental: para cada consulta, você precisa reinserir o contexto relevante. Seu prompt fica mais longo, sua latência explode, e o modelo nunca <strong>intériorise</strong> teus padrões — ele os lê a cada vez como um documento externo.</p> </div> <div class="paragraph"> <p>O fine-tune, ele, é a memória muscular. O modelo <strong>sabe</strong> que tu escreves`build.gradle.kts`com tarefas registradas via`tasks.register`, que teus`AGENTS.adoc`que seguem uma sintaxe padronizada, que o teu workspace está estruturado em boroughs. Ele não precisa que o lembrrem.</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>O ajuste fino não é um substituto do RAG. É uma camada complementar. O RAG permanece relevante para os dados que mudam frequentemente (logs, tickets, commits recentes). O ajuste fino é para o conhecimento <strong>estrutural</strong> e <strong>estilístico</strong> de longo prazo.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_a_ideia_uma_frota_de_especialistas_não_um_único_modelo">A ideia: uma frota de especialistas, não um único modelo.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Um único modelo fine-tunado em todo o meu workspace, já é bom. Mas isso é subótimo. Meu workspace cobre áreas muito diferentes:</p> </div> <div class="ulist"> <ul> <li> <p>Plugins do Gradle (Kotlin, plugins de convenção, builds compostos)</p> </li> <li> <p>Motor DAG (Kotlin, planejamento, execução)</p> </li> <li> <p>Agentes LLM (Python, LangChain4j, RAG)</p> </li> <li> <p>Documentação arquitetônica (AsciiDoc, governança)</p> </li> <li> <p>Infra/DevOps (Docker, GitHub Actions, CI/CD)</p> </li> </ul> </div> <div class="paragraph"> <p>Um modelo único deveria ser bom por toda parte, excelente em nenhum lugar. A solução? Uma<strong>frota de modelos especializados</strong>, com um orquestrador que roteia cada consulta para o especialista certo.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 13 package "Ollama Cloud" { rectangle "DeepSeek V4-Pro\n1.6T / 49B ativos" as V4Pro #FF6B6B rectangle "6× V4-Flash-FT 292B / 13B ativos" as Flash #4ECDC4 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FAFAFA skinparam defaultFontSize 13 package "Ollama Cloud" { rectangle "DeepSeek V4-Pro\n1.6T / 49B ativos" as V4Pro #FF6B6B rectangle "6× V4-Flash-FT 292B / 13B ativos" as Flash #4ECDC4 rectangle "6× Gemma4 26B-FT\n26B / 3.8B ativos" as Gemma #FFE66D rectangle "5× Qwen3.6 35B-FT 35B / 3B ativos" as Qwen36 #A8E6CF rectangle "5× Qwen3.5 35B-FT\n35B / 3B ativos" 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 : "tarefa Gradle complexa" V4Pro --> Gemma : "formatação AsciiDoc" V4Pro --> Qwen36 : "refatoração 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>A frota total:<strong>1 orquestrador + 22 especialistas = 23 modelos</strong>. E o custo mensal de inferência?<strong>17€/mês</strong>em assinatura Ollama Pro anual — extensível por acumulação de contas se as cotas forem excedidas, como demonstrado em <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">meu método Docker multi-contas</a>. Começamos em 17€, acrescentamos 20€ por patamar conforme a necessidade real. Sem desperdício.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_código_base_sob_a_lupa_7_900_arquivos_144_000_linhas">O código base sob a lupa : 7 900 arquivos, 144 000 linhas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de estimar o custo do training, é preciso saber o que treinar. Auditei meu workspace excluindo rigorosamente tudo o que é ignorado pelo Git :</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/ ---- Segue o resultado para os arquivos rastreados apenas: [cols="2,2"] |=== |Métrica |Valor |Arquivos de origem rastreados |**7 896** |Linhas de código (LOC) |**143 805** |repositórios Git |**26** |Principais linguagens |Kotlin (1 903), AsciiDoc (2 765), Python (5 029) |=== [IMPORTANT] ==== Estes 5 000+ arquivos Python incluem os`runtimes/`algunos notebooks e scripts utilitários. O núcleo aplicativo (plugins Gradle, motor DAG, agents) é principalmente em Kotlin e AsciiDoc. ==== A partir dessa massa, estimo poder gerar um dataset sintético de**~170 milhões de tokens**via um LLM instrutor(distilação da codebase em pares instrução/resposta). === Detalhe do conjunto de dados por tipo de especialista [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 ---- == A escolha dos modelos: 100% MoE, zero denso É lá que a arquitetura se torna realmente eficiente. Um modelo *dense* ativa todos os seus pesos a cada token. Um modelo *MoE* (Mixture of Experts) ativa apenas uma fração de seus parâmetros. O custo de inferência — e de fine-tuning — é proporcional aos parâmetros**ativados**, não aos parâmetros**estoqueados**. Vejamos o que o mercado oferece em MoE hoje no Ollama Cloud: [cols="3,2,2,1,3"] |=== |Modelo |Total parâmetros |Ativados |Ativação |Ollama Cloud |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% |�❌ (ainda não 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 validação |=== [CAUTION] ==== A relação de ativação é o critério discriminante. Um Gemma 4 26B-A4B ativa apenas 3,8B de seus 26B de parâmetros — é 7× menos que um denso 27B, para um desempenho de agente de codificação comparável (77,1% vs 80% no LiveCodeBench v6). ==== === Por que estou abandonando os modelos densos A exceção : os Gemma 4 E2B e E4B. Estes dois modelos, sob Apache 2.0, são perfeitos para testar e validar um pipeline de treinamento a menor custo. Uma execução de 2-3h em um E2B custa menos de $5 — se o conjunto de dados ou os hiperparâmetros forem problemáticos, descobrimos por alguns dólares. Uma vez que o pipeline esteja pronto, eles podem até ser usados para tarefas ultra-micro (reformatagem trivial, classificação binária). Mas para os especialistas da frota principal, eu continuo com o MoE. Eis por que : .Mas não apenas: os Gemma 4 E2B/E4B, especialistas em anonimização fina [NOTE] ==== Google projetou esses pequenos modelos como competitivos em tool calling nativo — eles sabem chamar funções, manipular regex, procurar padrões. Depois de fine-tunados em exemplos de anonimização (e‑mails, tokens, UUIDs, caminhos de arquivos), eles se tornam**anonimizadores de dataset**ultra-rapides. Nós damos-lhes um bloco de texto bruto, eles chamam`sed`/`regex`via uma chamada de ferramenta e retornam o bloco limpo. O custo de inferência é irrisório: 5B ativados, cabe em uma única GPU de entrada. Esses modelos não são especialistas de domínio — são**operários especializados**na cadeia de produção do conjunto de dados ==== * Sua VRAM de treinamento (mesmo em QLoRA) é proporcional aos**27B totais** * O seu tempo de treinamento é proporcional aos**27B ativados** Compare com um Qwen3.6-35B-A3B (MoE): [cols="3,2,2,2"] |=== | |Qwen3.5-27B (dense) |Qwen3.6-35B-A3B (MoE) |Razão |VRAM QLoRA |~55 GB |~35 GB |1.6× |GPU-horas (8M tok) |~12h |~4h |**3×** |Custo por fine-tune |~$24 |~$8 |**3 vezes** |SWE-bench Verificado |75.0% |73.4% |comparável |=== O MoE custa 3× menos para treinar para desempenho de agente-codificação com precisão de 5%. Em 22 especialistas, a diferença corresponde a milhares de euros. == Estimativa do treinamento: 811 H100-horas Dividi o custo de treinamento modelo por modelo, em QLoRA 4-bit, com os datasets descritos acima. === Micro-especialistas MoE leves (3-3.8B ativados) Estes modelos exigem 1 H100 (80 GB) por execução. A VRAM do modelo em Q4 é de aproximadamente 13-18 GB, deixando amplo espaço para os estados do otimizador LoRA e as ativações. [cols="4,2,3,2"] |=== |Modelo |Número de runs |GPU-h/run |Total GPU-h |Gemma 4 26B-A4B-FT |6 |3.5 h |**21h** |Qwen3.6-35B-A3B-FT |5 |4.0 h |**20h** |Qwen3.5-35B-A3B-FT |5 |4.0 h |**20 horas** |*subtotal micro* | | |*61 h* |=== === Executivos V4-Flash (13B ativados / 292B armazenados) O DeepSeek V4-Flash é um caso particular. Mesmo que apenas 13B sejam ativados por token, o modelo completo em Q4 pesa ~142 GB — todos os especialistas devem estar na VRAM durante o treinamento. É preciso, portanto**3× H100**por run para ficar confortável. [cols="4,2,3,3,2"] |=== |Modelo |conjunto de dados |GPUs |Horas |Total GPU-h |V4-Flash-Base generalista |50M tok |3× H100 |50 h |**150 h** |V4-Flash especialista ×5 |15M tokens |3× H100 |40 h |**600 h** |*Subtotal executivos* | | | |*750 h* |=== [cols="3,2,1"] |=== |**TOTAL** | |**811 H100-h** |=== [NOTE] ==== Para comparação, um fine‑tune completo do V4‑Flash (sem QLoRA, todos os pesos) custaria ~4 000 H100‑h apenas para os 6 modelos. O QLoRA reduz o custo por um fator de 5. É a única maneira de tornar o projeto economicamente viável nessa escala. ==== === Tarifas GPU: quem aluga o quê em maio de 2026 Eu fiz benchmark dos principais locatários de H100. O preço medido, para 811 horas. [cols="3,2,2,2"] |=== |Locador |$/H100·h |Total 811h |Fiabilidade |**Vast.ai spot** |$1.60 |**$1 298** |★★☆ interruptível |**Crusoe Cloud** |$2.00 |**$1 622** |★★★★ datacenter fiável |FluidStack |$1.98 |$1 606 |★★★ |TensorDock |$1.80 |$1 460 |★★☆ |RunPod |$2.29 |$1 857 |★★★ bom compromisso |CoreWeave |$2.25 |$1 825 |★★★★ empresa |Lambda Labs |$2.49 |$2 019 |premium |=== [TIP] ==== Vast.ai spot é o mais barato mas teus runs podem ser interrompidos a qualquer momento. Para training, é arriscado. Crusoe a $2,00/h é a melhor relação confiabilidade/preço. O acréscimo de $324 vs Vast vale a tranquilidade de espírito. ==== === Wall-clock: quanto tempo para treinar tudo? Com apenas um nó 3× H100, as 31 execuções (1 generalista + 30 especialistas) levam aproximadamente**12 dias**em sequencial. Se você aluga 2 nós em paralelo, cai para**6 dias**. Na prática, os micro-especialistas podem rodar em nós separados (1 H100 cada) enquanto os V4-Flash ocupam o nó 3× H100. Com um planejamento 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 dias de aluguel, tudo dobrado. == A inferência: 23 modelos na Ollama Cloud a partir de 17€/mês É a parte mais elegante da arquitetura. Ollama Cloud permite fazer upload de modelos privados (funcionalidade do plano Pro). Meus 22 modelos fine-tuned são enviados para`.gguf`no meu espaço Ollama, marcados como privados, e acessíveis via a API padrão. [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 ---- === Começamos a 17€/mês, escalamos se necessário O plano Pro Ollama (17€/mês anual) autoriza 3 modelos de nuvem concorrentes. Nesta arquitetura, nunca preciso de mais de 2-3 especialistas simultaneamente: * A fase de classificação (V4-Pro) ocupa 1 slot, alguns segundos * O especialista direcionado ocupa 1 slot, o tempo de gerar sua resposta * O 3º slot permanece em reserva para as tarefas paralelas Se o uso aumentar, eu adiciono contas Pro adicionais por meio do método Docker descrito em xref:0120_cumuler_deux_abonnements_ollama_pro_docker_post.adoc[meu artigo sobre o acúmulo de assinaturas]. Nenhum plano Max a 100€/mês — eu adiciono apenas o que realmente preciso. O único fator limitante é o**cota de tempo de GPU**mensal do Ollama (50× o plano gratuito para Pro). Para meu uso de algumas centenas de consultas por dia, isso é mais do que suficiente. [IMPORTANT] ==== O custo marginal de uma chamada ao V4-Pro (49B ativados) contra Gemma 4 26B-A4B (3.8B ativados) é o**mesmo para mim: zero**. O plano Ollama absorve a diferença de compute. O meu único indicador é a latência. ==== === O roteamento na prática</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>A maior parte do tráfego passa pelos pequenos. O modelo grande intervém apenas como último recurso. == A comparação que dói : Claude, GPT, Gemini, Grok vs minha frota É aqui que a diferença se torna vertiginosa. Vamos ver o que custaria o mesmo volume de trabalho (500 requisições/dia, ~300 tokens de entrada + 2 000 tokens de saída em média) com as soluções proprietárias do mercado em maio de 2026. === Anthropic — Claude (tarifas maio 2026) Anthropic recentemente *baixou* seus preços. A pressão das soluções open-weight como DeepSeek e Qwen está se fazendo sentir. [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Saída $/MTok |Custo/dia |**Custo/mês** |Opus 4.7 (o mais inteligente) |$5 |$25 |$25.75 |**$772** |Sonnet 4.6 (equilibrado) |$3 |$15 |$15.45 |**$463** |Haiku 4.5 (o + rápido) |$1 |$5 |$5.15 |**$154** |=== [CAUTION] ==== Estas tarifas são *depois* da última redução de preço da Anthropic (maio de 2026). Antes disso, Opus estava a $15/$75 por MTok. O medo do open-weight é real. ==== Mesmo o modelo mais barato do Claude — Haiku 4.5 a**154€/mês**— custa 9× mais que minha assinatura Ollama Pro de 17€. E Haiku não conhece minha codebase, não gera no meu estilo e requer engenharia de prompt sistemática. O mais inteligente — Opus 4.7 — estoura o orçamento em**772€/mês**um volume modesto de 500 requisições por dia. Seja**45 vezes mais caro**que a minha solução. === OpenAI — GPT (tarifas maio 2026) [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Output $/MTok |Custo/dia |**Custo/mês** |GPT 5.5 (o mais inteligente) |$5 |$30 |$30.90 |**$927** |GPT 5.4 (standard) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 Mini |$0.75 |$4.50 |$4.64 |**$139** |=== Mesmo o modelo « econômico » da OpenAI — GPT 5.4 Mini a 139€/mês — custa 8× minha assinatura, para um modelo que não sabe *nada* das minhas convenções e requer um prompt engineering pesado. GPT 5.5, seu flagship:**927€/mês**. Para *zero-shot* na minha base de código. Com 2-3 iterações por tarefa devido ao estilo não dominado, o custo mensal real dobra facilmente. === Google — Gemini (tarifas maio 2026) [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Saída $/MTok |Custo/dia |**Custo/mês** |Gemini 3.1 Pro (Alto) |$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 a 46€/mês é competitivo em preço puro — mas sem fine-tune, ele gera código « genérico ». Não é código *Cheroliv*. === Grok — xAI (tarifas maio 2026) [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |Saída $/MTok |Custo/dia |**Custo/mês** |Grok 4 |$4 |$16 |$16.48 |**$494** |Grok 4 Mini |$0.80 |$3.20 |$3.30 |**$99** |=== === Microsoft — Azure OpenAI (preços maio de 2026) Azure aplica os mesmos preços que a API OpenAI direta, mas cobra adicionalmente a infraestrutura e a rede. É necessário considerar um acréscimo de 10-20% para o serviço gerenciado. [cols="3,2,2,2,2"] |=== |Modelo |$/MTok |$/MTok |Custo/dia |**Custo/mês** |GPT 5.4 (Azure, Global) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 + infraestrutura |acréscimo de 15% |acréscimo de 15% |$17.77 |**$533** |=== [NOTE] ==== As tarifas acima referem-se à API, não aos planos « chat » (Claude Pro a $20/mês, ChatGPT Plus a $20/mês). Comparamos aqui o uso *desenvolvedor*, aquele em que você encadeia centenas de solicitações por dia via API para gerar, refatorar, documentar. Os planos para o público geral têm cotas que explodem muito antes de 500 solicitações/dia. ==== === A tabela comparativa final [cols="3,2,2,2,2,2"] |=== |Solução |Conhecimento codebase |Estilo integrado |Custo/mês |iterações |**Custo efetivo** |**Minha frota (Ollama Pro)** |�✅ Afinada |✅ Nos pesos |**17€** |0-1 |**17€** |Claude Opus 4.7 |❌ Zero-shot |�❌ Prompt necessário |$772 |2-3 |$1 500-2 300 |Claude Haiku 4.5 |�❌ Zero-shot |�❌ Prompt necessário |$154 |3-4 |$460-615 |GPT 5.5 |❌ Zero-shot |❌ Prompt necessário |$927 |2-3 |$1 854-2 781 |GPT 5.4 |�❌ Zero-shot |�❌ Prompt necessário |$463 |2-3 |$925-1 390 |GPT 5.4 Mini |❌ Zero-shot |❌ Prompt necessário |$139 |3-5 |$417-695 |Gemini 3.1 Pro High |❌ Zero-shot |Prompt necessário |$540 |2-3 |$1 080-1 620 |Grok 4 |�❌ Zero-shot |�❌ Prompt necessário |$494 |2-3 |$988-1 482 |**Azure GPT 5.4** |�❌ Zero-shot |❌ Prompt necessário |$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 Relação custo/eficácia — minha frota vs o mercado (maio 2026) rectangle "17€/mês" as OURS #4ECDC4 rectangle "Opus 4.7 772€" as OPUS #FF6B6B rectangle "Soneto 4.6 463€" 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€/mês para 23 especialistas de IA afinados. O flagship Claude Opus 4.7 custa**45× mais caro**para uma qualidade inferior no *meu* codebase. GPT 5.5 custa**54× mais caro**. Mesmo o modelo mais barato do mercado (Gemini Flash por 46€) custa**2.7× mais**sem o conhecimento do meu workspace. O veredicto é irrecorrível: o fine-tune em arquiteturas MoE, em 2026, não é apenas « mais barato ». É um fator de eficiência de**27× a 54×**sobre a relação custo/qualidade em face das soluções proprietárias. Anthropic, OpenAI, Google — todos sabem, e é por isso que eles estão baixando seus preços em pânico. == O fator de eficiência: 5-8× vs usar V4-Pro sozinho Comparemos os dois extremos. === Cenário A: V4-Pro apenas para tudo [cols="3,2"] |=== |Métrica |Valor |Conhecimento do codebase |0 (zero-shot) |Convenção de nomenclatura |40-60% de acerto na primeira tentativa |Prompt engineering necessário |Sim, sistemático |iterações por tarefa |2-3 |Custo inferência |$100/mês (Ollama Max) |Latência média |~20 tok/s + rede |=== === Cenário B : Frota MoE orquestrada [cols="3,2"] |=== |Métrica |Valor |Conhecimento da base de código |Integrada (fine-tune) |Convenção de nomeação |90-95% corretos de primeira |engenharia de prompts |Não (o estilo está nos pesos) |Iterações por tarefa |0-1 |Custo inferência |$60/mês (3× Ollama Pro) |Latência média |~50 tok/s (modelos leves) |=== [cols="4,2,2,2"] |=== |Dimensão |V4-Pro apenas |Frota MoE |Fator |Custo mensal da nuvem |$100 |**$60** |1.7× |Contexto a injetar |Elevado (prompt) |**Zero** |∞ |iterações médias |2-3 |**0-1** |2-3× |Latência percebida |20 tok/s |50 tok/s |**2.5×** |primeiro disparo correto |50% |90%+ |**1.8×** |=== **Fator de eficiência global : 5-8×**— produtividade do desenvolvedor sentida. [NOTE] ==== O fator não se mede em tokens ou em dólares. Ele se mede em « quanto tempo eu gasto para explicar ao modelo o que ele já deveria saber ». Com os modelos fine-tunados, esse tempo tende a zero. ==== == O orçamento completo: um investimento one-shot, um pacote ridículo [cols="3,2"] |=== |posto |Montante |Treinamento GPU (811 H100-h, Crusoe $2/h) |**$1 622** |Geração de conjunto de dados sintético (API LLM) |**$400** |Inference (Ollama Pro anual, $17/mês) |**$204** |**Total primeiro ano** |**$2 226** |**Equivalente mensal** |**$186** |**Custo por consulta estimado** |< $0.01 |=== [plantuml, budget-breakdown, svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FAFAFA</p> </div> <div class="paragraph"> <p>rectangle "Orçamento Ano 1 : $2 226" as Total #E8E8E8 { rectangle "Treinamento GPU $1 622 (73%)" as Train #FF6B6B rectangle "Conjunto de dados destilação $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/mês o primeiro ano,**$17/mês**desde o ano 2. O preço de uma assinatura Netflix premium, para uma equipe de 23 especialistas em IA disponíveis 24/7, que escrevem código *no meu estilo* sem que eu precise explicar minhas convenções a eles. === O cálculo de rentabilidade Com o edster.cloud e sua margem de ~95%, o ponto de equilíbrio está em**~$2 340 de CA adicional**no ano. Na prática : * 1 missão de pilotagem de software → $3 000-5 000 → investimento coberto + lucro * 1 formação corporativa → $5 000-10 000 → confortável * Upsell implícito : "minha equipe de IA domina minha forja de software" → diferencial comercial A partir do ano 2, o treinamento não precisa mais ser pago (exceto atualização do conjunto de dados). O custo anual cai para**$204**($17/mês). A relação custo/valor é a de um unicórnio: quase nula. == Os limites do exercício Isso continua uma *estimativa no dedo molhado*. Várias variáveis podem mudar o orçamento: [cols="2,3"] |=== |Variável |Impacto |Geração do dataset sintético |Se a API de distillation merda (alucinações, pares mal formados), é necessário tempo humano para curar. Custo oculto. |Cotas GPU-time Ollama |Se o uso ultrapassar as quotas do plano Pro, será necessário fazer upgrade ou mudar para uma GPU dedicada. |Qualidade efetiva dos fine-tunes |Um fine-tune mal-sucedido → a refazer. O verdadeiro risco são os hiperparâmetros, não o aluguel da GPU. |Evolução rápida dos modelos |Qwen3.6/Gemma 4 foram lançados há < 1 mês. Daqui a 6 meses, a próxima geração será melhor E mais barata para fazer fine-tuning. |=== [WARNING] ==== Não inicie 811 horas de treinamento sem primeiro testar o pipeline em *um único* micro-modelo. Uma execução de 3-4h em um Qwen 35B-A3B custa $8. Se o dataset estiver corrompido, você vai saber por $8, não por $1 622. ==== == Conclusão: o fine-tune tornou-se um luxo acessível Há um ano, fazer o fine-tuning de um modelo de 292B parâmetros (mesmo em QLoRA) era uma questão de pesquisa. Hoje, em maio de 2026, é um projeto viável para um desenvolvedor independente: * **811 H100-horas**de treinamento — $1 622 na Crusoe * **23 modelos especializados**carregados na Ollama Cloud —**$17/mês** * **0 servidor, 0 GPU local, 0 manutenção infra** A democratização veio de três fatores convergentes: 1. **As arquiteturas MoE**que permitem ajustar eficientemente modelos dos quais apenas uma fração dos pesos é ativada 2. **Os planos fixos do Ollama Cloud**— que transformam um custo variável (por token) em custo fixo (assinatura) 3. **Modelos open-weight de qualidade**— DeepSeek V4, Qwen3.6, Gemma 4 estão sob licenças MIT/Apache 2.0 A civilização avança estendendo o número de operações importantes que podemos realizar sem pensar sobre elas. O fine-tune, é exatamente isso: uma operação que delegas à máquina para não precisares mais pensar nisso. E em 2026, custa menos do que um desenvolvedor júnior mensalizado. --- _Artigo publicado em {jbake-date}_ == Modelos fine-tuned da frota [cols="2,2,2,2,3"] |=== |Tamanho ativado |número |Modelo base |Domínio |Conjunto de dados |13B |1 |DeepSeek-V4-Flash-Base |Espaço de trabalho geral |50M tokens |13B |5 |DeepSeek-V4-Flash |Gradle, Kotlin, DAG, Doc, Infra |15 milhões de tokens |3.8B |6 |Gemma 4 26B-A4B |Micro-tarefas, formatação, scripts |5M tokens |3B |5 |Qwen3.6-35B-A3B |Refatoração, revisão, doc intermediária |5M tokens |3B |5 |Qwen3.5-35B-A3B |Tarefas legadas, compatibilidade |5 milhões de tokens |=== == Recursos === Modelos open-weight no HuggingFace * https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Base[DeepSeek V4-Flash-Base — 292B parâmetros, licença MIT] * https://huggingface.co/Qwen/Qwen3.6-35B-A3B[Qwen3.6-35B-A3B — 35B/3B ativados, licença Apache 2.0] * https://huggingface.co/Qwen/Qwen3.5-35B-A3B[Qwen3.5-35B-A3B — 35B/3B ativados, licença Apache 2.0] * https://huggingface.co/google/gemma-4-26B-A4B-it[Gemma 4 26B-A4B — 26B/3.8B ativados, licença Apache 2.0] === Fontes das tarifas (maio de 2026) * https://ollama.com/pricing[Preços Ollama Cloud — plano Pro $17/mês 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 — GPT API (GPT 5.5 $5/$30, GPT 5.4 $2.50/$15)] * https://deepinfra.com/pricing[Tarifas DeepInfra — instâncias GPU H100 $1.79/h, B200 $2.79/h] * Vast.ai, Crusoe Cloud, FluidStack, TensorDock, RunPod, CoreWeave, Lambda Labs — levantamentos de preços manuais, datados de maio de 2026 === Anúncios oficiais * https://qwen.ai/blog?id=qwen3.6-35b-a3b[Anúncio oficial Qwen3.6-35B-A3B — blog Qwen]— agentic coding, Apache 2.0, 262K context</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="#_introdução">Introdução</a></li> <li><a href="#_por_que_gradle_para_da_infra">Por que Gradle para da Infra ?</a></li> <li><a href="#_o_build_gradle_kts_completo">O build.gradle.kts completo</a></li> <li><a href="#_anatomia_das_tarefas_chave">Anatomia das Tarefas Chave</a> <ul class="sectlevel2"> <li><a href="#_startollamab_o_lançador">startOllamaB` — O Lançador</a></li> <li><a href="#_signinb_o_interativo">signInB` — O Interativo</a></li> <li><a href="#_pullmodelb_o_configurável">pullModelB` — O configurável</a></li> <li><a href="#_statusollamaall_o_diagnóstico">statusOllamaAll` — O Diagnóstico</a></li> <li><a href="#_cleanollamab_a_limpeza_que_preserva_a_identidade">cleanOllamaB` — A limpeza que preserva a identidade</a></li> </ul> </li> <li><a href="#_workflow_completo_de_zero_a_duas_sessões">Workflow Completo — De Zero a Duas Sessões</a></li> <li><a href="#_por_que_não_transformá_lo_em_um_plugin_gradle_real">Por que não transformá-lo em um plugin Gradle real?</a></li> <li><a href="#_lições_aprendidas">Lições Aprendidas</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 18 minutes</div> <p>Por que digitar comandos Docker manualmente quando podemos encapsular tudo em tarefas Gradle? Aqui está como eu industrializei minha configuração dual-Ollama Pro com zero script shell externo. Inicialização, parada, identidade, sign-in, pull — tudo passa por`./gradlew`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>No artigo anterior, eu mostrei como fazer com que duas contas Ollama Pro coexistam na mesma máquina isolando a segunda instância em um contêiner Docker. A configuração funciona, mas a gestão diária torna-se rapidamente cansativa: lembrar o nome do contêiner, executar novamente os comandos corretos`docker exec`, verificar qual porta está ativa…​</p> </div> <div class="paragraph"> <p>Você conhece esse momento em que você tem 14 terminais abertos, que você digita`docker exec ollama-instance-b ollama list`para a quarta vez, e você pensa « deve haver um jeito mais limpo »?</p> </div> <div class="paragraph"> <p>Este método é o Gradle.</p> </div> <div class="paragraph"> <p>Não apenas para construir código. Gradle como um maestro da infraestrutura local. Tarefas que provisionam, verificam, testam e limpam. Tudo versionado em um`build.gradle.kts`que vive ao lado do`docker-compose.yml`.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-gradle-ollama.svg" alt="architecture gradle ollama" width="729" height="516"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_gradle_para_da_infra">Por que Gradle para da Infra ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>A pergunta é legítima. Gradle, é uma ferramenta de build. Normalmente, ele compila, ele testa, ele empacota. Ele não lança contêineres Docker.</p> </div> <div class="paragraph"> <p>Exceto que o Gradle também é um motor de grafo de dependências — e é aí que isso se torna interessante para o nosso caso.</p> </div> <div class="paragraph"> <p>Queremos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Que o contêiner seja iniciado antes de um sign-in</p> </li> <li> <p>Que a identidade seja verificada antes de um pull de modelo</p> </li> <li> <p>Que um teste de API falhe silenciosamente se o contêiner estiver fora do ar.</p> </li> </ol> </div> <div class="paragraph"> <p>Do grafo de dependências puro. Gradle é feito para isso. O DSL Kotlin torna a escrita das tarefas fluida, e o`doLast`permite executar comandos do sistema como se fossem código de aplicação.</p> </div> <div class="paragraph"> <p>Sobretudo: sem bashrc para manter, sem scripts que fiquem espalhados em`~/bin`, sem Makefile ao lado do docker-compose. Tudo vive em um único arquivo, no mesmo local que o código do projeto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_build_gradle_kts_completo">O build.gradle.kts completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está o arquivo que acabei por escrever. Ele faz tudo, do provisionamento de volume até o curl de verificação, passando pelo sign-in interativo.</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>Aqui está. Doze tarefas, um único ponto de entrada e zero atrito.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomia_das_tarefas_chave">Anatomia das Tarefas Chave</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_o_lançador">startOllamaB` — O Lançador</h3> <div class="paragraph"> <p>Nada de especial: um`docker run -d`com os parâmetros corretos. O truque está em`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>Se o contêiner já existir, o comando`docker run`falha (código de saída ≠ 0). Sem essa propriedade, o Gradle interromperia todo o build com erro. Aqui, a falha é silenciosa — e o`doLast`detecta se era um "já existente" ou um erro real.</p> </div> <div class="paragraph"> <p>Le `doLast`é crucial : ele é executado <strong>após</strong> a execução do comando, o que permite inspecionar`executionResult.get().exitValue`e de registrar uma mensagem apropriada.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_o_interativo">signInB` — O Interativo</h3> <div class="paragraph"> <p>É a única tarefa que requer interação humana. Gradle transmite`System.in`ao process para que o prompt`ollama signin`possa aparecer 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>Sem isso, o sign-in bloquearia porque o stdin estaria fechado e você nunca veria o prompt.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_o_configurável">pullModelB` — O configurável</h3> <div class="paragraph"> <p>Uma tarefa genérica que aceita um parâmetro via`-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>O fallback é importante:`project.findProperty("model") as? String ?: "qwen3:0.6b"`garante que a tarefa não quebre se esquecermos o parâmetro.</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_o_diagnóstico">statusOllamaAll` — O Diagnóstico</h3> <div class="paragraph"> <p>Dois`curl`em saúde nos portos`11434` et <code>11435</code>, com um fallback em`runCatching`para não travar caso uma das instâncias esteja down. A saída é estruturada:</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>Um olhar, e você sabe exatamente o que está acontecendo e o que está errado.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_a_limpeza_que_preserva_a_identidade">cleanOllamaB` — A limpeza que preserva a identidade</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>O contêiner foi excluído, mas o volume`~/ollama-b-data`é<strong>conservado</strong>. A identidade SSH sobrevive à limpeza. Ao próximo`startOllamaB`, as mesmas chaves serão reutilizadas — não é preciso refazer o sign-in nem re-registrar a Device Key.</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`não toque no volume. Se quiser apagar a identidade B (e recomeçar tudo do zero), é preciso excluir</code>~/ollama-b-data`manualmente. É voluntário — um`clean`não deve destruir as credenciais.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workflow_completo_de_zero_a_duas_sessões">Workflow Completo — De Zero a Duas Sessões</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está a sequência ideal para alguém que chega ao projeto e quer colocar tudo em funcionamento sem abrir nenhuma documentação:</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 dois minutos, tudo está provisionado. Não há README para ler, não há variáveis de ambiente a definir. A tarefa`helpOllama`funciona como documentação 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 Instância B" as OllamaB participant "Ollama\nNuvem" 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_que_não_transformá_lo_em_um_plugin_gradle_real">Por que não transformá-lo em um plugin Gradle real?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pergunta legítima. Extrair isso`build.gradle.kts`em um plugin Gradle autônomo teria vantagens: reutilização entre projetos, configuração declarativa, extensão DSL.</p> </div> <div class="paragraph"> <p>Mas por enquanto, não faz sentido. Este build não tem lógica de negócios complexa — é um wrapper em torno de comandos Docker e curl. A sobrecarga de um plugin Gradle completo (com extensão, testes unitários, publicação) seria desproporcional para 12 tarefas utilitárias.</p> </div> <div class="paragraph"> <p>Le `build.gradle.kts`inline está no projeto que precisa dele. É trivial copiar em outro lugar. Se um dia eu tiver três projetos que dependem dele, eu o transformarei em um plugin. Por enquanto, 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>O dia em que tens três`build.gradle.kts`identiques em três projetos, isso é o sinal de que é necessário extrair um plugin. Antes disso, a duplicação é menos custosa que a abstração. Sabedoria de dev.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lições_aprendidas">Lições Aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle não é apenas uma ferramenta de build</strong>— O motor de grafo de dependências o torna um orquestrador de infraestrutura formidável.<code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code>: estas três primitivas são suficientes para gerenciar um contêiner Docker com a mesma confiabilidade de um pipeline CI.</p> </li> <li> <p><strong>isIgnoreExitValue` é teu amigo</strong>— Num mundo ideal,<code>docker run`em um contêiner já existente retornaria um aviso em vez de um código de saída de erro. No mundo real, você coloca`isIgnoreExitValue = true`e você gerencia o diagnóstico em`doLast</code>.</p> </li> <li> <p><strong>As tarefas configuráveis matam a ambiguidade</strong> — Un <code>pullModelB`genérico com</code>-Pmodel=…​`substitui N tarefas especializadas. Uma única tarefa, uma única documentação, um único comportamento.</p> </li> <li> <p><strong>runCatching` para as verificações de saúde</strong>— Quando você testa N endpoints, a falha do primeiro não deve impedir de testar os outros.<code>runCatching</code>+`getOrElse`por endpoint, e o diagnóstico permanece completo mesmo em caso de falha parcial.</p> </li> <li> <p><strong>A tarefa <code>helpOllama</code> como documentação executável</strong> — Un `println()`Bem formatado substitui um README de três parágrafos. É auto-documentado, sempre atualizado e acessível sem sair do terminal.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Passamos de comandos docker a digitar à mão para um workflow Gradle completo, versionado, reutilizável. Doze tarefas cobrem todo o ciclo de vida: provisionamento, identidade, sign-in, pull, teste, diagnóstico, limpeza.</p> </div> <div class="paragraph"> <p>O combo docker-compose + build.gradle.kts + opencode.json forma uma trindade limpa: Docker para isolamento, Gradle para orquestração, OpenCode para consumo. Cada camada tem sua responsabilidade, e nenhuma transborda sobre a outra.</p> </div> <div class="paragraph"> <p>Próxima etapa? Automatizar o ciclo de vida na CI para que as instâncias Ollama estejam disponíveis nos ambientes de desenvolvimento efêmeros. Mas isso é outro artigo.</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">User Manual Gradle — Tarefas</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">Manual do Usuário Gradle — Tarefas Personalizadas</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Imagem Docker Ollama no Docker Hub</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle DSL Kotlin — Documentação</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Artigo publicado em 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="#_introdução">Introdução</a></li> <li><a href="#_por_que_fazer_a_mesma_coisa_duas_vezes">Por que fazer a mesma coisa duas vezes?</a></li> <li><a href="#_o_coração_do_problema_a_device_key">O Coração do Problema : A Device Key</a></li> <li><a href="#_colocação_passo_a_passo">Colocação — Passo a Passo</a> <ul class="sectlevel2"> <li><a href="#_pré_requisito">Pré-requisito</a></li> <li><a href="#_etapa_1_criar_o_volume">Etapa 1: Criar o Volume</a></li> <li><a href="#_passo_2_iniciar_o_contêiner_docker">Passo 2: Iniciar o contêiner Docker</a></li> <li><a href="#_passo_3_recuperar_a_chave_pública">Passo 3: Recuperar a Chave Pública</a></li> <li><a href="#_passo_4_registrar_a_chave_no_ollama_com">Passo 4: Registrar a Chave no Ollama.com</a></li> <li><a href="#_passo_5_testar_com_um_modelo_pequeno_gratuito">Passo 5: Testar com um modelo pequeno gratuito</a></li> </ul> </li> <li><a href="#_a_armadilha_da_api_v1models">A armadilha da API `/v1/models</a></li> <li><a href="#_resultado_duas_sessões_duas_contas_zero_conflito">Resultado: Duas Sessões, Duas Contas, Zero Conflito</a></li> <li><a href="#_lições_aprendidas">Lições Aprendidas</a></li> <li><a href="#_para_ir_mais_longe">Para Ir Mais Longe</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 14 minutes</div> <p>Duas assinaturas Pro, uma única máquina, um único cartão bancário, e nenhum conflito de rede. Como o Docker me permitiu dobrar minha capacidade de inferência na nuvem sem comprar um segundo PC.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estou usando o Ollama Pro há vários meses para alimentar minhas sessões OpenCode com modelos de nuvem. O problema é que, mesmo com uma assinatura Pro, ficamos rapidamente limitados pelo <strong>rate limiting</strong> quando iniciamos vários agentes em paralelo. A solução óbvia: uma segunda assinatura.</p> </div> <div class="paragraph"> <p>Mas aí, é o drama.</p> </div> <div class="paragraph"> <p>Ollama identifica cada máquina por uma chave SSH única — a sua famosa <strong>Device Key</strong>. Duas instâncias no mesmo SO compartilhariam a mesma identidade, e seria impossível vincular duas contas Pro ao mesmo device. E como você já deve imaginar, eu não ia comprar um segundo laptop só por isso.</p> </div> <div class="paragraph"> <p>A solução: trapacear. Fazer o Ollama acreditar que está sendo executado em duas máquinas diferentes, embora compartilhem o mesmo CPU, a mesma RAM e a mesma conexão de rede. Docker nos oferecerá uma bolha de isolamento perfeito.</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 "Instância A do Ollama (Nativa)" as Native { database "Identity ^^^^^ 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 "Instância A do Ollama (Nativa)" as Native { database "Identity /usr/share/ollama/.ollama/id_ed25519" as KeyA portin "API :11434" as PortA } frame "Ollama Instance B (Docker)" as Docker { database "Identidade ~/ollama-b-data/id_ed25519" as KeyB portin "API :11435" as PortB } } cloud "Ollama Cloud" { actor "Conta Pro A\n(email 1)" as AccountA actor "Conta Pro B\n(e-mail 2)" as AccountB } KeyA --> AccountA : "Chave SSH A" KeyB --> AccountB : "Chave SSH B" PortA --> AccountA : "Requisições 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_que_fazer_a_mesma_coisa_duas_vezes">Por que fazer a mesma coisa duas vezes?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de me chamar de doente mental, deixe-me explicar o caso de uso para você.</p> </div> <div class="paragraph"> <p>Com uma única assinatura Pro, posso lançar um modelo como`deepseek-v4-pro:cloud`dentro de uma sessão OpenCode. O problema surge quando eu quero <strong>duas</strong> sessões simultâneas. As cotas de rate limiting fazem com que a segunda sessão trave ou seja pura e simplesmente rejeitada.</p> </div> <div class="paragraph"> <p>Com duas assinaturas Pro independentes:</p> </div> <div class="ulist"> <ul> <li> <p>Sessão OpenCode 1 → Conta Pro A`localhost:11434`)</p> </li> <li> <p>Session OpenCode 2 → Conta Pro B`localhost:11435`)</p> </li> </ul> </div> <div class="paragraph"> <p>Cada sessão tem sua própria cota, seu próprio contexto, e não incomoda a outra. É multi-processamento 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>Duas assinaturas Pro = dois e‑mails diferentes. O mesmo cartão de crédito funciona — o sistema de pagamento da Ollama não bloqueia assinaturas múltiplas a partir do mesmo meio de pagamento. Verifiquei.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_coração_do_problema_a_device_key">O Coração do Problema : A Device Key</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando você instala o Ollama, um par de chaves SSH ed25519 é gerado no diretório de identidade:</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 chave é feita upload para os servidores da Ollama durante o`ollama signin`. Ela é quem diz « esta máquina pertence a tal conta Pro ». Se suas duas instâncias compartilharem o mesmo arquivo`id_ed25519`, elas compartilham a mesma identidade. Fim do jogo.</p> </div> <div class="paragraph"> <p>O expediente : dar à nossa segunda instância seu próprio diretório de identidade, isolado em um volume Docker.</p> </div> </div> </div> <div class="sect1"> <h2 id="_colocação_passo_a_passo">Colocação — Passo a Passo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pré_requisito">Pré-requisito</h3> <div class="ulist"> <ul> <li> <p>Uma instalação nativa do Ollama funcional (script oficial`curl | sh`)</p> </li> <li> <p>Docker instalado e funcional</p> </li> <li> <p>Portainer ou docker-compose para a implantação</p> </li> <li> <p>Duas contas Ollama com dois e-mails distintos</p> </li> </ul> </div> <div class="paragraph"> <p>Eu usei a versão`0.20.2`— a fornecida pelo script oficial e a imagem Docker correspondente.</p> </div> </div> <div class="sect2"> <h3 id="_etapa_1_criar_o_volume">Etapa 1: Criar o Volume</h3> <div class="paragraph"> <p>Um diretório simples no host servirá como volume persistente para a identidade da instância 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>Esta pasta será montada no contêiner Docker como`/root/.ollama`, onde o Ollama armazena suas chaves de identidade, seu histórico e seus modelos.</p> </div> </div> <div class="sect2"> <h3 id="_passo_2_iniciar_o_contêiner_docker">Passo 2: Iniciar o contêiner 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>O que se passa aqui:</p> </div> <div class="ulist"> <ul> <li> <p>O porto<strong>11435</strong>do host é mapeado para o<strong>11434</strong>interna do contêiner. Assim, a instância Docker ouve em`:11435`sem conflito com a instância nativa que ocupa`:11434`.</p> </li> <li> <p>O volume`~/ollama-b-data`está montado sobre`/root/.ollama`— é aqui que a identidade SSH será armazenada.</p> </li> <li> <p>`OLLAMA_HOST=0.0.0.0`permite ao contêiner aceitar conexões externas.</p> </li> </ul> </div> <div class="paragraph"> <p>Eu implementei essa stack via Portainer, mas um simples`docker compose up -d`funciona tão bem quanto.</p> </div> </div> <div class="sect2"> <h3 id="_passo_3_recuperar_a_chave_pública">Passo 3: Recuperar a Chave Pública</h3> <div class="paragraph"> <p>Como o container está vazio na primeira inicialização, Ollama gera automaticamente um novo par de chaves SSH no volume. Recuperamos a chave 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>Eu verifico que essa chave é <strong>diferente</strong> daquela da instância 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>Duas chaves distintas, duas identidades separadas. O truque foi feito.</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>Se o seu contêiner reiniciar, ele <strong>reutiliza</strong> as chaves presentes no volume. A identidade é persistente. Você não perderá a associação com a conta Pro.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_passo_4_registrar_a_chave_no_ollama_com">Passo 4: Registrar a Chave no Ollama.com</h3> <div class="paragraph"> <p>Acesse <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → Adicionar Chave SSH. Cole a chave pública da instância Docker e valide.</p> </div> <div class="paragraph"> <p>Em seguida, vincula-se esta identidade à conta 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>O navegador se abre, conectamo-nos com o e-mail da conta B e o token é associado à chave SSH do contêiner. Verificamos que tudo 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="_passo_5_testar_com_um_modelo_pequeno_gratuito">Passo 5: Testar com um modelo pequeno gratuito</h3> <div class="paragraph"> <p>Antes de mencionar o preço de uma assinatura Pro, quero ter certeza de que o tubo funciona. Eu faço um pull de um pequeno modelo local e gratuito para validar a conectividade:</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>O porto`11435`responde, o modelo está servido. A instância B está viva.</p> </div> <div class="paragraph"> <p>Depois de ficar tranquilo, passo para o pull do modelo cloud Pro verdadeiro :</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 o manifesto de um modelo cloud — normal, a inferência é feita do lado do servidor, não localmente. Eis o teste definitivo :</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>Olá também a ti, instance B.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_armadilha_da_api_v1models">A armadilha da API `/v1/models</h2> <div class="sectionbody"> <div class="paragraph"> <p>Perdi 20 minutos em um detalhe bobo. Quando eu configurei o provedor`ollama-b`no OpenCode, nada apareceu no seletor de modelos. Nada. De forma alguma.</p> </div> <div class="paragraph"> <p>A razão? L’API`/v1/models`da instância B retornou`{"object":"list","data":null}`em vez de`{"object":"list","data":[]}`quand nenhum modelo estava sendo puxado. O valor`null`fazia o parsing travar no lado OpenCode, que não exibia o provider.</p> </div> <div class="paragraph"> <p>A solução: declarar os modelos <strong>explícitamente</strong> na configuração OpenCode em vez de contar com a descoberta dinâmica.</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>Com esta declaração explícita, o OpenCode vê imediatamente o provider B e seus modelos. Um reinício de sessão, e o seletor`/models`mostra as duas instâncias lado a lado.</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>Se você não vê seu provider custom em`/models`, não perca três horas a reiniciar seu terminal. Declare os modelos manualmente em`opencode.json`— isso resolve o problema instantaneamente.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_resultado_duas_sessões_duas_contas_zero_conflito">Resultado: Duas Sessões, Duas Contas, Zero Conflito</h2> <div class="sectionbody"> <div class="paragraph"> <p>Finalmente, posso lançar duas sessões OpenCode simultaneamente:</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 sessão tem sua própria cota, seu próprio rate limit, e não se pisam nos pés. Mesmo máquina, mesmo cartão azul, dois e-mails diferentes.</p> </div> <div class="paragraph"> <p>E o melhor? O contêiner Docker está em`restart: always`. Ele sobrevive às reinicializações do sistema sem intervenção manual.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lições_aprendidas">Lições Aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker isola tudo, mesmo a identidade</strong>— Um simples bind mount de volume é suficiente para dar a um contêiner seu próprio conjunto de chaves SSH, tornando-o indistinguível de uma máquina física diferente aos olhos do Ollama.</p> </li> <li> <p><strong>Dois e-mails, mesmo CB</strong>— Ollama não bloque as assinaturas múltiplas desde o mesmo meio de pagamento. Só o email deve ser distinto.</p> </li> <li> <p><strong>Testar grátis 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` com <code>data: null</code> quebra OpenCode</strong>— Se você configurar um provider custom com`"models": {}`, OpenCode tenta descobrir os modelos via a API. Se a API responde`data: null`, o provedor não aparece. Declare os modelos explicitamente.</p> </li> <li> <p><strong>Duas contas, isso é multiprocessamento humano</strong>— Uma conta Pro = uma sessão OpenCode ativa. Duas contas = duas sessões paralelas. Para alguém que está malabarizando entre vários projetos Gradle simultaneamente, isso é um game changer.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_mais_longe">Para Ir Mais Longe</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Ollama Settings — Gerenciamento de chaves SSH</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Documentação oficial Ollama</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Imagem Docker Ollama no Docker Hub</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Provedor de Configuração Ollama</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Artigo publicado em 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_que_escolher_o_kitty_e_o_zsh">Por que escolher o Kitty e o Zsh?</a></li> <li><a href="#_pré_requisitos_do_sistema">Pré-requisitos do sistema</a></li> <li><a href="#_download_e_instalação_do_kitty">Download e instalação do Kitty</a> <ul class="sectlevel2"> <li><a href="#_baixar_o_script_de_instalação">Baixar o script de instalação</a></li> <li><a href="#_criação_dos_links_simbólicos">Criação dos links simbólicos</a></li> </ul> </li> <li><a href="#_integração_do_kitty_no_xubuntu">Integração do Kitty no Xubuntu</a> <ul class="sectlevel2"> <li><a href="#_copiar_o_arquivo_da_área_de_trabalho">Copiar o arquivo da área de trabalho</a></li> <li><a href="#_editar_o_ficheiro_desktop">Editar o ficheiro desktop</a></li> <li><a href="#_associar_kitty_como_terminal_padrão_opcional">Associar Kitty como terminal padrão (opcional)</a></li> </ul> </li> <li><a href="#_instalação_do_zsh">Instalação do Zsh</a></li> <li><a href="#_definir_o_zsh_como_shell_padrão">Definir o Zsh como shell padrão</a> <ul class="sectlevel2"> <li><a href="#_método_global_para_todos_os_terminais">Método global (para todos os terminais)</a></li> <li><a href="#_método_específico_para_kitty">Método específico para Kitty</a></li> </ul> </li> <li><a href="#_configuração_do_zsh_opcional">Configuração do Zsh (opcional)</a> <ul class="sectlevel2"> <li><a href="#_criar_um_arquivo_zshrc">Criar um arquivo .zshrc</a></li> <li><a href="#_exemplo_de_configuração_mínima">Exemplo de configuração mínima</a></li> </ul> </li> <li><a href="#_resumo_do_workflow_completo">Resumo do workflow completo</a></li> <li><a href="#_verificação_final">Verificação final</a> <ul class="sectlevel2"> <li><a href="#_abrir_o_arquivo_de_configuração">📂 Abrir o arquivo de configuração</a></li> <li><a href="#_️_adicionar_ou_modificar_font_size">�🖋️ Adicionar ou modificar `font_size</a></li> <li><a href="#_salvar_e_reiniciar_kitty">💾 Salvar e reiniciar Kitty</a></li> <li><a href="#_ajuste_dinâmico_zoom_temporário">�✅ Ajuste dinâmico (Zoom temporário)</a></li> </ul> </li> <li><a href="#_instalação_e_configuração_do_oh_my_zsh">Instalação e configuração do Oh My Zsh</a> <ul class="sectlevel2"> <li><a href="#_instalação_do_oh_my_zsh">Instalação do Oh My Zsh</a></li> <li><a href="#_mudar_o_tema">Mudar o tema</a></li> <li><a href="#_verificação">Verificação</a></li> <li><a href="#_diagrama_do_caso_de_uso">Diagrama do caso de uso</a></li> </ul> </li> <li><a href="#_ativar_a_translucididade_no_kitty">Ativar a translucididade no Kitty</a> <ul class="sectlevel2"> <li><a href="#_pré_requisito_para_a_transparência">Pré-requisito para a transparência</a></li> <li><a href="#_configuração_de_transparência_no_kitty_conf">Configuração de transparência no kitty.conf</a></li> <li><a href="#_reiniciar_kitty">Reiniciar Kitty</a></li> <li><a href="#_complementos_possíveis">Complementos possíveis</a></li> <li><a href="#_diagrama_de_sequência_inicialização_da_kitty_com_transparência">Diagrama de sequência - Inicialização da Kitty com transparência</a></li> <li><a href="#_limitações_conhecidas">Limitações conhecidas</a></li> </ul> </li> <li><a href="#_desativar_o_sinal_sonoro_sino_audível">Desativar o sinal sonoro (sino audível)</a></li> <li><a href="#_atualização_de_kitty">Atualização de Kitty</a></li> <li><a href="#_referências">Referências</a></li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Este guia explica passo a passo como instalar o terminal <strong>kitty</strong> no Xubuntu, configurá-lo corretamente e substituir o bash por <strong>zsh</strong> como shell padrão. O projeto kitty está disponível aqui: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a>.</p> </div> <div class="paragraph"> <p><em><em>_ Kitty é um terminal moderno, rápido e configurável, particularmente adequado para desenvolvedores exigentes. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_escolher_o_kitty_e_o_zsh">Por que escolher o Kitty e o Zsh?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty distingue-se por :</p> </div> <div class="ulist"> <ul> <li> <p>Desempenhos superiores graças à aceleração da GPU,</p> </li> <li> <p>Uma configuração totalmente baseada em um arquivo de texto único,</p> </li> <li> <p>Um excelente suporte a fontes e ligaduras</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh, por outro lado, é um shell interativo poderoso que oferece :</p> </div> <div class="ulist"> <ul> <li> <p>Uma conclusão inteligente,</p> </li> <li> <p>Um prompt personalizável,</p> </li> <li> <p>Uma grande compatibilidade com o bash.</p> </li> </ul> </div> <div class="paragraph"> <p>Ao combinar Kitty e Zsh, você desfruta de um ambiente produtivo e 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>Este guia é intencionalmente limitado à instalação via script e ao Xubuntu.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_pré_requisitos_do_sistema">Pré-requisitos do sistema</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de começar, certifique-se de ter :</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu instalado,</p> </li> <li> <p>acesso à internet,</p> </li> <li> <p>um shell bash funcional para lançar o script.</p> </li> </ul> </div> <div class="paragraph"> <p>Verifique seu ambiente:</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="_download_e_instalação_do_kitty">Download e instalação do Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty recomenda instalá‑lo via um script oficial que coloca os arquivos em`~/.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 é independente dos gerenciadores de pacotes (sem`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_baixar_o_script_de_instalação">Baixar o script de instalação</h3> <div class="paragraph"> <p>Execute o seguinte 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 executa:</p> </div> <div class="ulist"> <ul> <li> <p>download dos binários,</p> </li> <li> <p>extração em`~/.local/kitty.app`,</p> </li> <li> <p>criação dos links simbólicos.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/download-install.svg" alt="download install" width="288" height="336"> </div> </div> </div> <div class="sect2"> <h3 id="_criação_dos_links_simbólicos">Criação dos links simbólicos</h3> <div class="paragraph"> <p>Para poder invocar`kitty`A partir do terminal, crie um link 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>Adicione`~/.local/bin`adicionar ao seu PATH se ainda não o tiver feito :</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>Você pode verificar a instalação:</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="_integração_do_kitty_no_xubuntu">Integração do Kitty no Xubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que Kitty appele no menu de aplicativos :</p> </div> <div class="sect2"> <h3 id="_copiar_o_arquivo_da_área_de_trabalho">Copiar o arquivo da área de trabalho</h3> <div class="paragraph"> <p>Copie o arquivo`.desktop`fornecido :</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="_editar_o_ficheiro_desktop">Editar o ficheiro desktop</h3> <div class="paragraph"> <p>Edite o arquivo :</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 ou modifique as linhas seguintes :</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>Substitua`YOURUSER`pelo seu nome de usuário</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/desktop-integration.png" alt="desktop integration" width="439" height="335"> </div> </div> </div> <div class="sect2"> <h3 id="_associar_kitty_como_terminal_padrão_opcional">Associar Kitty como terminal padrão (opcional)</h3> <div class="paragraph"> <p>Para que Kitty seja o terminal iniciado por padrão:</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>Selecione`kitty`no menu proposto.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_instalação_do_zsh">Instalação do Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se o Zsh ainda não estiver instalado, execute:</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>Verifique a instalação:</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="_definir_o_zsh_como_shell_padrão">Definir o Zsh como shell padrão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Você pode mudar seu shell globalmente ou apenas no Kitty.</p> </div> <div class="sect2"> <h3 id="_método_global_para_todos_os_terminais">Método global (para todos os terminais)</h3> <div class="paragraph"> <p>Identifique o caminho 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>Em geral`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>Altere o shell padrão:</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>Desconecte-se e reconecte-se.</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>Se você prefere apenas mudar o shell no Kitty, edite o arquivo de configuração :</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>Adicione esta linha :</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>Salve e reinicie o Kitty.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuração_do_zsh_opcional">Configuração do Zsh (opcional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para personalizar seu Zsh:</p> </div> <div class="sect2"> <h3 id="_criar_um_arquivo_zshrc">Criar um arquivo .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="_exemplo_de_configuração_mínima">Exemplo de configuração 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="_resumo_do_workflow_completo">Resumo do workflow completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>O esquema abaixo resume todo o processo :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/full-workflow.png" alt="full workflow" width="348" height="643"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificação_final">Verificação final</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lance 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>Você deveria ver que`zsh`está ativo :</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 o tamanho da fonte em<strong>Kitty</strong>, é preciso ajustar o parâmetro`font_size`no arquivo de configuração. Aqui está o procedimento detalhado :</p> </div> <div class="sect2"> <h3 id="_abrir_o_arquivo_de_configuração">📂 Abrir o arquivo de configuração</h3> <div class="paragraph"> <p>O arquivo principal de configuração geralmente está localizado em :</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>Se este arquivo ainda não existir, você pode criá-lo. Exemple :</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="_️_adicionar_ou_modificar_font_size">�🖋️ Adicionar ou modificar `font_size</h3> <div class="paragraph"> <p>Adicione a diretiva a seguir, ou modifique-a se ela já existir:</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>Aqui`14.0`Corresponde ao tamanho desejado. Você pode colocar qualquer valor decimal, por exemplo`12.0`, <code>15.5</code>, etc.</p> </div> </div> <div class="sect2"> <h3 id="_salvar_e_reiniciar_kitty">💾 Salvar e reiniciar Kitty</h3> <div class="ulist"> <ul> <li> <p>Salve (<code>Ctrl + O</code>, então`Entrée`) e saia (<code>Ctrl + X</code>) se você usa`nano`.</p> </li> <li> <p>Feche todas as janelas do Kitty, depois reinicie o terminal para que a mudança tenha efeito.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_ajuste_dinâmico_zoom_temporário">�✅ Ajuste dinâmico (Zoom temporário)</h3> <div class="paragraph"> <p>Se você deseja zoomer/dézoomer temporariamente sem modificar a configuração, utilize os atalhos de teclado padrão:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Aumentar o tamanho da fonte</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Diminuir o tamanho da fonte</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Redefinir o tamanho</strong></think></p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>Essas configurações não persistem após o fechamento do terminal.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_instalação_e_configuração_do_oh_my_zsh">Instalação e configuração do Oh My Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Uma vez que o Zsh esteja instalado e configurado como shell padrão, você pode enriquecer seu ambiente com <strong>Oh My Zsh</strong>, um framework de gerenciamento de configuração do Zsh, oferecendo:</p> </div> <div class="ulist"> <ul> <li> <p>uma coleção de temas para o prompt,</p> </li> <li> <p>muitos plugins,</p> </li> <li> <p>uma organização clara da configuração.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_instalação_do_oh_my_zsh">Instalação do Oh My Zsh</h3> <div class="paragraph"> <p>Certifique-se de que o Zsh está ativo :</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>Se necessário, lance :</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>Em seguida, baixe e execute o script de instalação 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>crie a pasta`~/.oh-my-zsh`,</p> </li> <li> <p>salva eventualmente seu arquivo`~/.zshrc`,</p> </li> <li> <p>ativa automaticamente o novo prompt.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_mudar_o_tema">Mudar o tema</h3> <div class="paragraph"> <p>Abra o seu arquivo de configuração:</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>Altere a variável`ZSH_THEME`para escolher outro tema (por exemplo`agnoster`) :</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster</p> </div> <div class="paragraph"> <p>Salve e recarregue a configuração :</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="_verificação">Verificação</h3> <div class="paragraph"> <p>Inicie o Kitty e verifique se o prompt foi alterado corretamente. Você pode confirmar que o Oh My Zsh está ativo executando:</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>O resultado deveria ser similar a :</p> </div> <div class="paragraph"> <p>/home/seu_utilizador/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_diagrama_do_caso_de_uso">Diagrama do caso de uso</h3> <div class="imageblock"> <div class="content"> <img src="./images/ohmyzsh-installation.png" alt="ohmyzsh installation" width="511" height="480"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ativar_a_translucididade_no_kitty">Ativar a translucididade no Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Uma das funcionalidades mais apreciadas do Kitty é a possibilidade de adicionar <strong>transparência</strong> ao fundo do terminal. Isso permite ver levemente o ambiente subjacente (janela, área de trabalho, etc.), o que é particularmente útil em multitarefa.</p> </div> <div class="sect2"> <h3 id="_pré_requisito_para_a_transparência">Pré-requisito para a transparência</h3> <div class="paragraph"> <p>A transparência no Kitty baseia-se no<strong>compositor de janelas</strong>usado pelo ambiente gráfico. No Xubuntu (baseado em XFCE), certifique‑se de que a<strong>composição está ativada</strong>.</p> </div> <div class="paragraph"> <div class="title">À vérifier : -→ .A verificar : (but must output only translation)</div> <p>So output:.A verificar :</p> </div> <div class="paragraph"> <p>Proceed.</p> </div> <div class="paragraph"> <p></think></p> </div> <div class="ulist"> <div class="title">A vérifier :</div> <ul> <li> <p>clique com o botão direito na área de trabalho > Configurações ><strong>Parâmetros do gerenciador de janelas</strong>,</p> </li> <li> <p>aba<strong>Compositor</strong>: a caixa <strong><code>Activer la composition</strong></code> deve estar marcada.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/transparency-usecase.png" alt="transparency usecase" width="597" height="225"> </div> </div> </div> <div class="sect2"> <h3 id="_configuração_de_transparência_no_kitty_conf">Configuração de transparência no kitty.conf</h3> <div class="paragraph"> <p>Abra o seu ficheiro de configuração`~/.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>Adicione ou modifique as linhas seguintes:</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 aceita valores entre :</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ opaco (nenhuma transparência),</p> </li> <li> <p><code>0.0</code>→ totalmente transparente (inutilizável)</p> </li> <li> <p>valores intermediários como`0.90`, <code>0.75</code>, etc.</p> </li> </ul> </div> <div class="paragraph"> <p>Um bom compromisso visual geralmente está 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>Feche todas as instâncias do Kitty e, em seguida, reinicie uma nova janela para que as alterações tenham efeito :</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_possíveis">Complementos possíveis</h3> <div class="paragraph"> <p>Se você usa um fundo de terminal personalizado, também pode definir uma cor de fundo com transparência (em 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>Última componente ()<code>ff</code>) indica a opacidade (de`00` à <code>ff</code>)</p> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_sequência_inicialização_da_kitty_com_transparência">Diagrama de sequência - Inicialização da Kitty com transparência</h3> <div class="imageblock"> <div class="content"> <img src="./images/transparency-sequence.png" alt="transparency sequence" width="771" height="422"> </div> </div> </div> <div class="sect2"> <h3 id="_limitações_conhecidas">Limitações conhecidas</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>A translucidez não funciona se: - o compositor XFCE está desativado, - um gerenciador de janelas incompatível é utilizado, - você está usando Kitty no modo <strong>tmux</strong> em segundo plano sem suporte de transparência.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_desativar_o_sinal_sonoro_sino_audível">Desativar o sinal sonoro (sino audível)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Por padrão, o Kitty emite um som de <strong>bip</strong> quando um comando errado é inserido ou quando um evento de terminal o dispara. Este som pode rapidamente se tornar incômodo, especialmente em um ambiente de desenvolvimento intenso.</p> </div> <div class="paragraph"> <p>Para desativar esse comportamento, adicione a seguinte diretiva ao arquivo`~/.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>Você também pode ativar um <strong>retorno visual</strong> em substituição ao bip sonoro :</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="_atualização_de_kitty">Atualização de Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Como o Kitty é instalado por meio de um script e não por um gerenciador de pacotes, a atualização é feita ao relançar o script de instalação oficial. Isso permite baixar a versão mais recente e atualizar sua instalação existente em`~/.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>O sufixo`.app`no caminho`~/.local/kitty.app`é a convenção de instalação do Kitty no Linux via o seu script oficial, e não indica de forma alguma uma compatibilidade exclusiva com o 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 executar o comando de atualização, certifique-se de estar no seu diretório pessoal (<code>~</code>)</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Execute o seguinte comando a partir do seu diretório pessoal:</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 cuidará de:</p> </div> <div class="ulist"> <ul> <li> <p>Baixar os binários da nova versão.</p> </li> <li> <p>Extrair os ficheiros em`~/.local/kitty.app`.</p> </li> <li> <p>Atualizar os links simbólicos se necessário.</p> </li> </ul> </div> <div class="paragraph"> <p>Após a atualização, recomenda-se fechar todas as instâncias do Kitty e reiniciá‑las para garantir que a nova versão seja reconhecida.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se você quiser aprofundar a personalização, consulte a documentação 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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Você dispõe agora :</p> </div> <div class="ulist"> <ul> <li> <p>de um terminal moderno e performante (Kitty)</p> </li> <li> <p>um shell poderoso e personalizável (Zsh)</p> </li> <li> <p>de uma configuração limpa e independente dos pacotes do sistema</p> </li> <li> <p>de um terminal estético e funcional equipado com 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="#_o_contexto_um_mercado_que_invertiu">O Contexto : Um Mercado que Invertiu</a></li> <li><a href="#_painel_das_opções">Painel das Opções</a> <ul class="sectlevel2"> <li><a href="#_o_que_excluí_e_por_que">O que excluí (e por que)</a></li> </ul> </li> <li><a href="#_inferência_simples_a_morte_do_hardware_local">Inferência Simples: A Morte do Hardware Local</a> <ul class="sectlevel2"> <li><a href="#_o_cálculo">O Cálculo</a></li> <li><a href="#_mesmo_com_uso_intensivo">Mesmo com uso intensivo</a></li> </ul> </li> <li><a href="#_fine_tuning_o_cloud_é_invencível">Fine-Tuning : O Cloud é invencível</a> <ul class="sectlevel2"> <li><a href="#_o_custo_real_de_um_fine_tune">O custo real de um Fine-Tune</a></li> <li><a href="#_os_atores_especializados">Os Atores Especializados</a></li> </ul> </li> <li><a href="#_a_única_verdadeira_razão_a_soberania_dos_dados">A única verdadeira razão: a soberania dos dados</a> <ul class="sectlevel2"> <li><a href="#_o_verdadeiro_cálculo_da_confidencialidade">O Verdadeiro Cálculo da Confidencialidade</a></li> </ul> </li> <li><a href="#_síntese_a_matriz_de_decisão">Síntese: A matriz de decisão</a></li> <li><a href="#_o_caso_particular_a_assinatura_pro_face_aos_modelos_chineses">O Caso Particular: A Assinatura Pro Face aos Modelos Chineses</a> <ul class="sectlevel2"> <li><a href="#_por_que_os_modelos_chinos_mudam_tudo">Por que os Modelos Chinos Mudam Tudo</a></li> <li><a href="#_o_que_isso_significa_para_o_hardware">O Que Isso Significa para o Hardware</a></li> </ul> </li> <li><a href="#_e_huawei">E Huawei?</a></li> <li><a href="#_conclusão_o_luxo_da_proximidade">Conclusão: O Luxo da Proximidade</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 14 minutes</div> <p>NVIDIA vende o DGX Spark como um « supercomputador IA de mesa » por $4 699. A Ollama oferece seus modelos na nuvem por $20/mês. Um H100 pode ser alugado por $1,38/h na Vast.ai. E os modelos chineses de código aberto — DeepSeek, Qwen, GLM — estão disponíveis em todo lugar, gratuitamente, sem precisar comprar uma placa. Então, para que serve esse Spark exatamente? Fiz as contas.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_contexto_um_mercado_que_invertiu">O Contexto : Um Mercado que Invertiu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em maio de 2026, o cenário da IA mudou radicalmente em relação ao anúncio do DGX Spark na CES 2025. Três forças convergiram para tornar o hardware local cada vez mais difícil de justificar:</p> </div> <div class="ulist"> <ul> <li> <p><strong>O colapso dos preços do cloud GPU</strong>: um H100 é alugado entre $1.38 e $3/h, versus $5-8/h há 18 meses</p> </li> <li> <p><strong>A explosão dos modelos chineses open-source</strong>DeepSeek-V4, Qwen-3, GLM-5 são competitivos com os modelos ocidentais, disponíveis gratuitamente</p> </li> <li> <p><strong>A ascensão das plataformas de inferência gerenciada</strong>Ollama, Groq, Together AI oferecem APIs com tarifas agressivas, com camadas gratuitas generosas</p> </li> </ul> </div> <div class="paragraph"> <p>O DGX Spark, anunciado a $2 999 e depois elevado a $4 699, chega a um mundo que não precisa mais dele.</p> </div> </div> </div> <div class="sect1"> <h2 id="_painel_das_opções">Painel das Opções</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui estão as soluções disponíveis em maio de 2026 para rodar os LLMs, da mais leve à mais 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">opção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / Capacidade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelos acessíveis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Restrição principal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Gratuito</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/mês</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nuvem leve</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos 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/mês (~$240/ano)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (API fechada)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude 4.x apenas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelo único, não é 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/mês (~$200/ano)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Meio de nuvem</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos os 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/mês (~$1 200/ano)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nuvem pesada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos os 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 de nuvem (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 os modelos, ajuste fino</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Faturação horária, configuração necessária</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 um H100), fixo</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">Não CUDA, ecossistema 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>Os preços de GPU na nuvem citados são os da Vast.ai e do RunPod em maio de 2026 — spot/on-demand, não reservado. Os preços dos hyperscalers (AWS, GCP, Azure) permanecem 2-3x mais altos.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_o_que_excluí_e_por_que">O que excluí (e por que)</h3> <div class="paragraph"> <p>Excluí intencionalmente as seguintes opções deste benchmark:</p> </div> <div class="ulist"> <ul> <li> <p><strong>API OpenAI / Anthropic / Google</strong>: o assunto aqui é fazer rodar modelos <strong>open-source</strong> que podemos escolher, ajustar finamente, e não depender de um único fornecedor</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="_inferência_simples_a_morte_do_hardware_local">Inferência Simples: A Morte do Hardware Local</h2> <div class="sectionbody"> <div class="paragraph"> <p>Começamos pelo caso de uso mais comum: conversar com um LLM, fazer revisão de código, gerar texto. Sem fine-tuning, sem processamento em lote, apenas inferência interativa.</p> </div> <div class="sect2"> <h3 id="_o_cálculo">O Cálculo</h3> <div class="paragraph"> <p>Um DGX Spark por $4.699. Dividamos pelo custo anual de cada assinatura:</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 Ponto de Equilíbrio — DGX Spark ($4 699) vs Assinaturas rectangle "DGX Spark $4 699" as spark #FFCDD2 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Ponto de Equilíbrio — DGX Spark ($4 699) vs Assinaturas rectangle "DGX Spark $4 699" as spark #FFCDD2 rectangle "Ollama Pro $200/ano" as opro #C8E6C9 rectangle "Claude Pro $240/ano" as cpro #C8E6C9 rectangle "Ollama Max $1 200/ano" as omax #FFF9C4 rectangle "Cloud H100\n$3/h × 10h/sem" 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>O veredicto é brutal. Para inferência :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>: você precisaria<strong>23 anos</strong>para amortizar um DGX Spark. O Spark estará obsoleto há 20 anos.</p> </li> <li> <p><strong>Ollama Max</strong>:<strong>4 anos</strong>— desde que se utilize o Spark 24/7, o que ninguém faz</p> </li> <li> <p><strong>Claude Pro</strong>: mesmo problema,<strong>20 anos</strong>para o single-model fechado</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ A promessa do « supercomputador IA de mesa » esbarra numa realidade contábil elementar : $4 699 / $20 por mês = nunca rentável para uso individual. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_mesmo_com_uso_intensivo">Mesmo com uso intensivo</h3> <div class="paragraph"> <p>Consideremos o pior cenário para a nuvem: você executa um H100 8h/dia, 5 dias/semana, 52 semanas/ano.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2 080 horas/ano</p> </li> <li> <p>2 080 × $2/h (preço médio spot H100) =<strong>$4 160/ano</strong></p> </li> </ul> </div> <div class="paragraph"> <p>O Spark ($4 699) é amortizado em<strong>13 meses</strong>. Mas :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>O H100 é<strong>~10x mais rápido</strong>que o GB10 do Spark. Você faz em 1h o que o Spark faz em 10h. Para o mesmo volume de trabalho, o H100 custa $416/ano, não $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 a 1h de Spark não faz sentido. O H100 faz o trabalho 10x mais rápido. O verdadeiro custo na nuvem para uma carga de trabalho dada é portanto ~10x inferior ao cálculo ingênuo baseado nas horas.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fine_tuning_o_cloud_é_invencível">Fine-Tuning : O Cloud é invencível</h2> <div class="sectionbody"> <div class="paragraph"> <p>O argumento clássico dos defensores do Spark : « sim mas para o fine-tuning, é diferente ».</p> </div> <div class="paragraph"> <p>Não, isso não é.</p> </div> <div class="sect2"> <h3 id="_o_custo_real_de_um_fine_tune">O custo real de um Fine-Tune</h3> <div class="paragraph"> <p>Um fine-tune LoRA/QLoRA no Unsloth de um modelo 7B :</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h em um H100 =<strong>$5 a $9</strong></p> </li> <li> <p>Mesma coisa no Spark =<strong>20-30h</strong>(10 vezes mais lento), bloqueia a máquina</p> </li> </ul> </div> <div class="paragraph"> <p>Com os $4 699 do Spark, você pode financer:</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500 a ~900 fine-tunes</strong>em cloud H100</p> </li> <li> <p>Ou <strong>~23 anos</strong>de Ollama Pro</p> </li> <li> <p>Ou <strong>~4 anos</strong>de Ollama Max</p> </li> </ul> </div> <div class="paragraph"> <p>E para modelos maiores (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 um fine-tune completo, é preciso multi-GPU de qualquer forma — o Spark está fora da corrida</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_os_atores_especializados">Os Atores Especializados</h3> <div class="paragraph"> <p>Em 2026, plataformas como Unsloth, Modal, Replicate e Together AI oferecem fine-tuning serverless :</p> </div> <div class="ulist"> <ul> <li> <p>Sem gestão de GPU</p> </li> <li> <p>Sem configuração de ambiente</p> </li> <li> <p>Pagamento por minuto</p> </li> <li> <p>Otimizações integradas (flash attention, quantização automática)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-90d994cebed893eb8223115d10d5228a.svg" alt="Comparaison des coûts de fine-tuning" width="626" height="244"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_única_verdadeira_razão_a_soberania_dos_dados">A única verdadeira razão: a soberania dos dados</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depois de eliminar a inferência, o fine-tuning, e a relação custo-benefício — o que resta ao Spark ?</p> </div> <div class="paragraph"> <p><strong>A confidencialidade absoluta.</strong></p> </div> <div class="paragraph"> <p>Não é sobre privacidade «não quero que meus prompts sejam lidos por um funcionário da OpenAI». Isso, isso é um problema falso em 2026: Ollama, Groq e a maioria dos provedores respeitáveis têm políticas de zero logs e zero retenção.</p> </div> <div class="paragraph"> <p>A verdadeira confidencialidade é:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Air gap regulamentar</strong>: defesa, diplomacia, saúde — os dados não podem <strong>fisicamente</strong> sair do prédio</p> </li> <li> <p><strong>Dados proprietários críticos</strong>: código-fonte de um produto não publicado, segredos industriais, algoritmos de negociação</p> </li> <li> <p><strong>Resiliência rede</strong>: a IA deve continuar a funcionar mesmo se a Internet cai</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>Mas sejamos honestos: qual a porcentagem dos compradores do DGX Spark que realmente se enquadram nesse caso? 1%? O resto é um « nice to have » transformado em uma despesa de $4 699.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_o_verdadeiro_cálculo_da_confidencialidade">O Verdadeiro Cálculo da Confidencialidade</h3> <div class="paragraph"> <p>Para uso individual:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>($20/mês) + modelos de código aberto chineses = solução pragmática</p> </li> <li> <p>Se um prompt vazar no Ollama, ele se perde nos milhões de solicitações diárias. É uma gota d’água no oceano.</p> </li> <li> <p>O risco real não é a fuga de um prompt — é o treinamento não consentido nos seus dados. E isso, os fornecedores sérios o proíbem contractualmente.</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ O medo de « distillar seu prompt no LLM » é um nível de propagação de informação pessoal tão diluído que se encaixa mais na ansiedade do que na ameaça real. Em escala industrial, é diferente. Mas em escala individual, é ruído. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntese_a_matriz_de_decisão">Síntese: A matriz de decisão</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-8c4f9436c7d0314ed52c5b25b1237a11.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">Critério</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Livre</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 H100 na nuvem</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>Inferência</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">✅ confortável</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅ Exagero</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">�✅ Invencível</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Possível mas lento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Custo 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">Variável (~$416-2 080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 adiantado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Confidencialidade</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Nuvem EUA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Nuvem EUA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Nuvem EUA (variável)</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>Manutenção</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configuração única</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Eletricidade, atualizações</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Obsolescência</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nenhuma</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5 anos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ecossistema de software</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos os modelos abertos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos os modelos open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos modelos open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA (mais 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">prós/pesquisa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Somente air-gap</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Variável conforme volume de trabalho ; com velocidade H100 ~10x > Spark, o custo efetivo para uma carga de trabalho determinada é baixo.</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_o_caso_particular_a_assinatura_pro_face_aos_modelos_chineses">O Caso Particular: A Assinatura Pro Face aos Modelos Chineses</h2> <div class="sectionbody"> <div class="paragraph"> <p>Um ponto merece ser destacado: a combinação<strong>Ollama Pro a $20/mês + modelos chineses de código aberto</strong>É provavelmente a melhor relação custo-benefício da história da IA para o grande público.</p> </div> <div class="sect2"> <h3 id="_por_que_os_modelos_chinos_mudam_tudo">Por que os Modelos Chinos Mudam Tudo</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong>: 1.6T parâmetros, CSA+HCA, 1M contexto, competitivo com Claude 4 e GPT-5 para o código</p> </li> <li> <p><strong>Qwen-3</strong>: 235B, 256K contexto, excelente em francês e em raciocínio</p> </li> <li> <p><strong>GLM-5.1</strong>: 744B, MLA+DSA, 200K contexto, personalizado para o agente</p> </li> </ul> </div> <div class="paragraph"> <p>Todos disponíveis no Ollama. Todos de código aberto (licenças permissivas). Todos utilizáveis sem restrição através de uma assinatura de $20/mês.</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>Com o Ollama Pro, você tem acesso a ~5 modelos « de ponta » de código aberto pelo preço de um único modelo fechado (Claude Pro). O valor é tão assimétrico que quase se torna absurdo.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_o_que_isso_significa_para_o_hardware">O Que Isso Significa para o Hardware</h3> <div class="paragraph"> <p>Se a melhor relação qualidade‑preço for uma assinatura na nuvem de $20 por mês, o hardware local passa a ser uma escolha de <strong>confort</strong> ou de <strong>princípio</strong> — não uma escolha econômica.</p> </div> <div class="paragraph"> <p>Um DGX Spark a $4 699, equivale a :</p> </div> <div class="ulist"> <ul> <li> <p>235 meses de Ollama Pro</p> </li> <li> <p>23 jogos AAA dia de lançamento</p> </li> <li> <p>4 MacBook Air M4</p> </li> <li> <p>Um ano de aluguel de um T2 em Lyon</p> </li> </ul> </div> <div class="paragraph"> <p>Para cálculo. Lento.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_e_huawei">E Huawei?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Já que a pergunta me foi feita durante minhas pesquisas: não, a Huawei não comercializa um equivalente ao DGX Spark.</p> </div> <div class="paragraph"> <p>O 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="_conclusão_o_luxo_da_proximidade">Conclusão: O Luxo da Proximidade</h2> <div class="sectionbody"> <div class="paragraph"> <p>O DGX Spark não é um mau produto. É um mau investimento para 99% dos compradores potenciais.</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 Cenário da IA em 2026 — Quem domina? left to right direction package "Uso Pessoal / PME" #C8E6C9 { rectangle "🏆 Ollama Pro ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Cenário da IA em 2026 — Quem domina? left to right direction package "Uso Pessoal / PME" #C8E6C9 { rectangle "🏆 Ollama Pro $20/mês" as pro rectangle "Ollama Grátis $0/mês" as free rectangle "Spot da GPU em nuvem $1-3/h" as spot } package "Uso Intensivo / Profissional" #FFF9C4 { rectangle "🏆 Ollama Max $100/mês" as max rectangle "�🏆 GPU de nuvem dedicado\n$2-4/h" as dedicated rectangle "Modal / Together AI Serverless" as serverless } package "Air-Gap Obrigatório" #FFCDD2 { rectangle "DGX Spark $4 699" as spark rectangle "Mac Studio M3U\n~$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 um DGX Spark em 2026 é como comprar um servidor de e‑mail em 2010: tecnicamente possível, filosoficamente satisfatório, economicamente absurdo para um indivíduo. </em>_</em></p> </div> <div class="paragraph"> <p>O cálculo é simples, e ele não mente :</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong>para conversar com o DeepSeek no Ollama Free</p> </li> <li> <p><strong>$200/ano</strong>para trabalhar seriamente com Ollama Pro</p> </li> <li> <p><strong>$5-9</strong>para um fine-tune pontual na nuvem GPU</p> </li> <li> <p><strong>$4 699</strong>para…​ a experiência de ter uma caixa NVIDIA na sua secretária?</p> </li> </ul> </div> <div class="paragraph"> <p>O mercado decidiu. As assinaturas em nuvem e os modelos open-source chineses venceram a batalha do preço. O hardware local sobrevive nos nichos regulatórios, não nos escritórios dos desenvolvedores.</p> </div> <div class="paragraph"> <p><em><em>_ O DGX Spark não é uma ferramenta rentável. É uma declaração. « Quero minha IA em casa, não na nuvem de outra pessoa. » É respeitável. Mas em 2026, quando Ollama te dá DeepSeek-V4-Pro na nuvem por $20/mês, é principalmente uma declaração que custa muito caro. </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>Este artigo resulta de uma conversa com meu agente IA sobre a pertinência econômica do DGX Spark, cruzada com uma vigilância de mercado sobre os preços de GPU na nuvem (Vast.ai, RunPod), as tabelas tarifárias Ollama/Claude, e o ecossistema dos modelos chineses de código aberto. Os preços citados são de maio de 2026 — provavelmente ainda terão caído quando você ler estas linhas.</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="#_o_problema_o_prompt_engineering_é_um_castelo_de_areia">O Problema: o Prompt Engineering é um Castelo de Areia</a></li> <li><a href="#_minha_resposta_a_matriz_44">minha resposta: a matriz 4×4</a> <ul class="sectlevel2"> <li><a href="#_as_cinco_zonas_dimensão_espacial_rgpd">As Cinco Zonas (Dimensão Espacial — RGPD)</a></li> <li><a href="#_a_classificação_epistemológica_segunda_dimensão">A Classificação Epistemológica (Segunda Dimensão)</a></li> </ul> </li> <li><a href="#_como_o_llm_consome_esta_matriz">Como o LLM consome esta matriz</a></li> <li><a href="#_implementação_tarefas_gradle_tipadas">Implementação : Tarefas Gradle Tipadas</a></li> <li><a href="#_por_que_é_um_manifesto_não_apenas_uma_spec">Por que é um Manifesto, não apenas uma Spec</a></li> <li><a href="#_a_cascata_completa_do_brain_dump_ao_artigo_do_blog">A Cascata Completa — do Brain Dump ao Artigo do Blog</a></li> <li><a href="#_próscontras">Prós/Contras</a></li> <li><a href="#_conclusão_guarde_seus_arquivos_não_seus_prompts">Conclusão: Guarde seus arquivos, não seus prompts</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">Tempo de leitura: 14 minutes</div> <p>Durante meses, tenho empilhado as regras de governança de agentes. Arquivos EAGER, checklists LAZY, protocolos de encerramento de sessão em seis etapas. E, contudo, uma questão permanecia em suspense: <strong>como o LLM sabe o que ele tem o direito de fazer com um arquivo ?</strong></p> </div> <div class="paragraph"> <p>A resposta não está em um prompt. Ela está no sistema de arquivos.</p> </div> <div class="paragraph"> <p>Aqui está a especificação de arquitetura que torna a resposta utilizável — la <strong>matriz de governança LLM</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_o_prompt_engineering_é_um_castelo_de_areia">O Problema: o Prompt Engineering é um Castelo de Areia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando se dá um arquivo a um LLM, dá-se tudo a ele. O conteúdo, sim — mas também a ausência de barreiras de proteção. O LLM não sabe se esse arquivo contém um segredo, uma opinião especulativa, ou do código fechado. Ele vai indexá-lo, resumi-lo, citá-lo, misturá-lo com outros dados — et potencialmente Publicá-lo em um embedding público ou uma resposta de usuário</p> </div> <div class="paragraph"> <p>O truque clássico, é o 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 tem três problemas :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Ele depende da boa vontade do LLM.</strong> Um modelo suficientemente grande para</p> </li> </ol> </div> <div class="paragraph"> <p>Resolver bugs complexos é grande o suficiente para contornar uma instrução de segurança afogada em 200k tokens de contexto</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>É contextual, não estrutural. Mude o prompt, mude o LLM,</p> </li> </ol> </div> <div class="paragraph"> <p>mude de sessão — e a regra desaparece.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Ele não escala.</strong> Cada novo tipo de arquivo, cada novo nível</p> </li> </ol> </div> <div class="paragraph"> <p>de confidencialidade exige uma nova cláusula. Seu prompt torna-se um texto regulamentar que ninguém lê 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>A segurança de um sistema nunca deve depender de uma instrução que se pode esquecer, contornar, ou não carregar. Ela deve depender de uma barreira que não se pode atravessar sem querer explicitamente.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_minha_resposta_a_matriz_44">minha resposta: a matriz 4×4</h2> <div class="sectionbody"> <div class="paragraph"> <p>A solução que implementei no meu workspace é uma <strong>matriz zona × direito de acesso LLM</strong>. Ela não pede ao LLM que seja prudente. Ela rende a imprudência estruturalmente impossível.</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 A Matriz de Governança LLM — Zona × Direito de Acesso package "Espaço de trabalho" { rectangle "RAIZ (Círculo 0) ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title A Matriz de Governança LLM — Zona × Direito de Acesso package "Espaço de trabalho" { rectangle "RAIZ (Círculo 0) ━━━━━━ Brain dump Pensamento livre [PROIBIDO LLM]" as Z0 #FFB3B3 rectangle "configuration/ (Círculo 1) ━━━━━━ Segredos, tokens Infra privada [PROIBIDO LLM]" as Z1 #FFB3B3 rectangle "office/\n(Círculo 2)\n━━━━━━\nDados editoriais\nArtigos, enquadramentos\n[Visão Filtrada]" as Z2 #FFF3B3 rectangle "foundry/private/ (Círculo 3) ━━━━━━ Code closed source [DATASET PRIVADO]" as Z3 #B3D9FF rectangle "foundry/public/ (Círculo 3) ━━━━━━ Código aberto Apache 2.0 [ACESSO LIVRE]" as Z4 #B3FFB3 } Z0 -[hidden]-> Z1 Z1 -[hidden]-> Z2 Z2 -[hidden]-> Z3 Z3 -[hidden]-> Z4 @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_as_cinco_zonas_dimensão_espacial_rgpd">As Cinco Zonas (Dimensão Espacial — RGPD)</h3> <div class="paragraph"> <p>Cada zona do espaço de trabalho tem um nível de RGPD que determina <strong>onde</strong> o arquivo pode ser roteado :</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">Nível RGPD</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Conteúdo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Direito de acesso público ao RAG</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">raiz</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, conversas LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PROIBIDO</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 — Proprietário restrito</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Segredos, tokens, chaves API</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>proibido</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">Restrito colaborativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Data editorial, enquadramento, formações</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>FILTRADO</strong>— Visão apenas</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 — Aberto condicional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Código fechado, SaaS não público</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PROIBIDO</strong>— conjunto de dados 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>livre</strong>— indexação completa</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>A regra é simples: <strong>o caminho do arquivo determina o que o LLM pode fazer com ele</strong> Não há metadados para manter, não há tag para adicionar no frontmatter, não há classificação manual em cada commit. O arquivo está em`OSS/<code>? É público. Está em`configuration/</code>; Ele é intocável.</p> </div> </div> <div class="sect2"> <h3 id="_a_classificação_epistemológica_segunda_dimensão">A Classificação Epistemológica (Segunda Dimensão)</h3> <div class="paragraph"> <p>A dimensão espacial diz <strong>onde</strong> router. Mas há um segundo eixo, perpendicular : <strong>o que</strong> router. Alguns ficheiros numa zona autorizada contêm informações que não devem ser diluídas assim:</p> </div> <div id="diag-epistemic-filter" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-17d60994fe8990d0ca7c0e782cf8fdf8.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>A grelha de classificação epistemológica, gravada na Regra 2‑bis da minha governança agente :</p> </div> <div class="paragraph"> <p>| Status | Definição | Sinal LLM | Destino | | VISION | Arquitetura estabilizada, padrão testado | Linguagem declarativa, referências sessões/testes | Diluição completa + Blog | | ESTRATÉGIA | Posicionamento negócios, preços | Vocabulário mercado, concorrência | Documentos raiz apenas | | OPINION | Especulação, hipótese não validada | Linguagem hipotética, intuição | Confinamento Círculo 0 |</p> </div> <div class="paragraph"> <p>A combinação das duas dimensões — zona física × classificação epistemológica — forma a<strong>matriz completa</strong> :</p> </div> <div id="diag-full-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-a4dca1e1342127dee30a4086926815bc.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="_como_o_llm_consome_esta_matriz">Como o LLM consome esta matriz</h2> <div class="sectionbody"> <div class="paragraph"> <p>A matriz não é um documento que o LLM lê. É uma <strong>restrição</strong> implicita** codificada no vetor composto de contexto (EPIC 9 — em curso de implementação).</p> </div> <div class="paragraph"> <p>Aqui está o que o LLM recebe em cada sessão:</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, quando o LLM me diz :</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>O metadado da zona responde mesmo antes de o LLM terminar sua frase : <code>edster/`está em`CSS/</code>, nível 3 →<strong>acesso proibido ao knowledge graph público</strong> O RAG não o vê. O grafo não o toca. A resposta do usuário não não o 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>A ontologia espacial funciona como uma<strong>permissão Unix</strong>para os LLMs. Você não pede a um processo para ser cuidadoso com`/etc/shadow`— você lhe nega acesso à leitura. Mesmo princípio.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_implementação_tarefas_gradle_tipadas">Implementação : Tarefas Gradle Tipadas</h2> <div class="sectionbody"> <div class="paragraph"> <p>A matriz não é uma filosofia. É código. Aqui está o contrato da tarefa Gradle que o 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>A tarefa é <strong>testable</strong>. Você pode escrever um teste 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 testes, 380 PASS. Assim como para o plugin plantuml-gradle — a segurança é testada, não esperada.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_é_um_manifesto_não_apenas_uma_spec">Por que é um Manifesto, não apenas uma Spec</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este documento é uma especificação de arquitetura porque define :</p> </div> <div class="ulist"> <ul> <li> <p>uns<strong>dimensões</strong>(espacial, epistemológico)</p> </li> <li> <p>de<strong>regras determinísticas</strong>(zone → direito de acesso)</p> </li> <li> <p>Un <strong>contrato de tarefa</strong>(Gradle tipado, testável)</p> </li> <li> <p>Uma<strong>implementação de referência</strong>(meu espaço de trabalho)</p> </li> </ul> </div> <div class="paragraph"> <p>Mas também é um<strong>manifesto</strong>porque toma posição em um debate maior : <strong>como governar o acesso de um LLM a dados ?</strong></p> </div> <div class="paragraph"> <p>A resposta da indústria é o prompt engineering + os guardrails<br> os classificadores pós-hoc. Minha resposta é: <strong>guarde seus arquivos em Os bons arquivos.</strong> O resto é 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 manifesto não diz "os LLMs devem ser alinhados". Ele diz: "o alinhamento de um LLM sobre suas regras de segurança é uma consequência de seu sistema de arquivos, não do seu prompt.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_a_cascata_completa_do_brain_dump_ao_artigo_do_blog">A Cascata Completa — do Brain Dump ao Artigo do Blog</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para ilustrar o ciclo completo, aqui está como essa ideia de matriz nasceu e foi diluída :</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>O que começou como uma observação em sessão("ei, o RAG não sabe que edster est closed source") tornou-se uma especificação de arquitetura Publicada em menos de uma sessão. Este é o padrão STIMULUS em ação.</p> </div> </div> </div> <div class="sect1"> <h2 id="_próscontras">Prós/Contras</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">Esta Abordagem (Ontologia Espacial + Matriz)</th> <th class="tableblock halign-left valign-top">A Abordagem Clássica (Prompt + Guardrails)</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Mecânica* — o sistema de arquivos bloqueia o acesso, não o LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Declarativa</strong> — o prompt pede ao LLM que seja prudente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Testable</strong> — o contrato de tarefa Gradle é verificado por 380+ testes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Não testável</strong> — "O LLM respeitou a regra?" é uma questão aberta</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Independente do LLM</strong> — mude de modelo, as pastas permanecem</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Dependente do LLM</strong> — cada modelo interpreta o prompt de forma diferente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Escalável</strong> — novo tipo de dados = nova pasta, zero alteração de código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non scalable</strong> — novo tipo de dado = nova cláusula de prompt, novo risco de regressão</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Auditable</strong> — o sistema de arquivos é o rastro de auditoria</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Não auditável</strong> — o prompt não tem histórico, não tem diff, não tem blame</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Restrição</strong>: exige uma disciplina de organização inicial</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Restrição</strong> : exige uma disciplina de redação de prompt a cada sessão</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusão_guarde_seus_arquivos_não_seus_prompts">Conclusão: Guarde seus arquivos, não seus prompts</h2> <div class="sectionbody"> <div class="paragraph"> <p>A matriz de governança LLM que acabo de descrever não é um produto. É uma<strong>especificação de arquitetura</strong>— e é por isso que ela está publicável.</p> </div> <div class="paragraph"> <p>O que a torna robusta é que ela não pede nada ao LLM. Ela não lhe Ela não confia. Ela não se baseia em seu alinhamento, sua compreensão. do francês, ou sua boa vontade. Ela se baseia no sistema de arquivos — A camada mais baixa, a mais estável, a mais testada de toda a pilha.</p> </div> <div class="paragraph"> <p>Quando eu digo ao meu LLM "você pode indexar tudo em`OSS/<code>, nada em `configuration/</code>, et `office/`apenas se for classificado Vision não é uma instrução. É um <strong>filtro</strong> — implementado em Kotlin, Verificado por 380 testes, executado antes de que o LLM veja os dados.</p> </div> <div class="paragraph"> <p>É a diferença entre dizer a alguém "não olhe nessa gaveta E fechar a gaveta à chave. A governança agente que estou construindo desde meses são a chave. A matriz é o plano do móvel.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — O Compartimentação Epistêmica Automatizada</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Artigo 0114 — Os Círculos de Confiança e a Ontologia Espacial</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Governar um Agente IA com o AsciiDoc</a></p> </li> <li> <p><a href="../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html">Artigo 0115 — O 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="#_o_acidente_que_esperava_acontecer">O acidente que esperava acontecer</a> <ul class="sectlevel2"> <li><a href="#_a_verdadeira_pergunta">A Verdadeira Pergunta</a></li> </ul> </li> <li><a href="#_a_solução_oss_e_css">A Solução: OSS/ e CSS/</a></li> <li><a href="#_por_que_oss_e_css_e_não_public_e_private">Por que "OSS" e "CSS" e não "Public" e "Private</a> <ul class="sectlevel2"> <li><a href="#_a_árvore_completa_quatro_zonas_não_três">A Árvore Completa — Quatro Zonas, Não Três</a></li> </ul> </li> <li><a href="#_o_caso_particular_cheroliv_com">O Caso Particular : cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_bakery_gradle_não_liga">bakery-gradle não liga</a></li> </ul> </li> <li><a href="#_impacto_sobre_o_agente_de_governança">Impacto sobre o Agente de Governança</a></li> <li><a href="#_o_que_se_ganha_e_o_que_se_perde">O Que Se Ganha (E O Que Se Perde)</a></li> <li><a href="#_conclusão_o_sinal_físico_bate_o_sinal_de_software">Conclusão: o sinal físico bate o sinal de software</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 10 minutes</div> <p><code>foundry/</code>— a zona funcional que hospeda o código do meu workspace — contém 18 projetos. Oito são código aberto sob a licença Apache 2.0. Apenas um é closed source — o SaaS Edster. Durante meses, esses nove projetos coabitaram. na mesma pasta, separados apenas por…​ nada. O status público/privado deles era uma informação na minha cabeça, não no sistema de arquivos.</p> </div> <div class="paragraph"> <p>E então eu quis conectar um RAG. E aí, tudo desabou.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_acidente_que_esperava_acontecer">O acidente que esperava acontecer</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em abril de 2026, comecei a implementar o RAG pgvector para slider-gradle. O princípio: indexar todos os repositórios de`foundry/<code>, produzir de embeddings, e injetá‑los no contexto do LLM para que ele tenha uma perception" do dossier`foundry/</code>.</p> </div> <div class="paragraph"> <p>O pipeline era simples:</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>Simples. Eficaz. E<strong>perigoso</strong>.</p> </div> <div class="paragraph"> <p>Porque este`fileTree`não distingue entre`plantuml-gradle/` (Apache 2.0, public) e`edster/`(closed source, private). Ele engole tudo. E se um dia eu publicar estes embeddings — num dashboard, numa resposta LLM, em um conjunto de dados de treinamento — o código proprietário da Edster está vazando.</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>O problema não é que um LLM leia código fechado. O problema, é que esse código termine em um embedding vetorial <strong>público</strong> — irreversível, não removível, não auditável.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_a_verdadeira_pergunta">A Verdadeira Pergunta</h3> <div class="paragraph"> <p>Não é "como impedir que o LLM vazeie código?". É "como tornar a fuga estruturalmente impossível ?</p> </div> <div class="paragraph"> <p>A resposta não é um prompt. A resposta, é de cortar o dossier em dois.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_oss_e_css">A Solução: OSS/ e 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>Apó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`torna-se :</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>O RAG público nunca vê`CSS/`. O código fechado alimenta um dataset privado de ajuste fino — um modelo interno que nunca sai da minha casa separação é mecânica, não declarativa.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_oss_e_css_e_não_public_e_private">Por que "OSS" e "CSS" e não "Public" e "Private</h2> <div class="sectionbody"> <div class="paragraph"> <p>A escolha dos acrônimos OSS (Open Source Software) e CSS (Closed Source Software) é deliberado:</p> </div> <div class="ulist"> <ul> <li> <p>Public"/"Private" descreve o<strong>visibilidade</strong>(o que o GitHub vê)</p> </li> <li> <p>OSS"/"CSS" descreve a<strong>natureza</strong>do código (o que o LLM deve saber)</p> </li> </ul> </div> <div class="paragraph"> <p>A visibilidade do GitHub é um metadado do repositório remoto. A natureza do código é O LLM não tem acesso à API do GitHub — mas ele tem acesso ao sistema de arquivos.<code>CSS/`ele disse "atenção, este código não está sob licença livre" sem precisar ler um`LICENSE`ou analisar um`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>O nome da pasta é o metadado mais robusto que você pode dar a um LLM. Ela não pode ser mal analisada, ignorada, ou mal interpretada. O LLM vê`CSS/edster/`no caminho do arquivo — ele sabe</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_a_árvore_completa_quatro_zonas_não_três">A Árvore Completa — Quatro Zonas, Não Três</h3> <div class="paragraph"> <p>A granularização OSS/CSS complementa a ontologia de três zonas. A zona `foundry/`passa de 1 para 2 subzonas funcionais :</p> </div> <div id="diag-four-zone-workspace" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-472f6392b3896db2716782e1dca49bcd.svg" alt="L’organisation de foundry/ en deux sous-zones OSS et CSS" width="1751" height="5763"> </div> </div> <div class="paragraph"> <p>| Zone | RGPD | Indexação RAG pública | Ajuste fino do dataset | | Raiz | Nível 0 — Íntimo | ✗ | ✗ | | <code>configuration/</code>| Nível 1 — Restrito | ✗ | ✗ | | <code>office/</code>| Nível 2 — Colaborativo | ✓ Filtrado | ✓ Filtrado | |<code>foundry/private/</code>| Nível 3 — Abertura condicional | ✗ | ✓ Privado | (blank)`foundry/public/`Nível 4 — Público nativo | ✓ Livre | ✓ Público</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_o_caso_particular_cheroliv_com">O Caso Particular : cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>Enquanto estava lá, corriji outra incoerência. Meu site <code>cheroliv.com`morava em`foundry/`como um projeto de software de pleno direito — com seu próprio build Gradle, sua própria CI, sua própria governança</code>.agents/`.</p> </div> <div class="paragraph"> <p>Mas os artigos de blog não são código. São <strong>dados</strong> editoriais** de Cercle 2 — da mesma forma que os enquadramentos de`office/pilotage/` ou as formações 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>O que muda :</p> </div> <div class="ulist"> <ul> <li> <p>Os artigos estão em`office/`→ confidencialidade do Círculo 2</p> </li> <li> <p>A tarefa`publishSite`torna-se uma capacidade de`engine`</p> </li> </ul> </div> <div class="paragraph"> <p>via`bakery-gradle`— o plugin recebe um`FileTree`, ele não sabe que os artigos venham de`office/`</p> </div> <div class="ulist"> <ul> <li> <p>Um único CI, uma única governança — zero duplicação</p> </li> <li> <p>O classificador Vision/Opinion (Regra 2bis) aplica-se automaticamente:</p> </li> </ul> </div> <div class="paragraph"> <p>os artigos em`office/`são filtrados antes da publicação</p> </div> <div class="sect2"> <h3 id="_bakery_gradle_não_liga">bakery-gradle não liga</h3> <div class="paragraph"> <p>E é isso que é bonito. O plugin`bakery-gradle`não foi modificado. Ele recebe um diretório de conteúdo AsciiDoc, ele gera HTML, ele faz push no GitHub Pages. Que esse diretório se chame`site/jbake/content/` ou <code>office/sites/cheroliv/</code>— o plugin não se importa.</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>O contrato de interface é uma tarefa Gradle. Não é uma API REST. Não é um webhook. Uma tarefa — tipada, testável, executável localmente e na CI.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_impacto_sobre_o_agente_de_governança">Impacto sobre o Agente de Governança</h2> <div class="sectionbody"> <div class="paragraph"> <p>A granularização OSS/CSS altera a governança do agente em três pontos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RAG public</strong> : o perímetro de indexação passa de`foundry/**`</p> </li> </ol> </div> <div class="paragraph"> <p>à <code>foundry/public/<strong></code>+<code>office/Vision/</strong></code>. O código closed source é excluído do índice por configuração de tarefa, não por prompt.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Knowledge Graph</strong> : o graphify-gradle produz dois grafos :</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>office/graph.json</code>(public) — relações entre artefatos OSS + office/Vision *<code>configuration/graph_private.json</code>(gitignored, privado) — relações entre artefatos CSS, nunca publicado</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>ajuste fino do conjunto de dados</strong> :`codebase-gradle`agora tem duas fontes :</p> </li> </ol> </div> <div class="paragraph"> <p>*<code>OSS/</code>→ datasets públicos (modelos comunitários, benchmarks) *<code>CSS/</code>→ datasets privados (modelo interno, fine-tuning proprietário)</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_se_ganha_e_o_que_se_perde">O Que Se Ganha (E O Que Se Perde)</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 (pasta plana)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Depois (OSS/CSS + office/sites)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/</code>→ mistura público/privado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/public/</code>→ tudo é publicável</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexa tudo sem discriminação</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">Impossível saber se um projeto é open source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O caminho`OSS/` ou `CSS/`o dito</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com tem sua própria CI, sua própria governança</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A CI e a governança são mutualizadas no engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os artigos de blog estão em um repositório "code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os artigos do blog estão em`office/sites/`— dados, não código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Risco de vazamento de código fechado em embeddings públicos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estruturalmente impossível —`CSS/`fora do escopo RAG</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O único custo : um`git mv`global sobre os 17 repositórios OSS + um refatoramento do <code>build.gradle.kts</code> de <code>engine</code>. É uma migração a frio Sem dados em voo, nenhum usuário impactado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_sinal_físico_bate_o_sinal_de_software">Conclusão: o sinal físico bate o sinal de software</h2> <div class="sectionbody"> <div class="paragraph"> <p>O que eu fiz nesta tarde foi substituir uma convenção invisível por uma separação visível na zona`foundry/<code>. Antes, você tinha que <strong>saber</strong> que`edster/`era closed source. Agora você <strong>vê</strong> — o dossiê se chama`CSS/</code>.</p> </div> <div class="paragraph"> <p>É o mesmo princípio que as permissões Unix, os VLAN de rede, ou os compartimentos à prova de fogo em uma base de dados. A segurança não deve ser uma informação que você deve reter. Ela deve ser uma propriedade <strong>física</strong>do sistema.</p> </div> <div class="paragraph"> <p>A granularização OSS/CSS é a tradução deste princípio no domínio da governança LLM. O LLM não precisa saber que o Edster é Confidencial. Ele precisa ser incapaz de indexá-lo.</p> </div> <div class="paragraph"> <p>E isso é exatamente o que`CSS/`garante.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0118_matrice_gouvernance_llm_zone_acces_workspace_post.html">Artigo 0117 — A Matriz de Governança LLM</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Artigo 0114 — Os Círculos de Confiança</a></p> </li> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Artigo 0116 — O Compartimentamento Epistêmico Automatizado</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Artigo 0108 — Governar um agente de IA com 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="#_o_problema_pensar_livremente_sem_publicar_qualquer_coisa">O Problema: Pensar Livremente sem Publicar Qualquer Coisa</a></li> <li><a href="#_o_padrão_stimulus_nascer_fixar_diluir_morrer">O padrão STIMULUS — nascer, fixar, diluir, morrer</a></li> <li><a href="#_a_delegação_ao_llm_por_que_o_llm_é_quem_filtra">A Delegação ao LLM: Por que o LLM é quem filtra</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 10 minutes</div> <p>Meu LLM não se limita a executar minhas tarefas Gradle. Ele é o guardião da fronteira entre meu pensamento privado e minha expressão pública. Cada ideia é classificada — Visão, Opinião, Estratégia — antes de ser encaminhada. Eis como esse compartimentamento epistemológico automatizado protege meu jardim mental sem me calar.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_pensar_livremente_sem_publicar_qualquer_coisa">O Problema: Pensar Livremente sem Publicar Qualquer Coisa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando um desenvolvedor solo documenta seu processo de pensamento com um LLM, ele se depara com um paradoxo:</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 esses dois extremos, há um<strong>filtro</strong>. A pergunta é: quem faz isso? Um humano cansado no final da sessão? Um script de regex ingênuo? Ou o próprio LLM, que já leu tudo?</p> </div> <div class="paragraph"> <p>Minha resposta: o LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_padrão_stimulus_nascer_fixar_diluir_morrer">O padrão STIMULUS — nascer, fixar, diluir, morrer</h2> <div class="sectionbody"> <div class="paragraph"> <p>O STIMULUS é um arquivo`.adoc`temporário na raiz do workspace (Círculo 0). Seu nome segue uma convenção evocativa —<code>PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code>— que captura a intenção exploratória do momento.</p> </div> <div class="paragraph"> <p>Seu ciclo de vida é implacável :</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>Um estímulo que sobrevive a mais de 2 sessões sem diluição é um anti-padrão. Ou a informação é muito importante para apodrecer em um arquivo temporário (→ diluir), ou ela é muito vaga para merecer existir (→ excluir).</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_delegação_ao_llm_por_que_o_llm_é_quem_filtra">A Delegação ao LLM: Por que o LLM é quem filtra</h2> <div class="sectionbody"> <div class="paragraph"> <p>Não faço hardcode da classificação Vision/Opinion em Kotlin. Eu a injeto no<strong>prompt do sistema</strong>do 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 ---- O LLM lê esta diretiva**antes**de tratar a sessão. Ela está em seu contexto imediato, não em um arquivo separado. É de *prompt engineering determinístico*: o comportamento surge do texto injetado, não de um classificador externo. === Por que Funciona — e Por que é Contra-intuitivo A reação padrão : « Tu confias a classificação à IA ? E se ela errar ? Resposta: o ser humano não faz melhor às 2h da manhã. A diferença, é que o LLM, ele, lê TUDO. Ele tem o contexto completo da sessão e dos documentos-alvo. Ele sabe que`VPS ECO-16 12€ HT`é uma decisão de infraestrutura (VERSION) enquanto`« le TTS ElevenLabs sonne plus naturel que Coqui »`é uma opinião não verificada por um benchmark. O ser humano, no final da sessão, lê na diagonal e faz o melhor que pode. O LLM lê exaustivamente e aplica uma grade sistemática. O resultado é**mais confiável**, não menos. E para os 20% de casos ambíguos — a zona cinzenta onde mesmo o LLM hesita — a resposta não é « adicionar código ». A resposta é**LangGraph4j**(EPIC 13) : um grafo de estado que, para os casos ambíguos, ativa um nó Human-in-the-Loop e eleva ao humano para decisão. Mas para os 80% de casos claros, o LLM basta. == O Furo Completo: do Brain Dump ao Blog Post Segue o fluxo completo — da ideia bruta ao artigo publicado — com o 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 ---- O desenvolvedor não escreve o artigo. Ele desafia, relê, valida. O LLM escreve. O loop é : 1. Brain dump livre → sem censura 2. Classificação epistêmica pelo LLM → sem vazamento 3. Redação pelo LLM → sem procrastinação 4. Revisão humana → sem erro O gargalo histórico — « não tenho tempo para escrever » — foi eliminado. O LLM faz o grosso do trabalho. O ser humano faz o que só o ser humano pode fazer : julgar. == Os Três Documentos Racine — Como a Informação Encontra Seu Lugar Cada documento alvo tem um papel específico na cascata de diluição : [cols="1,3,2"] |=== |Documento |O que ele recebe |Tipo de conteúdo |`WORKSPACE_AS_PRODUCT.adoc` |Decisões arquiteturais, pilha técnica, mapa de rota, modelo de negócio |VISÃO + ESTRATÉGIA |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |padrões, lições, anti-padrões, ontologie, regras formais |VISION (padrões testados) |`WORKSPACE_VISION.adoc` |Contexto da sessão, histórico das decisões, pontos de infraestrutura |VISÃO + ESTRATÉGIA (contexto) |`AGENT_GOVERNANCE.adoc` |Regras de governança, portfólio de projetos, procedimentos |VISÃO (governança) |**Blog cheroliv.com** |Artigos públicos, valor para o leitor externo |VISÃO apenas |=== Um mesmo estímulo pode alimentar os 4 documentos + o blog — cada destino recebe a parte que lhe corresponde, sem redundância, sem contradição. É o que aconteceu para`PICTURE_ME_ROLLIN.adoc`(3 maio 2026) : | Informação | Classificação | Destinos | | Inventário dos 13+ projetos foundry/ | VISION | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 8,49€/mês | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | O mercado africano está pronto para o mobile money » | ESTRATÉGIA | WORKSPACE_AS_PRODUCT (seção de negócios) | « DeepSeek > Kimi > GLM para contexto longo » | OPINIÃO → VISÃO | Confinado e depois promovido após benchmark (artigo 0112) | | Funcionário Sintético como produto final | ESTRATÉGIA | WORKSPACE_AS_PRODUCT (sem blog) | == O Padrão Baby-Step + TestContainer + Documento Vivo — o Código que se testa a si mesmo O padrão STIMULUS/Dilution gerencia o pensamento. Seu equivalente para o código é o padrão Baby-Step/TestContainer/Doc Vivo, validado pelo plantuml-gradle (380/380 testes PASS, 137 sessões sem vazamento Docker): [cols="1,3"] |=== |Princípio |Regra |**Passo de bebê** |Nunca mais de 3 pts por US. Se uma US assustar, dividir. Uma US de 1 pt que passa > uma US de 8 pts que arrasta. |**TestContainer primeiro** |Antes do código de negócio, o contêiner. O teste de infra passa → ambiente estável garantido. |**Dataset comitê** |Subconjunto mínimo porém representativo em`src/test/resources/`, sem PII. Clonável, lançável. |**documentação viva** |Cada teste Cucumber = uma frase em linguagem natural. O código-fonte É a especificação executável. Zero documentação Markdown para manter. |**Limpeza automática** |Zero vazamento de recursos. Contêineres órfãos,`/tmp/gradle-test-*`Tudo está limpo. |=== Este padrão é a razão pela qual o plantuml-gradle nunca teve uma regressão Docker em 138 sessões. Ele garante que o código que fala com uma infraestrutura externa (PostgreSQL, Redis, Kafka) seja sempre testado em um ambiente idêntico ao da produção — versionado, reproduzível e lançável com um único comando. == Conclusão: A Liberdade de Pensar sem o Medo de Publicar O compartimentamento epistemológico automatizado não é uma ferramenta de censura. É um**libertador**. Ele permite pensar livremente, especular sem filtro, despejar tudo o que passa pela cabeça — sem jamais temer que uma ideia embrionária apareça no blog. O LLM é o guardião dessa fronteira. Ele lê tudo. Ele classifica. Ele dilui o que merece sobreviver. Ele confina o que deve permanecer privado. Ele redige o que é publicável. E o desenvolvedor, ele, tem a última palavra: reler, desafiar, validar. Julgar. É a divisão do trabalho que faltava ao desenvolvedor solo: um empregado sintético que cuida da burocracia mental, para que o ser humano possa se concentrar no que faz de melhor — projetar, arquitetar, decidir. == Referências * Artigo sobre a governança do agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governar um Agente IA com AsciiDoc] * Artigo sobre ontologia espacial e os círculos de confiança :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[A Ontologia Espacial como Mecanismo de Alinhamento] * Artigo sobre o Anonimizador MVP0 :link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Nosso Primeiro Funcionário: o Anonimizador de Datasets] * Artigo sobre a comparação de LLMs longo contexto :link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * Artigo sobre o mecanismo do agente de backup:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window e Onda Fria] ----</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="#_o_problema_que_faz_fugir_todo_o_mundo">O Problema que Faz Fugir Todo o Mundo</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 12 minutes</div> <p>Não contrato um LLM. Contrato um anonimizador. Antes de fazer <code>RAG pgvector</code>, antes de fazer fine-tuning de especialistas <code>CDA/FPA</code>, antes de provisionar workspaces de clientes — alguém deve limpar os banheiros dos dados. Este funcionário é o especialista em anonimização (<code>MVP0</code>, <code>EPIC 2</code> de <code>codebase-gradle</code>). E é ele quem torna o produto comercializável.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_que_faz_fugir_todo_o_mundo">O Problema que Faz Fugir Todo o Mundo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Toda startup de IA que manipule dados de treinamento bate no mesmo 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: ou você faz RAG em dados sujos (alucinações de PII, não conformidade com GDPR, risco jurídico), ou você não faz nada (sem produto). A terceira via — limpar manualmente — não é escalável. Minha resposta: não contornar o problema. L'**automatizar**. == MVP0: O Anonimizador, Primeiro Contratado no Período de Experiência O MVP0 não é uma funcionalidade. É um**especialista em conveniência**— um funcionário que faz o trabalho sujo, estúpido e malvado, e que ninguém quer falar nos pitch decks. O que ele faz: [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 ---- Ele detecta os padrões mais óbvios primeiro (e-mails`.*@.*`, tokens`sk-*`, `ghp_*`, IPs), então ele aprende. O período de teste, isso é: validamos que ele não deixa passar falsos negativos antes de efetivá-lo. == O que esse MVP desbloqueia (e não é apenas a conformidade) A anonimização como MVP0 não é o pedágio RGPD antes da autoestrada. É a própria autoestrada. Veja o que ela abre: === Presente: Realidade Aumentada em 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 ---- O RAG não procura em dados sujos — ele procura em um espaço**limpo por construção**Isso muda tudo para a qualidade das respostas: o LLM não perde tempo a contornar PII que ele reconhece, mas que não deve mencionar. === Futuro : Fine-Tuning em Dados Saudáveis [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) ---- O fine-tuning em dados brutos é uma catástrofe jurídica em potencial. Em dados limpos, é uma**método reprodutível**. Cada cliente acumula os seus conjuntos de dados limpos, cada cliente pode afinar os seus especialistas de negócio nos seus dados — sem nunca expor um dado pessoal. == Por que é vendável Não é « uma ferramenta de conformidade GDPR ». É uma**Método reprodutível que transforma um problema universal em ativo**: 1. *Toda empresa de formação tem dados sujos* — isso é o problema 2. *Nenhuma tem um pipeline automatizado de limpeza multi-fonte*—é o mercado 3. *O ciclo: anonimização → RAG → fine-tuning é proprietário* — é a barreira O SaaS Edster (MVP3) não venderá « um workspace Gradle ». Ele venderá esse loop fechado. E o MVP0 é a porta de entrada. == O Formato SQL como Terceira Via de Contexto A importação de dados estruturados não é apenas um formato de troca. O esquema SQL (DDL) leva o**modelo de entidade-relacionamento do domínio**: [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, uma vez anonimizado (linha 4), torna-se uma fonte de contexto para o LLM. Não é texto — do**modelo de negócio**. O RAG fornece o conteúdo (similaridade vetorial), Graphify fornece as relações (estrutura exata), e o esquema SQL fornece o**Design orientado por domínio implícito**: contextos delimitados, agregados, objetos de valor. O LLM compreende o negócio porque ele lê seu esquema. == A Roadmap: do MVP0 ao 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 do anterior. Nenhum pode ser entregue sem o MVP0. Esta é a razão pela qual o Anonimizador não é « P0 » no backlog — ele é**MVP0**. É o primeiro entregável comercial, e tudo o resto está condicionado ao seu sucesso. == Conclusão: o Trabalho Invisível que Torna Tudo Possível Em uma startup clássica, a limpeza de dados é terceirizada, manual ou ignorada. Nesta arquitetura, é o**coração do produto**. O Anonimizador é o primeiro empregado porque, sem ele, nada funciona: * Sem MVP0 → não há RAG legal (MVP1) * Sem MVP0 → sem fine-tuning sem vazamento de dados (EPIC 5) * Sem MVP0 → não há SaaS credível (MVP3) * Sem MVP0 → não há realidade aumentada no prompt * Sem MVP0 → não há terceira via de contexto (SQL DDD) Ele faz o trabalho sujo. Nunca será citado nos pitches. Mas é ele quem faz a fábrica funcionar. E é por isso que ele/ela é contratado primeiro. == Referências * Artigo sobre a ontologia espacial e os círculos de confiança :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[A Ontologia Espacial como Mecanismo de Alinhamento] * Artigo sobre o agente de governança Eager/Lazy:link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governar um agente de IA com AsciiDoc] * Artigo sobre o mecanismo Hot/Warm/Cold:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Janela deslizante e onda fria] * Artigo sobre a comparação dos três 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="#_o_problema_que_faz_todo_mundo_fugir">O problema que faz todo mundo fugir</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 12 minutes</div> <p>Não contrato um LLM. Contrato um anonimizador. Antes de fazer o RAG pgvector, antes de afinar os especialistas CDA/FPA, antes de provisionar os workspaces dos clientes — alguém precisa limpar o banheiro dos dados. Esse funcionário é o especialista em anonimização (MVP0, EPIC 2 do código-base gradle). E é ele que torna o produto vendável.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[empty string]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_que_faz_todo_mundo_fugir">O problema que faz todo mundo fugir</h2> <div class="sectionbody"> <div class="paragraph"> <p>Qualquer startup de IA que manipula dados de treinamento se depara com o mesmo 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: ou você faz RAG em dados sujos (alucinações de PII, não conformidade GDPR, risco jurídico), ou você não faz nada (sem produto). A terceira via — limpar à mão — não é escalável. Minha resposta: não contornar o problema. O**automatizar**. == MVP0 : O Anonimizador, Primeiro Contratado em Período de Experiência O MVP0 não é uma funcionalidade. É um**especialista de conveniência**— um funcionário que faz o trabalho sujo, estúpido e malévolo, e que ninguém quer falar nos pitch decks. O que ele faz : [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 ---- Ele detecta os padrões mais óbvios primeiro (emails`.*@.*`, tokens`sk-*`, `ghp_*`, IPs), então ele aprende. O período de teste, isso é: validamos que ele não deixa passar falsos negativos antes de o titularizar. == O Que Este MVP Desbloqueia (e Não é Apenas Conformidade) A anonimização como MVP0 não é o pedágio RGPD antes da autoestrada. É a própria autoestrada. Aqui está o que ela abre: === Presente: Realidade Aumentada em 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 ---- O RAG não busca em dados sujos — ele busca em um espaço**limpo por construção**. Mudar isso muda tudo para a qualidade das respostas: o LLM não perde tempo contornando PII que reconhece, mas que não deve mencionar. === Futuro : Fine-Tuning em Dados Saudáveis [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) ---- O fine-tuning em dados brutos é uma catástrofe jurídica em potencial. Em dados limpos, é uma**método reprodutível**. Cada cliente acumula seus datasets limpos, cada cliente pode ajustar finamente seus especialistas de negócio nos seus dados — sem nunca expor um dado pessoal. == Por que isso é mercadável Não é « uma ferramenta de conformidade com o RGPD ». É uma**método reprodutível que transforma um problema universal em ativo**: 1. *Toda empresa de treinamento tem dados sujos* — esse é o problema 2. *Nenhuma tem um pipeline automatizado de limpeza multi-fonte* — é o mercado 3. *O ciclo : anonimização → RAG → ajuste fino é proprietário* — é a barrière O SaaS Edster (MVP3) não venderá « um workspace Gradle ». Ele venderá esse loop fechado. E o MVP0 é a porta de entrada. == O Formato SQL como Terceira Via de Contexto A importação de dados estruturados não é apenas um formato de troca. O esquema SQL (DDL) carrega o**modelo entidade-relacionamento do domínio**: [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, uma vez anonimizado (linha 4), torna-se uma fonte de contexto para o LLM. Não é texto —**modelo de negócio**. O RAG fornece o conteúdo (similaridade vetorial), Graphify fornece as relações (estrutura exata), e o esquema SQL fornece o**Domain-Driven Design implícito**: bounded contexts, agregados, value objects. O LLM compreende o negócio porque ele lê seu esquema. == Roadmap: do MVP0 ao 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 do anterior. Nenhum pode ser entregue sem o MVP0. Esta é a razão pela qual o Anonymiseur não é « P0 » no backlog — ele está**MVP0**. É o primeiro entregável comercial, e tudo o resto está condicionado ao seu sucesso. == Conclusão: o trabalho invisível que torna tudo possível Em uma startup clássica, a limpeza de dados é terceirizada, manual ou ignorada. Nesta arquitetura, é o**coração do produto**. O Anonimizador é o primeiro empregado porque sem ele, nada funciona : * Sem MVP0 → não há RAG legal (MVP1) * Sem MVP0 → sem ajuste fino sem vazamento de dados (ÉPICO 5) * Sem MVP0 → sem SaaS credível (MVP3) * Sem MVP0 → sem realidade aumentada em prompt * Sem MVP0 → não há terceiro caminho de contexto (SQL DDD) Ele faz o trabalho sujo. Ele nunca será mencionado nos pitches. Mas é ele quem faz a fábrica funcionar. É por isso que o contratamos primeiro. == Referências * Artigo sobre ontologia espacial e círculos de confiança :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[A Ontologia Espacial como Mecanismo de Alinhamento] * Artigo sobre a governança do agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governar um agente IA com AsciiDoc] * Artigo sobre o mecanismo Hot/Warm/Cold:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Janela Deslizante e Onda Fria] * Artigo sobre a comparação dos três 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="#_o_constato_prompt_engineering_é_um_castelo_de_areia">O Constato : Prompt Engineering é um Castelo de Areia</a></li> <li><a href="#_os_quatro_círculos_de_confiança_uma_ontologia_espacial">Os Quatro Círculos de Confiança : uma Ontologia Espacial</a> <ul class="sectlevel2"> <li><a href="#_o_jardim_secreto_o_espaço_fora_cvs">O Jardim Secreto: o Espaço Fora-CVS</a> <ul class="sectlevel3"> <li><a href="#_o_gitignore_como_configuração_de_governança">O <code>.gitignore</code> como Configuração de Governança</a></li> <li><a href="#_o_mecanismo_de_snapshot">O Mecanismo de Snapshot</a></li> </ul> </li> <li><a href="#_o_cofre_fort_configuration_como_spring_cloud_config">O Cofre-Fort : <code>configuration/</code> como Spring Cloud Config</a></li> <li><a href="#_a_biblioteca_office_como_dados_consumíveis">A Biblioteca: <code>office/</code> como Dados Consumíveis</a></li> <li><a href="#_as_forjas_foundry_como_implementação">As Forjas: <code>foundry/</code> como implementação</a></li> </ul> </li> <li><a href="#_próscontras_alinhamento_espacial_vs_alinhamento_por_prompt">Prós/Contras : Alinhamento Espacial vs Alinhamento por Prompt</a> <ul class="sectlevel2"> <li><a href="#_abordagem_clássica_alinhamento_por_pré_prompt">Abordagem Clássica: Alinhamento por Pré-Prompt</a></li> <li><a href="#_esta_abordagem_alinhamento_por_ontologia_espacial">Esta Abordagem : Alinhamento por Ontologia Espacial</a></li> </ul> </li> <li><a href="#_álgebra_relacional_do_workspace_e_o_observável_delta">Álgebra Relacional do Workspace e o Observável Delta</a></li> <li><a href="#_o_vetor_composto_do_contexto_rag_pgvector_graphify">O Vetor Composto do 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_esparso_agregável_consumível">Componente 3 — Graphify Incremental : Esparso, Agregável, Consumível</a></li> </ul> </li> <li><a href="#_classificação_automática_do_rgpd_o_llm_como_roteador">Classificação Automática do RGPD : o LLM como Roteador</a></li> <li><a href="#_roadmap_do_asciidoc_ao_langgraph4j">Roadmap : do AsciiDoc ao LangGraph4j</a></li> <li><a href="#_o_que_esta_arquitetura_resolve_e_o_que_ela_não_resolve">O que Esta Arquitetura Resolve (e o que ela não Resolve)</a></li> <li><a href="#_conclusão_a_arquitetura_como_discurso">Conclusão: a Arquitetura como Discurso</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 20 minutes</div> <p>A engenharia de prompts é frágil. Com 80.000 tokens, suas regras de alinhamento estão afogadas no ruído, e o LLM esquece o que você pediu no início da conversa. Minha solução? Não alinhar por texto, mas por l'<strong>espaço</strong>. Estruturei meu workspace de desenvolvimento em quatro círculos de confiança concêntricos — do jardim secreto íntimo até as forjas públicas — e cada círculo é uma área física do sistema de arquivos. O LLM não precisa que se lhe lembre das regras: o caminho do arquivo as contém. Veja como funciona, e por que essa arquitetura de alinhamento por espaço é mais resiliente do que um`system prompt`de 500 linhas</p> </div> <div class="paragraph"> <p>É um artigo longo.<br> Acomode-se confortavelmente.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_constato_prompt_engineering_é_um_castelo_de_areia">O Constato : Prompt Engineering é um Castelo de Areia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante três semanas, desenvolvi plugins Gradle com Opencode, usando três LLMs diferentes — Kimi K2.6, GLM-5.1, e DeepSeek-V4-Pro (o único sobrevivente, mas isso é outra história<a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Já coberta aqui.</a>) Meu método de governança agent<a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Eu a documentei em detalhes em um artigo anterior.</a> baseia-se em arquivos AsciiDoc —<code>AGENT.adoc</code>, <code>INDEX.adoc</code>, <code>PROMPT_REPRISE.adoc</code>— que carregam ~30 000 tokens de regras, de backlog e de histórico no início de cada sessão.</p> </div> <div class="paragraph"> <p>E apesar dessa infraestrutura documental, duas coisas me chamaram a atenção:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>O LLM esquece.</strong> Mesmo com as regras absolutas na cabeça de cada arquivo EAGER, além de 60 000 tokens acumulados (contexto inicial + conversa), Kimi K2.6 começou a proposer`Write`esmagadores em arquivos de configuração. GLM-5.1 confundiu um token Firebase com um placeholder a ser substituído. As regras estavam escritas — o LLM não as <strong>via</strong> mais.</p> </li> <li> <p><strong>A governança em si se torna um problema.</strong> Depois de ter implementado o mecanismo Hot/Warm/Cold<a href="0110_mecanisme_backup_contexte_agent_post.html">Article sur la rotation de backup.</a> para evitar a explosão do contexto, meus arquivos EAGER ainda pesavam 1414 linhas<a href="0111_audit_contexte_agent_post.html">J’ai documenté cet audit ici.</a>. A governança — projetada para proteger o LLM da saturação — saturava o LLM.</p> </li> </ol> </div> <div class="paragraph"> <p>Eu precisava de um mecanismo de alinhamento que não dependesse do número de tokens no prompt.</p> </div> <div class="paragraph"> <p>A resposta: parar de alinhar pelo texto, e começar a alinhar pelo<strong>espaço</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_os_quatro_círculos_de_confiança_uma_ontologia_espacial">Os Quatro Círculos de Confiança : uma Ontologia Espacial</h2> <div class="sectionbody"> <div class="paragraph"> <p>Meu dossiê`workspace/<code>(em</code>~/workspace/`) <strong>não</strong> é um repositório Git. É a raiz de todo o meu trabalho — código, documentação, formação, infraestrutura. E está estruturado em quatro áreas que não são convenções de arrumação, mas de<strong>círculos de confiança 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">Nível</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Label</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">Visibilidade</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>Jardim secreto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`workspace/`raiz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhum</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Íntimo — pensamento livre, sem commit, sem publicação</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>Cofre forte</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">Segredos, tokens, arquivo de visão. Uma única pessoa.</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">Dados pedagógicos, SPG/SPD, esquemas JSON. Círculo de confiança 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>Forjas (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 fonte, plugins, testes, documentação técnica.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>NOTA: Não há nível 3 na tabela. O nível 3 é um nível <strong>transitório</strong>: é conteúdo de`office/`que foi anonimizado e está pronto para ser publicado em open data. Não tem uma zona física própria — é um estado do dado, não um local.</p> </div> <div class="paragraph"> <p>Cada nível responde a uma pergunta específica :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Onde depositar uma ideia que ainda não está pronta para ser compartilhada, mesmo com um círculo restrito?</strong> → Jardim secreto. Sem Git. Sem pressão.</p> </li> <li> <p><strong>Onde armazenar um token API sem que ele vaze ?</strong> → O cofre (<code>configuration/</code>). Fisicamente isolado. Nenhum outro depósito pode referenciá-lo por engano.</p> </li> <li> <p><strong>Onde co-construir um catálogo de formação com um OF piloto?</strong> → A biblioteca`office/`). Versionado, colaborativo, mas privado.</p> </li> <li> <p><strong>Onde industrializar um plugin Gradle open source?</strong> → As forjas`foundry/`Público, forkável, testado em CI.</p> </li> </ul> </div> <div class="paragraph"> <p>Esta ontologia é<strong>consumível por um LLM</strong>. Quando ele lê um arquivo dentro`foundry/plantuml-gradle/src/`, ele sabe implicitamente: "estou no círculo 4 — código público, testes obrigatórios, sem segredos, sem dados pedagógicos". Ele não precisa de um prompt que o lembre.</p> </div> <div class="sect2"> <h3 id="_o_jardim_secreto_o_espaço_fora_cvs">O Jardim Secreto: o Espaço Fora-CVS</h3> <div class="paragraph"> <p>Este é o conceito mais importante — e o mais contra-intuitivo.</p> </div> <div class="paragraph"> <p>A raiz`workspace/<code>não tem</code>.git/<code>. Os documentos que vivem lá (`WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>— e aquele que você está lendo neste momento, que dele provém, não são destinados a serem versionados, compartilhados ou mesmo relidos por alguém além de mim. São<strong>pensamentos em germinação</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>O jardim secreto é <strong>out-of-CVS</strong> por natureza. A ausência de versionamento é a condição da liberdade de pensar. Não se escreve para ser lido — escreve-se para esclarecer a própria visão.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Mas esta liberdade tem um custo: um`rm`acidental, e são meses de reflexão estratégica que desaparecem. A solução não é versionar o jardim (isso seria destruí‑lo) — é de le<strong>espelhar</strong>no círculo mais restrito</p> </div> <div class="sect3"> <h4 id="_o_gitignore_como_configuração_de_governança">O <code>.gitignore</code> como Configuração de Governança</h4> <div class="paragraph"> <p>Na raiz de`workspace/<code>, um arquivo</code>.gitignore`minimal declara o<strong>política de historicização</strong>alguns ficheiros do jardim 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`não tem uma função Git clássica (não há</code>.git/`à raiz). ele age como um<strong>arquivo de configuração de governança</strong>que responde a uma pergunta específica: <strong>quais artefatos do jardim secreto merecem ser historizados, e quais são puramente transitórios?</strong></p> </div> <div class="ulist"> <ul> <li> <p>Os arquivos listados em`.gitignore`—<code>.goosehints</code>, <code>.goose</code>— são artefatos efêmeros gerados pelos agentes. Sem valor estratégico. Sem historicização.</p> </li> <li> <p>Os arquivos`.adoc` da raiz —<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>— não são<strong>não</strong>no`.gitignore`. Estes são os artefatos a serem historicizados.</p> </li> </ul> </div> <div class="paragraph"> <p>Le `.gitignore`é o<strong>esquema de governança</strong>: tudo o que não está listado lá é um candidato ao snapshot. E o LLM, ao ler esse arquivo, sabe exatamente o que deve ser arquivado e o que pode ser ignorado — sem que seja necessário lembrá-lo nisso em um prompt.</p> </div> </div> <div class="sect3"> <h4 id="_o_mecanismo_de_snapshot">O Mecanismo de Snapshot</h4> <div class="paragraph"> <p>Eu criei`configuration/vision-archive/<code>: instantâneos datados de todos os</code>.adoc`da raiz, commits no repositório privado`configuration/`Cada sessão de brainstorming produz um snapshot:</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>O procedimento é acionado no final da sessão pelo próprio LLM, que executa essa tarefa global de roteamento. Cada snapshot captura o estado completo do pensamento estratégico em um instante T.</p> </div> <div class="paragraph"> <p>O histórico Git de`configuration/`torna-se a<strong>biografia de meu pensamento estratégico</strong>. Eu posso fazer um`git log — vision-archive/`e ver a evolução da minha visão, sessão por sessão, data por data.</p> </div> <div class="paragraph"> <p>Exemplo real do histórico após um dia de trabalho :</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 snapshots em um dia. Cada um é um ponto de restauração. Cada um é um marco na gênese da estratégia.</p> </div> <div class="paragraph"> <p>O dossier`configuration/vision-archive/latest/`contém continuamente uma<strong>cópia de trabalho</strong>do último snapshot, servindo como referência rápida sem precisar navegar no histórico do Git.</p> </div> <div class="paragraph"> <p>E para o LLM, é um<strong>oráculo de coerência</strong>: quando ele observa uma contradição entre a implementação atual e a visão arquivada em uma data anterior, ele pode sinalizá-la.</p> </div> </div> </div> <div class="sect2"> <h3 id="_o_cofre_fort_configuration_como_spring_cloud_config">O Cofre-Fort : <code>configuration/</code> como Spring Cloud Config</h3> <div class="paragraph"> <p>`configuration/`ne contém apenas o arquivo da visão. Sua função primária — e futura — é ser um<strong>servidor Spring Cloud Config</strong>. Todos os segredos, tokens, credenciais e descritores de infraestrutura vivem aqui, em um repositório Git privado acessível apenas ao proprietário.</p> </div> <div class="paragraph"> <p>Por que um repositório separado em vez de um arquivo`.env`em cada projeto?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Push acidental de um segredo</strong>: impossível. Os segredos estão em um repositório privado que os projetos públicos não podem referenciar por engano.</p> </li> <li> <p><strong>Audit</strong> : o histórico do Git fornece o rastro de cada modificação de configuração. Quem mudou o quê, quando, com qual hash SHA.</p> </li> <li> <p><strong>Reverter</strong> :`git revert`Em uma configuração quebrada. Instantâneo, sem backup manual.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_a_biblioteca_office_como_dados_consumíveis">A Biblioteca: <code>office/</code> como Dados Consumíveis</h3> <div class="paragraph"> <p>`office/`o contrapartida documental do trabalho de desenvolvimento. Contém os artigos de blog, as especificações técnicas, os materiais de formação (38 diretórios de cursos FPA, SPG/SPD, esquemas JSON, taxonomias Bloom/Harrow/Krathwohl) — tudo o que constitui o<strong>material didático</strong>.</p> </div> <div class="paragraph"> <p>Mas`office/`Não é apenas uma gaveta de documentos. É uma<strong>fonte de dados estruturados</strong>que os plugins Gradle de`foundry/`consumem. Um artigo de blog em`office/`é uma entrada que um plugin transformará em HTML. Um SPG AsciiDoc dentro`office/metiers/FPA/`é um artefato que um orquestrador analisará para gerar slides, quiz e cápsulas de vídeo.</p> </div> <div class="paragraph"> <p>Et le `build.gradle.kts`na raiz de`office/`não é código de negócio — é um<strong>script de consumo do ecossistema de plugins</strong>. Ele diz : "aqui estão os plugins Gradle que eu uso, aqui está o contexto do meu workspace".</p> </div> </div> <div class="sect2"> <h3 id="_as_forjas_foundry_como_implementação">As Forjas: <code>foundry/</code> como implementação</h3> <div class="paragraph"> <p><code>foundry/`contém o<strong>código industrializado</strong>. 54 repositórios Git, dos quais 7 atualmente governados por</code>.agents/`. É aqui que a visão se torna executável — plugins Gradle, CI/CD, testes JUnit5 + Cucumber.</p> </div> <div class="paragraph"> <p>A relação com`office/`é bidirecional :</p> </div> <div class="ulist"> <ul> <li> <p><code>office/</code>→<code>foundry/</code>: os dados pedagógicos são a matéria-prima que os plugins consomem.</p> </li> <li> <p><code>foundry/</code>(empty)<code>office/</code>: os plugins produzem dados que enriquecem`office/` — le `graph.json`do graphify-gradle, os decks slider compilados, os relatórios de build.</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_próscontras_alinhamento_espacial_vs_alinhamento_por_prompt">Prós/Contras : Alinhamento Espacial vs Alinhamento por Prompt</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comparemos as duas abordagens.</p> </div> <div class="sect2"> <h3 id="_abordagem_clássica_alinhamento_por_pré_prompt">Abordagem Clássica: Alinhamento por Pré-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">Simples de implementar. Um bloco de texto no system prompt.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Frágil ao contexto longo</strong> : a regra se perde após 80K tokens.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Funciona para regras gerais (tom, formato).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Não verificável</strong> : nada impede o LLM de violar a regra.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Não é necessário repensar a arquitetura do projeto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Não transferível</strong>: cada repositório redefine as regras.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Puramente declarativo</strong>: o LLM sabe que ele <strong>deveria</strong>, mas nada o impede.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_esta_abordagem_alinhamento_por_ontologia_espacial">Esta Abordagem : Alinhamento por Ontologia 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 a contextos longos</strong> : a regra está no caminho do arquivo, não em um prompt distante.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Custo de infraestrutura inicial</strong> : estruturar o workspace em círculos leva tempo.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Verificável mecanicamente</strong>: um segredo em`foundry/<code>é detectável por`git check-ignore</code>.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Exige disciplina</strong> : um novo contribuidor deve entender os círculos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Transferível</strong> : um`AGENT.adoc`O padrão expõe os círculos a todo novo projeto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cobre apenas as restrições espaciais</strong> — o estilo de código permanece no prompt.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Segurança por design</strong> : um`git push`desde`foundry/<code>não pode expor`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>Consumível por agentes não-LLM</strong> : um orquestrador Gradle pode rotar de acordo com o círculo.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>O ganho principal não é defensivo (segurança, visibilidade) — ele é<strong>criativo</strong>. Quando o LLM trabalha em um espaço estruturado por uma ontologia, ele pode fazer o que nenhum prompt lhe permite: <strong>observar o delta</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_álgebra_relacional_do_workspace_e_o_observável_delta">Álgebra Relacional do Workspace e o Observável Delta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando o LLM percorre`foundry/<code>, ele dispõe de um<strong>treliça de dados estruturados</strong>: nós (plugins, arquivos, testes, dependências), arestas tipadas (`import</code>, <code>depends_on</code>, <code>generates</code>, <code>tests</code>), relações de composição e ordem (`training-gradle`extrai o repositório`slider-gradle`gera os slides →`capsule-gradle`reproduz o vídeo).</p> </div> <div class="paragraph"> <p>Esta álgebra não está escrita em nenhum lugar em texto claro — mas ela é <strong>observável</strong>. Cada`build.gradle.kts`expõe dependências. Cada`INDEX.adoc`expõe referências cruzadas.</p> </div> <div class="paragraph"> <p>O LLM observa esta álgebra e detecta o<strong>delta</strong>: a diferença entre o que o sistema já sabe produzir e o que a visão descreve.</p> </div> <div class="paragraph"> <p>A partir desse delta, ele pode definir alguns<strong>cartografias de especialistas de negócio</strong>— CDA (Designer e desenvolvedor de aplicações, Kotlin/Gradle/JHipster) e FPA (Formador Profissional de Adultos, Pedagogie/Qualiopi/Bloom) — e identificar o que falta para cada especialista.</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>O LLM não precisa que se lhe diga o que fazer. O delta emerge da estrutura.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_vetor_composto_do_contexto_rag_pgvector_graphify">O Vetor Composto do Contexto: RAG + pgvector + Graphify</h2> <div class="sectionbody"> <div class="paragraph"> <p>A álgebra relacional não é uma construção teórica. Ela é <strong>materializada</strong> por três componentes que formam um<strong>vetor composto de contexto</strong>para o 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>Já tenho LangChain4j em produção em dois plugins :`slider-gradle`(4 provedores LLM) e`plantuml-gradle`(7 fornecedores). Os embeddings ONNX (AllMiniLmL6V2) indexam os dados de`office/`e o código fonte de`foundry/`no PostgreSQL + pgvector</p> </div> <div class="paragraph"> <p>Este RAG opera em duas dimensões :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Dados de dimensão</strong> : os documentos`office/`(SPG, artigos, formações, esquemas JSON)</p> </li> <li> <p><strong>Código de dimensão</strong> : as codebases`foundry/`(fontes Kotlin, testes Cucumber, AGENT.adoc)</p> </li> </ul> </div> <div class="paragraph"> <p>A interseção cobre tanto o <strong>o quê</strong> (o domínio de negócio) quanto o <strong>como</strong> (a implementação).</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 em`plantuml-gradle`(109 testes, 380/380 PASS) e produz um`graph.json`— um knowledge graph estruturado com nós, arestas e comunidades detectadas automaticamente.</p> </div> <div class="paragraph"> <p>Ao contrário do RAG, que opera por similaridade vetorial (difuso), o knowledge graph opera por<strong>relações exatas</strong>(determinista) :`graphify query`para as interrogações semânticas (~50 tokens),`graphify path`para navegar,`graphify explain`para explicar</p> </div> </div> <div class="sect2"> <h3 id="_componente_3_graphify_incremental_esparso_agregável_consumível">Componente 3 — Graphify Incremental : Esparso, Agregável, Consumível</h3> <div class="paragraph"> <p>Esta é a decisão arquitetônica-chave.</p> </div> <div class="paragraph"> <p>Graphify não deve viver em um único repositório. Ele deve viver de forma<strong>esparsa</strong>em cada plugin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Cada plugin</strong> embarca uma tarefa Gradle`updateKnowledgeGraph`que chama Graphify<strong>sobre o seu próprio scope</strong>e produz um`graph.json`local.</p> </li> <li> <p><strong>O script de build de`office/<code></strong> consome`graphify-gradle`com`rootDir = /home/cheroliv/workspace`e produz um`graph.json</code> <strong>global</strong>que agrega os grafos locais.</p> </li> <li> <p><strong>O RAG de cada plugin</strong> injeta o`graph.json`global como<strong>filtro de contexto</strong>para as 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: o LLM não está procurando no vazio — ele navega em um espaço estruturado pelo knowledge graph. Uma consulta sobre gerar um diagrama consegue alcançar os nós relevantes do grafo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_classificação_automática_do_rgpd_o_llm_como_roteador">Classificação Automática do RGPD : o LLM como Roteador</h2> <div class="sectionbody"> <div class="paragraph"> <p>A ontologia espacial não se contente apenas de alinhar o LLM — ela lhe dá uma<strong>grade de classificação GDPR</strong>para encaminhar cada dado para sua 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">Critério</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detecção LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ação</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nível máximo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dado pessoal (nome, e-mail, IP)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">padrão`@`, IP, nomes próprios</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonimizar →`[OF_PILOTE]`ou router nível 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 / Segredo / Credencial</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">padrão`sk-…​<code>, `ghp_…​</code>, <code>ya29…​</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Roteador →<code>configuration/</code>. Referenciar por`${VAR}`no 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">Contém`localhost`, IP privado</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">Dado pedagógico (SPG, aula)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estrutura Bloom/Qualiopi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">roteador`office/`(nível 2). Versão dupla se exportar.</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 fonte / teste</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensão`.kt`, <code>.kts`em`foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">roteador →`foundry/`Verificar ausência de segredos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>No final da sessão, o LLM executa uma<strong>tarefa global</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Leitura do`.gitignore`raiz para identificar os artefatos efêmeros (a excluir do instantâneo) vs os artefatos estratégicos (a historizar)</p> </li> <li> <p>Inventário de todos os arquivos`.adoc`da raiz`workspace/`</p> </li> <li> <p>Filtragem : exclusão dos arquivos listados em`.gitignore`, inclusão de todos os outros</p> </li> <li> <p>Copia em`configuration/vision-archive/$DATE/<code>e atualização do symlink`latest/</code></p> </li> <li> <p>Commit no repositório`configuration/`com uma mensagem estruturada</p> </li> <li> <p>Classificação automática do RGPD de cada arquivo modificado (todos os círculos)</p> </li> <li> <p>Roteamento: dados`office/<code>→ commit privado, código`foundry/</code>→<code>./gradlew check</code>, configuração → commit</p> </li> <li> <p>Relatório estruturado com alertas RGPD e confirmação de arquivamento</p> </li> </ol> </div> <div class="paragraph"> <p>Le `.gitignore`raiz não é um arquivo de configuração Git — é um<strong>arquivo de governança da historicização</strong>. Define o esquema que o LLM consome para decidir quais arquivos do jardim secreto entram na biografia estratégica e quais são descartáveis.</p> </div> <div class="paragraph"> <p>O LLM não é mais um simples gerador de texto. Ele é o<strong>gerente de informação</strong>do ecossistema — produtor, classificador, roteador.</p> </div> </div> </div> <div class="sect1"> <h2 id="_roadmap_do_asciidoc_ao_langgraph4j">Roadmap : do AsciiDoc ao LangGraph4j</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hoje, esta governança é <strong>determinista</strong>: o LLM aplica um procedimento descrito em arquivos AsciiDoc. É a<strong>fase 1</strong>— o prompt engineering com memória LLM</p> </div> <div class="paragraph"> <p>La <strong>fase 2</strong>extrairá cada etapa do procedimento em uma<strong>tarefa 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á o processo de término da sessão como um<strong>grafo de estado</strong>comhttps://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 no CI/CD, executado pelo Gradle, configurado via os GitHub Secrets dos plugins. O LLM não precisará mais decidir o roteamento — o grafo fará isso.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_esta_arquitetura_resolve_e_o_que_ela_não_resolve">O que Esta Arquitetura Resolve (e o que ela não Resolve)</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>A ontologia espacial não cobre tudo. As convenções de estilo de código, a nomenclatura, as escolhas de design arquitetural — tudo isso permanece no prompt. O que a ontologia espacial resolve é a<strong>camada de segurança e de visibilidade</strong>: onde cada byte deve viver, e quem pode vê-lo.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Aqui está o que ela traz concretamente:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Não`git push`acidental de um segredo</strong>: os segredos são em`configuration/<code>(cercle 1). Os projetos públicos estão em`foundry/</code>(círculo 4). Nenhum caminho atravessa os dois.</p> </li> <li> <p><strong>Sem código de negócio nos dados</strong><code>office/`contém</code>.adoc`, alguns YAML, alguns JSON Schemas — mas não há`.kt`. Le `build.gradle.kts`que lá vive é um script de consumo, não é código de negócio.</p> </li> <li> <p><strong>Sem pensamento estratégico exposto</strong> : Os documentos de visão vivem no jardim secreto (raiz fora-CVS). Os snapshots estão em`configuration/`(cofre privado). Ninguém, mesmo num círculo de confiança alargado, lê a gênese da estratégia.</p> </li> <li> <p><strong>Auto-priorização</strong> : o LLM observa o delta entre a álgebra relacional (o que existe) e os mapeamentos de especialistas (o que é necessário). A próxima tarefa de desenvolvimento surge desse delta.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_a_arquitetura_como_discurso">Conclusão: a Arquitetura como Discurso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Não coloco manifesto político no rodapé do meu site. Não coloco regras éticas nos meus prompts. O alinhamento não está no texto — está no<strong>sistema de arquivos</strong>.</p> </div> <div class="paragraph"> <p>Quando um LLM trabalha neste espaço, ele não pode vazar um segredo (o caminho o impede). Ele não pode confundir um dado pedagógico com código-fonte (a zona física é diferente). Ele não pode esquecer uma regra de segurança de 80 000 tokens — porque a regra não está no prompt, ela está no`workspace/` → <code>configuration/</code>→<code>office/</code>→`foundry/`que cada leitura de arquivo seja reativa</p> </div> <div class="paragraph"> <p>É o princípio do <strong>secure by design</strong> aplicado ao alinhamento do agente: não pedir ao LLM para se lembrar das regras. Fazer com que a arquitetura torne o erro estruturalmente impossível.</p> </div> <div class="paragraph"> <p>E a propósito, isso dá ao LLM o que nenhum prompt pode lhe dar: a capacidade de<strong>perceber</strong>onde ele está, o que existe, o que falta — e disso deduzir o que ele deve fazer.</p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Artigo sobre a governança do agente Eager/Lazy :<a href="../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Governar um Agente IA com AsciiDoc</a></p> </li> <li> <p>Artigo sobre o mecanismo Hot/Warm/Cold :<a href="../2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window e onda fria</a></p> </li> <li> <p>Artigo sobre a auditoria de contexto:<a href="../2026/0111_audit_contexte_agent_post.html">Quando Sua Própria Governança Torna-se o Problema</a></p> </li> <li> <p>Artigo sobre a comparação dos três 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="#_a_cena_um_formulário_que_não_armazena_nada">A cena : um formulário que não armazena nada</a> <ul class="sectlevel2"> <li><a href="#_o_legado_supabase">O legado Supabase</a></li> <li><a href="#_a_submissão_dupla_fantasma">A submissão dupla fantasma</a></li> </ul> </li> <li><a href="#_por_que_firebase_em_vez_de_supabase">Por que Firebase em vez de Supabase?</a></li> <li><a href="#_fase_1_criar_o_projeto_firebase">Fase 1: Criar o projeto Firebase</a> <ul class="sectlevel2"> <li><a href="#_inicialização">Inicialização</a></li> <li><a href="#_regras_de_segurança_firestore">Regras de segurança Firestore</a></li> </ul> </li> <li><a href="#_fase_2_reescrever_o_javascript_de_submissão">Fase 2: Reescrever o JavaScript de submissão</a> <ul class="sectlevel2"> <li><a href="#_a_dependência_window_firebase">A dependência `window.<em>FIREBASE</em></a></li> <li><a href="#_o_novo_contact_js">O novo `contact.js</a></li> </ul> </li> <li><a href="#_phase_3_limpar_o_código_morto_supabase">Phase 3 : Limpar o código morto Supabase</a></li> <li><a href="#_fase_4_configurar_o_rodapé">Fase 4 : Configurar o rodapé</a></li> <li><a href="#_fase_5_arquitetura_final">Fase 5 : Arquitetura final</a></li> <li><a href="#_o_que_essa_migração_diz_sobre_o_dogfooding">O que essa migração diz sobre o dogfooding</a> <ul class="sectlevel2"> <li><a href="#_resumo_das_modificações">Resumo das modificações</a></li> </ul> </li> <li><a href="#_próximos_passos_backlog">Próximos passos (backlog)</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 12 minutes</div> <p>Durante meses, o formulário de contato deste site rodou em um mock JavaScript — uma promessa de 85% de sucesso, um Firestore falso, zero dados armazenados. O plano inicial previa um backend Supabase com Google Apps Script para as notificações por e‑mail. Abandonado. Hoje, eu conto a migração para o Firebase Firestore: criação do projeto, regras de segurança, reescrita do JS, limpeza do código morto Supabase. E por que essa escolha diz algo maior sobre a filosofia de desenvolvimento.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_um_formulário_que_não_armazena_nada">A cena : um formulário que não armazena nada</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este site é gerado pelo JBake, meu plugin Gradle`bakery`. É 100% estático—sem backend, sem banco de dados. Exceto que eu tenho um formulário de contato. A página`contact.html`existe, o HTML está pronto (campos nome, e-mail, telefone, assunto, mensagem, validação HTML5, honeypot anti-spam), os estilos Bootstrap estão no lugar. Visualmente, tudo está perfeito.</p> </div> <div class="paragraph"> <p>Exceto que na submissão, nada acontece.</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>Um mock. Uma promessa que finge. O utilizador vê um spinner, depois uma mensagem « Mensagem enviada com sucesso! ». Mas os dados vão para o vazio. Nenhuma mensagem é armazenada em lugar nenhum.</p> </div> <div class="paragraph"> <p>A situação é pior do que um formulário quebrado — é um formulário que mente.</p> </div> <div class="sect2"> <h3 id="_o_legado_supabase">O legado Supabase</h3> <div class="paragraph"> <p>O plano inicial, documentado em`content/draft/integration_formulaire_contact_supabase.adoc`, previa :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Uma base Supabase com tabela`contacts`e Row Level Security</p> </li> <li> <p>Uma RPC`handle_contact_form`lado do servidor</p> </li> <li> <p>Um trigger SQL chamando um webhook Google Apps Script</p> </li> <li> <p>Google Apps Script que envia um e-mail Gmail de notificação</p> </li> </ol> </div> <div class="paragraph"> <p>O código JavaScript correspondente ainda existe em`script.js`. Há uma classe`SupabaseManager`que inicializa um cliente Supabase com variáveis globais`SUPABASE_URL` et <code>SUPABASE_KEY</code>, e uma classe`ContactFormHandler`quem ouve o evento submit do formulário e chama`SupabaseManager.submitContactForm()`.</p> </div> <div class="paragraph"> <p>Problema: Essas variáveis globais não são mais injetadas no rodapé. O`<script src="supabase-js">`foi removido. O código chama`supabase.createClient()`em uma variável`supabase`que não existe mais. Portanto:</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>Não apenas os dados não são armazenados, mas o código de submissão está morto.</p> </div> </div> <div class="sect2"> <h3 id="_a_submissão_dupla_fantasma">A submissão dupla fantasma</h3> <div class="paragraph"> <p>Para piorar as coisas, há uma<strong>concorrência silenciosa</strong>entre dois handlers no mesmo formulário :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>`contact.js`Ouça o submit, chame o mock Firebase</p> </li> <li> <p><code>script.js</code>— via`ContactFormHandler`— escuta também o submit, chama`SupabaseManager`</p> </li> </ol> </div> <div class="paragraph"> <p>Os dois fazem`event.preventDefault() + event.stopPropagation()<code>. Como`contact.js`é carregado primeiro em`footer.thyme</code>, seu handler é anexado primeiro. Ele bloqueia a propagação.`ContactFormHandler`nunca será acionado.</p> </div> <div class="paragraph"> <p>Não é nem mesmo um bug ativo — é um zumbi. Código que nunca tem a oportunidade de ser executado.</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 — Formulário de Contato rectangle "contact.thyme (HTML Bootstrap, honeypot)" as FORM ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Estado Inicial — Formulário de Contato rectangle "contact.thyme (HTML Bootstrap, honeypot)" as FORM rectangle "footer.thyme\n(Firebase SDK com placeholder de config)" as FOOT rectangle "contact.js\n(mock Firebase, 85% de sucesso)" as CONT rectangle "script.js\n(SupabaseManager + ContactFormHandler, mortos)" as SCRIPT rectangle "Usuário" 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_que_firebase_em_vez_de_supabase">Por que Firebase em vez de Supabase?</h2> <div class="sectionbody"> <div class="paragraph"> <p>A decisão de migração é documentada em`AGENT.adoc`</think> (nothing)</p> </div> <div class="paragraph"> <p>Firebase agora é escolhido pelos seguintes motivos: melhor plano gratuito, Firestore nativo, Cloud Functions integradas, ecossistema Google mais adequado. A implementação Supabase existente está marcada « ⚠️ Abandonado ».</p> </div> <div class="paragraph"> <p>Além do plano gratuito, há uma razão arquitetônica. Este site vive no ecossistema do Google: o repositório alvo é`cheroliv.github.io`, o CNAME aponta para o GitHub Pages, o build Gradle faz push no GitHub via JGit. Adicionar um serviço Google (Firebase) em vez de um serviço terceirizado (Supabase) reduz a superfície de dispersão.</p> </div> <div class="paragraph"> <p>Firestore no modo nativo (não no modo Datastore) também está mais próximo do modelo mental de documento NoSQL que eu tenho em mente: coleções, documentos, campos tipados, timestamps do servidor, regras de segurança integradas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_1_criar_o_projeto_firebase">Fase 1: Criar o projeto Firebase</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_inicialização">Inicialização</h3> <div class="paragraph"> <p>Como a CLI do Firebase não está instalada na minha máquina, passo a usar o console da web:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ir parahttps://console.firebase.google.com/[Firebase Console]</p> </li> <li> <p>Criar um projeto`cheroliv-contact`(ou reutilizar um projeto existente)</p> </li> <li> <p>Ativar Firestore no modo nativo (não Datastore)</p> </li> <li> <p>Criar um banco de dados na região`eur3`(Europe)</p> </li> </ol> </div> <div class="paragraph"> <p>Para um uso minimalista como o nosso (uma única coleção, gravação pública), o modo nativo é a escolha certa. Não é necessário ter regras Datastore complexas.</p> </div> </div> <div class="sect2"> <h3 id="_regras_de_segurança_firestore">Regras de segurança Firestore</h3> <div class="paragraph"> <p>O formulário é público — qualquer pessoa pode enviar uma mensagem. Mas eu quero limitar os 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>Pontos-chave:</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code>— somente os usuários autenticados podem ler as mensagens (eu, via o console Firebase)</p> </li> <li> <p><code>allow create</code>— qualquer pessoa pode criar um documento, mas com validação dos campos</p> </li> <li> <p>Validação do lado do servidor: tamanhos mínimo/máximo, formato de e-mail,<code>created_at`deve corresponder a`request.time</code>(anti-falsificação)</p> </li> <li> <p>`user_agent`é enviado para rastreabilidade (não crítico mas útil)</p> </li> </ul> </div> <div class="paragraph"> <p>Estas regras são mais estritas do que um simples`allow write: if true;`. Eles impedem que um atacante injete payloads enormes ou campos malformados.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_2_reescrever_o_javascript_de_submissão">Fase 2: Reescrever o JavaScript de submissão</h2> <div class="sectionbody"> <div class="paragraph"> <p>O contrato é simples:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ler os dados do formulário</p> </li> <li> <p>Verificar o honeypot (campo`hp_name`— se estiver preenchido, é um bot, simulamos um sucesso sem enviar nada)</p> </li> <li> <p>Chamar`addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})`</p> </li> <li> <p>Mostrar sucesso ou erro</p> </li> </ol> </div> <div class="sect2"> <h3 id="_a_dependência_window_firebase">A dependência `window.<em>FIREBASE</em></h3> <div class="paragraph"> <p>Em`footer.thyme`, um módulo de script inicializa o Firebase SDK e expõe um 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>Os scripts do módulo são executados antes`DOMContentLoaded`, portanto`window.<em>FIREBASE</em>`é garantido disponível quando o handler`contact.js`é disparado. Por precaução, adiciono mesmo um polling de 5 segundos caso o CDN esteja lento.</p> </div> </div> <div class="sect2"> <h3 id="_o_novo_contact_js">O novo `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>As alterações em relação ao mock :</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code>— polling com timeout, robusto mesmo se o CDN for lento</p> </li> <li> <p><code>honeypot</code>— se o campo oculto`hp_name`está preenchido, simular um sucesso sem apelo Firestore. O bot acredita ter tido sucesso mas nada é armazenado</p> </li> <li> <p><code>addDoc(collection, {…​})</code>— chamada verdadeira do Firestore com`serverTimestamp()` et <code>user_agent</code></p> </li> <li> <p>Gestão de erro com`try/catch`assíncrono</p> </li> <li> <p>Limpeza do`finally`(restauro do botão)</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 que`user_agent`? É opcional, mas útil para o diagnóstico. Se chegar uma mensagem estranha, saber se ela vem de um navegador de desktop, móvel, ou de um script curl ajuda na triagem.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_3_limpar_o_código_morto_supabase">Phase 3 : Limpar o código morto Supabase</h2> <div class="sectionbody"> <div class="paragraph"> <p>`script.js`contém 250 linhas de código morto :</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code>(linhas 417-481) — 65 linhas</p> </li> <li> <p><code>ContactFormHandler</code>(linhas 490-551) — 62 linhas</p> </li> <li> <p>Bloco de inicialização (linhas 645-654) — 10 linhas</p> </li> </ul> </div> <div class="paragraph"> <p>Total: ~140 linhas a excluir.</p> </div> <div class="paragraph"> <p>O bloco`DOMContentLoaded`cria um`SupabaseManager`então um`ContactFormHandler`relacionado ao formulário. Como explicado acima, esse código nunca é executado (bloqueado por`contact.js`), e mesmo se fosse executado, falharia (nenhum SDK Supabase carregado).)</p> </div> <div class="paragraph"> <p>Eu apago:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>A classe`SupabaseManager`</p> </li> <li> <p>A classe`ContactFormHandler`</p> </li> <li> <p>O bloco de inicialização em`DOMContentLoaded`(linhas 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_o_rodapé">Fase 4 : Configurar o rodapé</h2> <div class="sectionbody"> <div class="paragraph"> <p>`footer.thyme`já tem o boilerplate Firebase mas com valores de placeholder. Substituo:</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>Pelos valores reais recuperados desde<strong>Configurações do Projeto > Geral > Seus aplicativos > App da web</strong>na console Firebase.</p> </div> <div class="paragraph"> <p>Os valores são sensíveis (<code>apiKey`é pública por design no Firebase, mas prefiro não commita-los em claro). Eu os armazeno em`site.yml</code>(já em`.gitignore`) e o plugin`bakery`os injeta no modelo via uma lógica a ser adicionada no lado do build.</p> </div> <div class="paragraph"> <p>Por enquanto eu os coloco diretamente em`footer.thyme`— o build`./gradlew serve`os carregará localmente. Na implantação, migrerei a injeção para`site.yml`ou para uma variável 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 não é<strong>não</strong>um segredo. Ela é pública por projeto. O que protege os seus dados, são os<strong>regras de segurança do Firestore</strong>, não a chave de API. Não a coloque em um`.env`Carregado do lado do servidor — é destinado a ser exposto ao navegador.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_fase_5_arquitetura_final">Fase 5 : Arquitetura 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 8) ] @startuml skinparam backgroundColor #FEFEFE title Arquitetura Final — Formulário de Contato Firebase actor Utilisateur as USER package "Navegador" #E8F5E9 { rectangle "contact.thyme ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE title Arquitetura Final — Formulário de Contato Firebase actor Utilisateur as USER package "Navegador" #E8F5E9 { rectangle "contact.thyme (HTML, honeypot)" as FORM rectangle "contact.js\n(validação + Firestore)" as CONT rectangle "footer.thyme\n(Inicialização do SDK Firebase)" as FOOT } cloud "Firebase" #BBDEFB { rectangle "Firestore\n(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="_o_que_essa_migração_diz_sobre_o_dogfooding">O que essa migração diz sobre o dogfooding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este site é gerado pelo meu próprio plugin Gradle`bakery`. O formulário de contato fica dentro do site. A migração Supabase → Firebase está documentada em`AGENT.adoc`, ela é discutida no backlog, ela é testada via`./gradlew serve`, e ela gera um artigo de blog (aquele que você está lendo).</p> </div> <div class="paragraph"> <p>É puro dogfooding. O site é o produto do plugin, o plugin é o produto do desenvolvedor, o desenvolvedor documenta o processo no próprio site.</p> </div> <div class="paragraph"> <p>O ciclo está fechado.</p> </div> <div class="paragraph"> <p>O fato de ter arrastado um mock por meses (sessões inteiras onde o formulário mentia silenciosamente) fez-me perceber algo : o backlog de um site estático pessoal nunca é « acabado ». Sempre há uma US prioritária, sempre um artigo em rascunho, sempre uma seção comentada em um modelo. A disciplina não é terminar tudo — é terminar o que é visível pelo usuário.</p> </div> <div class="paragraph"> <p>Um formulário de contato quebrado é pior do que não ter nenhum formulário. É uma promessa não cumprida.</p> </div> <div class="sect2"> <h3 id="_resumo_das_modificações">Resumo das modificações</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">arquivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">modificação</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">Criação do artigo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentação</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">Reescrita (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">Exclusão SupabaseManager + ContactFormHandler + init bloco</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Limpeza</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">Substituição do placeholder de config → valores reais</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">configuração</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_próximos_passos_backlog">Próximos passos (backlog)</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Email de notificação</strong>: uma Cloud Function`onCreate`sobre`contact_messages`que envia um e-mail via SendGrid. O formulário armazena, mas eu não sou notificado. Prioridade média — as mensagens são visíveis na console do Firebase.</p> </li> <li> <p><strong>Limitação de taxa no lado do cliente</strong>: Adicionar um timestamp localStorage para impedir envios múltiplos em rajada. O honeypot bloqueia os bots ingênuos, um rate limiter bloquearia os bots um pouco mais espertos.</p> </li> <li> <p><strong>Testes</strong>: Um teste Playwright que envia o formulário e verifica se o documento aparece no Firestore. Por enquanto, estou testando manualmente via`./gradlew serve`.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://firebase.google.com/docs/firestore/security/get-started">Documentação das regras de segurança do Firestore</a></p> </li> <li> <p><a href="https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document">Documentação Firestore addDoc — Web v9 modular</a></p> </li> <li> <p><a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Série de governança do agente — Parte 1: Eager/Lazy</a></p> </li> <li> <p><a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Série agente de governança — Parte 2 : Hot/Warm/Cold</a></p> </li> <li> <p><a href="/blog/2026/0111_audit_contexte_agent_post.html">Série governança agente — Parte 3 : Auditoria</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_não_é_um_banco_de_ensaio_mas_um_canteiro_de_obras">Contexto: não é um banco de ensaio, mas um canteiro de obras</a></li> <li><a href="#_meu_ambiente_de_teste">Meu ambiente de teste</a></li> <li><a href="#_a_grade_de_avaliação">A Grade de Avaliação</a></li> <li><a href="#_rodada_1_kimi_k2_6_o_falso_início">Rodada 1 : Kimi K2.6 — O Falso Início</a> <ul class="sectlevel2"> <li><a href="#_sessão_9_a_melhora">Sessão 9 : a melhora</a></li> <li><a href="#_sessão_10_o_naufrágio_silencioso">Sessão 10: o naufrágio silencioso</a></li> </ul> </li> <li><a href="#_round_2_glm_5_1_o_combatente_honorável">Round 2 : GLM-5.1 — O Combatente Honorável</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_o_dsa_contra_o_mla_puro">Arquitetura : o DSA contra o MLA puro</a></li> <li><a href="#_sessões_11_13_sólido_mas_frustrante">Sessões 11-13 : sólido mas frustrante</a></li> </ul> </li> <li><a href="#_round_3_deepseek_v4_pro_a_máquina_de_guerra">Round 3: DeepSeek-V4-Pro — A Máquina de Guerra</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_csa_hca_o_duplo_filete">Arquitetura: CSA + HCA, o duplo filete</a></li> <li><a href="#_sessões_1_8_alívio">Sessões 1-8 : alívio</a></li> <li><a href="#_o_teste_decisivo_refactoring_de_100k_tokens">O teste decisivo: refactoring de 100K tokens</a></li> </ul> </li> <li><a href="#_encontro_face_a_face_métricas_comparativas">Encontro Face a Face: Métricas Comparativas</a></li> <li><a href="#_por_que_deepseek_v4_pro_ganha_em_desenvolvimento_de_software">Por que DeepSeek-V4-Pro Ganha em Desenvolvimento de Software</a> <ul class="sectlevel2"> <li><a href="#_a_arquitetura_csahca_é_adaptada_para_o_código">A arquitetura CSA+HCA é adaptada para o código</a></li> <li><a href="#_2_o_contexto_eager_é_a_zona_de_conforto">2. O contexto EAGER é a zona de conforto</a></li> <li><a href="#_3_a_relação_qualidadelatência_é_ideal_para_o_fluxo">3. A relação qualidade/latência é ideal para o fluxo</a></li> </ul> </li> <li><a href="#_lições_aprendidas_como_escolher_seu_llm_para_o_vibe_coding">Lições Aprendidas: Como Escolher seu LLM para o Vibe Coding</a></li> <li><a href="#_e_a_governança_agent_em_tudo_isso">E a Governança Agent em tudo isso?</a></li> <li><a href="#_fontes_técnicas">Fontes Técnicas</a></li> <li><a href="#_conclusão_a_escolha_do_artesão">Conclusão: A Escolha do Artesão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 18 minutes</div> <p>A guerra dos LLMs também se desenrola no terminal de um desenvolvedor. Não em benchmarks acadêmicos estéreis. Na vida real: um prompt de 30 000 tokens, uma governança de agente em AsciiDoc, plugins Gradle Kotlin DSL para depurar e sessões que se encadeiam por três semanas. Testei para você DeepSeek-V4-Pro, Kimi K2.6 e GLM-5.1. Aqui está o veredicto, provas técnicas a respaldar.</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_não_é_um_banco_de_ensaio_mas_um_canteiro_de_obras">Contexto: não é um banco de ensaio, mas um canteiro de obras</h2> <div class="sectionbody"> <div class="paragraph"> <p>Há três semanas, eu estava trabalhando em`codebase-gradle`, meu sistema meta-build que centraliza a configuração YAML de quatro projetos: um gerador de README PlantUML, um construtor de slides AsciiDoc, um site estático JBake e um chatbot LLM. O agente Opencode, governado pela minha metodologia de arquivos de agente em AsciiDoc, carregava ~30K tokens de contexto EAGER a cada início de sessão — regras absolutas, backlog, histórico das últimas 10 sessões.</p> </div> <div class="paragraph"> <p>É neste terreno que eu confrontei três modelos :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong>(Moonshot AI, 1T parâmetros / 32B ativados, 256K contexto máximo, MLA) - <strong>GLM-5.1</strong>(Zhipu AI/Tsinghua, 744B de parâmetros / DSA, contexto máximo de 200K) - <strong>DeepSeek-V4-Pro</strong>(DeepSeek, 1.6T parâmetros / 49B ativados, 1M contexto máximo, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>Todos servidos via Ollama em servidor cloud, todos em modo thinking (fase de reflexão ativada). O desafio: produzir código correto, manter a consistência em sessões longas e não alucinar quando o contexto ultrapassar 80K tokens.</p> </div> </div> </div> <div class="sect1"> <h2 id="_meu_ambiente_de_teste">Meu ambiente de teste</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 10) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Ambiente de Teste — Sessões Opencode × 3 LLMs left to right direction package "🖥️ Terminal do Desenvolvedor" #E8F5E9 { rectangle "AGENT.adoc ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Ambiente de Teste — Sessões Opencode × 3 LLMs left to right direction package "🖥️ Terminal do Desenvolvedor" #E8F5E9 { rectangle "AGENT.adoc (regras, backlog)" as AG rectangle "PROMPT_REPRISE\n(missão)" as PR rectangle "INDEX.adoc\n(roteiro)" as IDX } package "☁️ Ollama Nuvem" #BBDEFB { rectangle "DeepSeek-V4-Pro\n1.6T / CSA+HCA" as DV4 rectangle "Kimi K2.6\n1T / MLA" as KIMI rectangle "GLM-5.1 744B / MLA+DSA" as GLMG } package "⚙️ Base de código Gradle" #FFF9C4 { folder "buildSrc/" { file "codebase.kt" file "readme.kt" file "site.kt" file "slider.kt" file "snapshot.kt" } file "build.gradle.kts (947 linhas)" file "embeds.yml" } AG --> DV4 : Sessions 1-8 ✅ AG --> KIMI : Sessions 9-10 ⚠️ AG --> GLMG : Sessions 11-13 ⚠️ DV4 --> "base de código" : "TDD, refatoração,\ninstantâneo" KIMI --> "base de código" : "Degradação a partir de 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 sessão iniciava com aproximadamente 30K tokens de contexto EAGER:`AGENT.adoc`(287 linhas),<code>PROMPT_REPRISE.adoc</code>(51 linhas),<code>.agents/INDEX.adoc</code>(218 linhas)<code>LAZY_EAGER_ESSENTIALS.adoc</code>(50 linhas). O contexto aumentava rapidamente com as trocas — uma sessão típica de 10 mensagens adicionava 15-20K tokens ao prompt cumulado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_grade_de_avaliação">A Grade de Avaliação</h2> <div class="sectionbody"> <div class="paragraph"> <p>Eu avaliei cada modelo em quatro eixos críticos para o desenvolvimento de software assistido.</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">Eixo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Critério concreto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coerência de longo contexto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O agente se lembra das convenções decididas há 40 mensagens?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Qualidade do código produzido</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O código compila de primeira? Respeita os padrões existentes?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Raciocínio arquitetônico</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O agente compreende as relações entre os módulos sem que eu tenha que lhes reexplicar?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Resistência às alucinações</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A partir de quantos tokens o agente começa a inventar APIs ou classes inexistentes?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>E uma métrica sintética caseira : o<strong>coeficiente de retomada</strong>(quanto tempo eu passo corrigindo o agente ao invés de codificar com ele)</p> </div> </div> </div> <div class="sect1"> <h2 id="_rodada_1_kimi_k2_6_o_falso_início">Rodada 1 : Kimi K2.6 — O Falso Início</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6 foi minha primeira escolha. Seus benchmarks no SWE-Bench Verified (80.2) e no Terminal-Bench 2.0 (66.7) são excelentes. Sua arquitetura MLA promete boa eficiência em sequências longas.</p> </div> <div class="sect2"> <h3 id="_sessão_9_a_melhora">Sessão 9 : a melhora</h3> <div class="paragraph"> <p>Primeira sessão com Kimi. Tarefa: implementar o método`resolveActiveKey()<code>em`codebase.kt</code>— uma função de resolução de chave API com fallback CLI. O contexto tem 30K tokens, o Kimi raciocina rápido, produz código limpo com gerenciamento de expiração das chaves.</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>O código compila. Os 7 casos de teste passam. Estou otimista.</p> </div> </div> <div class="sect2"> <h3 id="_sessão_10_o_naufrágio_silencioso">Sessão 10: o naufrágio silencioso</h3> <div class="paragraph"> <p>Segunda sessão. O contexto sobe para ~90K tokens com as trocas. Peço ao Kimi para acrescentar um mecanismo de snapshot AsciiDoc que anonimiza os segredos antes da escrita.</p> </div> <div class="paragraph"> <p>É aqui que isso escorrega. Kimi começa a inventar classes que não existem. Ele me propõe`AnonymizedObjectMapper`— uma classe fictiva. Ele confunde`ReadmeYmlAnonymizer` et <code>CodebaseYmlAnonymizer</code>. Ele me sugere importar`com.fasterxml.jackson.anonymize.*`— um pacote que nunca existiu.</p> </div> <div class="paragraph"> <p>Pior : na sua fase de reflexão, vejo que ele constrói raciocínios sobre premissas falsas. Ele "se lembra" que`GitConfig`tem um campo`anonymizedToken`— não, é`resolvedToken()<code>. Ele atribui a`SiteYmlAnonymizer`um método`maskSupabaseCredentials()</code>— que não existe.</p> </div> <div class="paragraph"> <p><em><em>_ Não era um bug. Era uma dissolução progressiva da coerência. Como se cada token adicionado ao contexto diluísse um pouco mais a memória dos primeiros 30 000. </em>_</em></p> </div> <div class="paragraph"> <p>Paro o Kimi após duas sessões. O diagnóstico é claro: o MLA comprime bem o cache KV, mas sem um mecanismo de seleção esparsa de granulação fina, a atenção se dilui mecanicamente além de 60K tokens. Cada token "vê" cada vez pior o contexto distante — e começa a preencher as lacunas com ruído.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_2_glm_5_1_o_combatente_honorável">Round 2 : GLM-5.1 — O Combatente Honorável</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1 chega com uma arquitetura diferente: MLA para o modelo base, seguido de um <strong>continued pre-training</strong> com DSA (DeepSeek Sparse Attention) — um indexador leve que seleciona dinamicamente os top-2048 tokens pertinentes de todo o histórico.</p> </div> <div class="sect2"> <h3 id="_arquitetura_o_dsa_contra_o_mla_puro">Arquitetura : o DSA contra o MLA puro</h3> <div class="paragraph"> <p>A diferença é fundamental. Onde Kimi comprime o histórico em um espaço latente único (e perde gradualmente a capacidade de discriminar a informação relevante), o GLM acrescenta um indexador pós-treinamento que faz uma seleção sparse 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 Arquiteturas de Atenção — 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 Arquiteturas de Atenção — MLA vs MLA+DSA left to right direction rectangle "**Kimi K2.6 — MLA puro**" as MLA #FFCDD2 { rectangle "KV Cache completo" as KV1 rectangle "Compressão latente" as CL1 rectangle "Decodificação espaço 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 "Compressão\nlatente (MLA)" as CL2 rectangle "Indexador leve (DSA, top-k=2048)" as IL rectangle "Decodificação dos tokens selecionados" as DL2 KV2 --> CL2 CL2 --> IL IL --> DL2 note bottom of DL2 ✅ "Sem perdas por construção." Sélection explicite des tokens pertinents end note } MLA --> DSA : "Gain : seleção esparsa que evita a diluição" @enduml</pre> </div> </div> <div class="paragraph"> <p>O relatório técnico diz explicitamente: DSA é <em>"lossless by construction"</em> — ao contrário das alternativas como SWA (busca por padrão), Gated DeltaNet ou SimpleGDN, que perdem até 5,69 pontos no RULER@128K.</p> </div> </div> <div class="sect2"> <h3 id="_sessões_11_13_sólido_mas_frustrante">Sessões 11-13 : sólido mas frustrante</h3> <div class="paragraph"> <p>GLM-5.1 mantém melhor a distância. Na sessão 11 (~60K tokens), ele permanece coerente. Ele produz um`SnapshotManager`funcional com gestão correta dos quatro anonimizadores</p> </div> <div class="paragraph"> <p>Mas a latência é um problema. As fases de reflexão DSA são mais pesadas que o MLA puro — o indexador precisa rescanear o histórico a cada passo. Uma resposta que levava 8 segundos com Kimi passa a levar 15 com GLM. Em uma sessão de 30 mensagens, isso se faz sentir.</p> </div> <div class="paragraph"> <p>E então há os erros sutis. GLM não delira como o Kimi — mas ele faz erros de <strong>nomeação</strong>. Ele chama`toAnonymizedYaml()<code>o método que deveria ser chamado`anonymize()</code>. Ele inverte`loadReadmeConfiguration()` et `loadCodebaseConfiguration()`no`renderFileSection()`Não são alucinações, são confusões de superfície — mas em produção, uma confusão de superfície pode quebrar um build.</p> </div> <div class="paragraph"> <p>Tive três sessões com o GLM. É melhor que o Kimi, sem contestação. Mas três sessões de correção manual em detalhes de nomeação, isso cansa.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_3_deepseek_v4_pro_a_máquina_de_guerra">Round 3: DeepSeek-V4-Pro — A Máquina de Guerra</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro chega com a arquitetura mais ambiciosa das três: um sistema híbrido que combina dois mecanismos de atenção complementares.</p> </div> <div class="sect2"> <h3 id="_arquitetura_csa_hca_o_duplo_filete">Arquitetura: CSA + HCA, o duplo filete</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 — Arquitetura Híbrida CSA + HCA left to right direction rectangle "Cache KV ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — Arquitetura Híbrida CSA + HCA left to right direction rectangle "Cache KV 1M tokens" as KV #E3F2FD rectangle "CSA Atenção Esparsa Comprimida" as CSA #C8E6C9 { rectangle "Compressão m tokens → 1" as CC rectangle "Atenção Esparsa (DSA, top-k)" as SA CC --> SA note bottom of SA Attention locale fine + sélection sparse end note } rectangle "HCA Atenção Altamente Comprimida" as HCA #BBDEFB { rectangle "Compressão extrema\nm' >> m → 1" as ECC rectangle "Atenção densa\nresidual" as EDA ECC --> EDA note bottom of EDA Contexte global + connexions longue distance end note } rectangle "Fusão\nhíbrida" as FUSION #FFF9C4 rectangle "Decodificação coerente" 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>Dois níveis de compressão, duas granularidades de atenção:</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong>: comprime o cache KV todos os`m`tokens, então aplica uma atenção esparsa (DeepSeek Sparse Attention) — apenas o top-k das entradas comprimidas é consultado. Preciso, local, eficiente. - <strong>HCA</strong>: compressão extrema (fator`m'`muito maior que`m`), mas atenção densa sobre o resíduo comprimido — mantenha as conexões globais sem explosão quadrática.</p> </li> </ul> </div> <div class="paragraph"> <p>Resultado: em 1M de tokens, DeepSeek-V4-Pro apenas consome<strong>27% dos FLOPs de inferência</strong> et <strong>10% do tamanho do cache KV</strong>em comparação ao DeepSeek-V3.2. O modelo anterior.</p> </div> <div class="paragraph"> <p>E principalmente, o relatório técnico (Figura 9) anuncia: <em>"O desempenho de recuperação permanece altamente estável dentro de uma janela de contexto de 128K."</em></p> </div> </div> <div class="sect2"> <h3 id="_sessões_1_8_alívio">Sessões 1-8 : alívio</h3> <div class="paragraph"> <p>Eu passei oito sessões com DeepSeek-V4-Pro em`codebase-gradle`. Oito sessões sem uma única alucinação, sem uma única classe inventada, sem uma única confusão de nomenclatura.</p> </div> <div class="paragraph"> <p>Sessão 1 : implementação de`CodebaseYmlConfig` et <code>CodebaseYmlAnonymizer</code>. 350 linhas de Kotlin, testes inline, tudo compila. Sessão 4 : adição do`SnapshotManager`com visualização em árvore, coleta de arquivos, renderização AsciiDoc por arquivo. 279 linhas, zero erros. Sessão 7 : depuração do`renderFileSection()`que precisava gerenciar quatro tipos de anonimizadores diferentes sem ambiguidade de resolução. Resolvido em três mensagens.</p> </div> <div class="paragraph"> <p>A latência é maior que a do Kimi — aproximadamente 10-12 segundos por resposta no modo de pensamento. Mas a taxa de correção é quase nula. Não estou perdendo meu tempo corrigindo os erros do agente. Eu codifico <strong>com</strong> ele.</p> </div> </div> <div class="sect2"> <h3 id="_o_teste_decisivo_refactoring_de_100k_tokens">O teste decisivo: refactoring de 100K tokens</h3> <div class="paragraph"> <p>Na sessão 8, o contexto cumulado ultrapassa 100K tokens. Peço um refactoring pesado: extrair as quatro tarefas de verificação inline do`build.gradle.kts`para arquivos de teste JUnit5 em`buildSrc/src/test/`.</p> </div> <div class="paragraph"> <p>O agente propõe um plano em três fases :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Criar as classes de teste com migração dos casos existentes</p> </li> <li> <p>Adicionar as dependências JUnit5 e Kotest em`buildSrc/build.gradle.kts`</p> </li> <li> <p>Remover o código inline de`build.gradle.kts`</p> </li> </ol> </div> <div class="paragraph"> <p>O plano está correto. A execução é limpa. Ele identifica até um caso de borda que eu tinha perdido: as dependências Jackson duplicadas entre`buildscript {}` et `buildSrc/build.gradle.kts`que devem ser unificadas durante a migração.</p> </div> <div class="paragraph"> <p>100K tokens de contexto, e o agente se lembra que`CodebaseYmlAnonymizer.TOKEN_MASK`é`"<strong>*</strong>"`, que`GitConfig.resolvedToken()<code>é uma função de extensão definida em`readme.kt</code>, e que`SnapshotManager.PRUNED_DIRS`exclui`build`, <code>.gradle</code> et <code>.git</code>.</p> </div> <div class="paragraph"> <p>É isso, a diferença.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_encontro_face_a_face_métricas_comparativas">Encontro Face a Face: 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">Critério</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 atenção</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 totais</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 ativados</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">não 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">Limiar de degradação observado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output, as no French text was provided for translation)</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">~128K tokens</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Comportamento além</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alucinações massivas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusões superficiais</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">degradação lenta e progressiva</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Estabilidade NIAH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">não 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">estável até 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">não publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">não publicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">superior ao Gemini 3.1 Pro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sessões résultatsantes avant 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 (e continua)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">tempo de correção / tempo 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">Latência média (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 confiança*</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>*Coeficiente de confiança = medida subjetiva da minha capacidade de pegar o código do agente e o commit sem revisão linha por linha.</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 em Desenvolvimento de Software Assistido legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coerência\n80K+ tokens" as coh #F5F5F5 rectangle "Qualidade código" as qual #F5F5F5 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Radar Comparativo — 3 LLMs em Desenvolvimento de Software Assistido legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coerência\n80K+ tokens" as coh #F5F5F5 rectangle "Qualidade código" as qual #F5F5F5 rectangle "Raciocínio arquitetural" as arch #F5F5F5 rectangle "Resistência alucinações" as hall #F5F5F5 rectangle "Velocidade (experiência de desenvolvimento)" as speed #F5F5F5 rectangle "Conhecimento Gradle/Kotlin" as kg #F5F5F5 rectangle "Taxa de correção" 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_que_deepseek_v4_pro_ganha_em_desenvolvimento_de_software">Por que DeepSeek-V4-Pro Ganha em Desenvolvimento de Software</h2> <div class="sectionbody"> <div class="paragraph"> <p>A superioridade do DeepSeek-V4-Pro não se deve a um único fator — é uma convergência :</p> </div> <div class="sect2"> <h3 id="_a_arquitetura_csahca_é_adaptada_para_o_código">A arquitetura CSA+HCA é adaptada para o código</h3> <div class="paragraph"> <p>O desenvolvimento de software assistido é um caso de uso <strong>extremo</strong> para a atenção de longo contexto. Você precisa de: - Precisão local (esta classe herda de quê? este método é definido onde?) →<strong>CSA</strong> - Visão global (por que este módulo existe ? como os quatro anonimizadores interagem ?) →<strong>HCA</strong></p> </div> <div class="paragraph"> <p>Kimi com MLA sozinho trata a precisão local, mas perde a visão global além de 60K. GLM com DSA melhora a visão global, mas permanece mono-nível. DeepSeek combina os dois explicitamente.</p> </div> </div> <div class="sect2"> <h3 id="_2_o_contexto_eager_é_a_zona_de_conforto">2. O contexto EAGER é a zona de conforto</h3> <div class="paragraph"> <p>Meu sistema de governança carrega ~30K tokens de regras e de backlog na inicialização. Com uma janela estável até 128K, o DeepSeek tem ~100K tokens de margem para as trocas da sessão. É de 3 a 4 vezes mais do que o Kimi consegue lidar sem degradação.</p> </div> <div class="paragraph"> <p>(Empty output) A janela de 128K de estabilidade perfeita corresponde exatamente às minhas necessidades : 30K de EAGER + 70K de trocas = uma sessão produtiva de 20-30 mensagens sem nunca sair da zona verde. <em>__</em></p> </div> </div> <div class="sect2"> <h3 id="_3_a_relação_qualidadelatência_é_ideal_para_o_fluxo">3. A relação qualidade/latência é ideal para o fluxo</h3> <div class="paragraph"> <p>Sim, DeepSeek-V4-Pro é mais lento que o Kimi (11s vs 8s). Mas o tempo <strong>total</strong> de uma tarefa é bem menor porque eu não gasto 20 minutos corrigindo as alucinações do agente.</p> </div> <div class="paragraph"> <p>O desenvolvedor não mede a latência de uma resposta. Ele mede o tempo entre "eu faço a pergunta" e "o código está no meu repositório e funciona". Nesta métrica, o DeepSeek-V4-Pro é o mais rápido dos três.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lições_aprendidas_como_escolher_seu_llm_para_o_vibe_coding">Lições Aprendidas: Como Escolher seu LLM para o Vibe Coding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Além da classificação pontual, esta experiência me ensinou a avaliar um LLM para o desenvolvimento de software assistido em critérios que não constam de nenhum benchmark:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Olha a arquitetura, não o tamanho do contexto anunciado</strong>— Um modelo que anuncia 256K de contexto mas tem apenas um MLA terminará como Kimi: teoricamente capaz, praticamente inutilizável além de 60K.</p> </li> <li> <p><strong>Teste no TEU contexto, não em um benchmark genérico</strong>— Meu prompt inicial de 30K tokens AsciiDoc com regras absolutas e backlog não tem nada a ver com as questões de HLE ou AIME.</p> </li> <li> <p><strong>A latência não é a inimiga se a qualidade acompanha</strong>— Um modelo lento que produz código correto é mais rápido do que um modelo rápido que produz código errado.</p> </li> <li> <p><strong>Cuidado com os modelos sem relatório técnico público</strong>— Se a equipe não documentar sua arquitetura de atenção, é porque ela não confia em seu desempenho em longo contexto.</p> </li> </ol> </div> <div id="diag-decision-tree" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-eef823d5be6fd380ecbee716465cd526.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="_e_a_governança_agent_em_tudo_isso">E a Governança Agent em tudo isso?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta experiência valida um ponto que defendo desde meu artigo sobre a governança Eager/Lazy :<strong>a qualidade do LLM e a qualidade da governança são multiplicativas, não aditivas</strong>.</p> </div> <div class="paragraph"> <p>Com o Kimi K2.6, minha governança estava impecável — mas o modelo diluía a informação. Resultado: governança perfeita × alucinação = zero.</p> </div> <div class="paragraph"> <p>Com o DeepSeek-V4-Pro, a governança EAGER (30K tokens de regras) + LAZY (arquivos de sessão, referências técnicas) + Hot/Warm/Cold (backup rotativo) forma um ecossistema onde cada camada amplifica a outra. O agente tem as regras à vista (EAGER), pode consultar o histórico (LAZY), e o contexto nunca fica saturado (rotação de backup).</p> </div> <div class="paragraph"> <p><em><em>_ Um bom LLM sem governança, é um motor de Ferrari sem volante. Uma boa governança sem bom LLM, é um volante sem motor. DeepSeek-V4-Pro + minha governança agente = a primeira vez que tenho a sensação de dirigir. </em>_</em></p> </div> <div class="paragraph"> <p>O mecanismo de backup rotativo (rotação a cada 10 sessões ou >500 linhas EAGER) faz todo sentido com um modelo que suporta 128K de contexto: a sliding window de 10 sessões ativas mantém o contexto atualizado sem jamais ultrapassar a zona de degradação.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fontes_técnicas">Fontes Técnicas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cruzei minha experiência empírica com os relatórios técnicos oficiais para validar minhas observações :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>DeepSeek-V4 Technical Report</strong> — PDF obtido desdehttps://huggingface.co/deepseek-ai/DeepSeek-V4-Flash[HuggingFace]. Figura 9 : "Retrieval performance remains highly stable within a 128K context window. While a performance degradation becomes visible beyond the 128K mark, the model’s retrieval capabilities at 1M tokens remain remarkably strong." Arquitetura CSA+HCA documentada secção 2.3.</p> </li> <li> <p><strong>GLM-5 Relatório Técnico</strong> —https://arxiv.org/abs/2602.15763[arXiv:2602.15763]. DSA introduzido via pré-treinamento contínuo, "lossless by construction". Contexto máximo 202.752 tokens. Tabelas 3/5/6 documentam o desempenho de longo contexto em comparação com 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. Estratégia de discard-all além do limiar nas tarefas agenteicas (confirmando implicitamente o limite prático do MLA em longo contexto).</p> </li> <li> <p><strong>Kimi K2 Relatório Técnico</strong> —https://arxiv.org/abs/2507.20534[arXiv:2507.20534]. Arquitetura MoE, otimizador MuonClip, desempenhos agentivos (HLE, BrowseComp, Terminal-Bench).</p> </li> </ol> </div> <div class="paragraph"> <p>O ponto mais revelador: em sua própria avaliação, Moonshot aplica uma estratégia de <code>discard-all</code> (supressão do contexto antigo) assim que a janela de contexto é ultrapassada. Isso confirma exatamente o que observei: o MLA sozinho não consegue manter a coerência em toda a janela de 256K. A arquitetura não acompanha.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_a_escolha_do_artesão">Conclusão: A Escolha do Artesão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depois de três semanas e treze sessões de desenvolvimento real, o veredicto é irrecorrível :</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 menos de 60K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sólido até 120K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Domine em toda parte</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Inutilizável além</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusões superficiais</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estável até 128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 sessões, abandonado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 sessões, abandonado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 sessões, adotado</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek-V4-Pro tornou-se meu LLM padrão para todas as sessões de desenvolvimento de software assistido com Opencode. Não porque é o mais recente. Não porque tem os melhores benchmarks acadêmicos. Mas porque, na vida real de um desenvolvedor que está enviando plugins Gradle Kotlin DSL com um contexto de agente de 30K tokens, é o único que não me trai quando o contexto se expande.</p> </div> <div class="paragraph"> <p>O CSA+HCA é um <strong>game changer</strong> arquitetural. A compressão de nível duplo + esparsificação não é um detalhe de implementação — é o que faz a diferença entre um assistente de código e um colega confiável.</p> </div> <div class="paragraph"> <p><em><em>_ Escolhi o DeepSeek-V4-Pro porque é o único dos três que transforma minha governança de agente de uma restrição defensiva ("como evitar que o agente esqueça?") em uma vantagem ofensiva ("o que podemos construir agora que o agente se lembra de tudo?"). </em>_</em></p> </div> <hr> <div class="paragraph"> <p>*Este artigo é o resultado de 13 sessões de desenvolvimento real no projeto`codebase-gradle`, documentadas em`.agents/sessions/`de acordo com a minha metodologia de governança agente Eager/Lazy/Hot/Warm/Cold. As fontes técnicas citadas são acessíveis publicamente no HuggingFace e 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="#_a_cena_sessão_051_algo_está_errado">A cena: sessão 051, algo está errado</a></li> <li><a href="#_a_auditoria_analisar_as_627_linhas">A auditoria: analisar as 627 linhas</a></li> <li><a href="#_o_medo_de_perder_a_engenharia">O medo de perder a engenharia</a></li> <li><a href="#_a_solução_split_enciclopédico">A solução : split enciclopédico</a></li> <li><a href="#_o_conteúdo_do_ficheiro_essentials">O conteúdo do ficheiro ESSENTIALS</a></li> <li><a href="#_o_resultado_50_de_contexto_eager">O resultado: -50% de contexto EAGER</a></li> <li><a href="#_por_que_a_pasta_se_chama_encyclopedies">Por que a pasta se chama `encyclopedies/</a></li> <li><a href="#_a_continuação_lógica_da_série">A continuação lógica da série</a></li> <li><a href="#_o_que_eu_teria_feito_diferente">O que eu teria feito diferente</a></li> <li><a href="#_o_guia_para_auditar_seu_próprio_contexto">O guia para auditar seu próprio contexto</a></li> <li><a href="#_uma_governança_viva">Uma governança viva</a></li> <li><a href="#_links">Links</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 14 minutes</div> <p>Você passou semanas construindo uma governança de agente impecável. Eager/Lazy, procedimento de fim de sessão, backups rotativos. O sistema está funcionando. Então, um dia, o agente fica lento. As respostas ficam diluídas. Você mede: 1414 linhas carregadas automaticamente. E o pior é que o culpado não é o código, nem o backlog, nem os arquivos de sessão. O culpado é o arquivo que documenta seu método.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_sessão_051_algo_está_errado">A cena: sessão 051, algo está errado</h2> <div class="sectionbody"> <div class="paragraph"> <p>30 de abril de 2026, 16h00. Estou em plena sessão sobre`magic-stick`, meu projeto de build da ISO Linux live. O agente Opencode carregou automaticamente meus arquivos Eager como sempre —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Tudo está normal.</p> </div> <div class="paragraph"> <p>Mas as respostas são mornas. O agente leva dois segundos a mais para raciocinar. Ele esquece um detalhe que tinha sob o nariz três mensagens antes. Não é um crash nem um erro — é uma degradação lenta, do tipo que não se percebe imediatamente.</p> </div> <div class="paragraph"> <p>Eu já tinha vivido isso na sessão 048, quando eu tinha descoberto que os arquivos de governança pesavam 5200 linhas acumuladas. Eu então tinha conceptualizado o mecanismo Hot/Warm/Cold com sua sliding window de 10 sessões, suas ondas frias idênticas, seu sensor com dois gatilhos. O problema estava resolvido. Em teoria.</p> </div> <div class="paragraph"> <p>Mas aqui, estamos na sessão 051. A rotação de backup ocorreu — os arquivos EAGER passaram de 2087 para 500 linhas. Porém, o contexto ainda está pesado. Algo me escapa.</p> </div> <div class="paragraph"> <p>Abro um terminal e digito :</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 linhas. A rotação de backup cortou bem em INDEX, SESSIONS_HISTORY e COMPLETED_TASKS — eles estão limpos. Mas há um elefante na sala que eu não tinha visto:<strong>627 linhas</strong>em um único arquivo.<code>AGENT_MODUS_OPERANDI.adoc</code>.</p> </div> <div class="paragraph"> <p>Este arquivo, esse é o que escrevi na sessão 1 para documentar a estratégia Eager/Lazy. É o manual do método. E ele se tornou, sozinho, 44% do 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 linhas rectangle "AGENT_MODUS_OPERANDI\n**627 linhas (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 linhas (20%)" as AG #BBDEFB rectangle "INDEX.adoc\n218 linhas (15%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS 213 linhas (15%)" as ARC #FFF9C4 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER — 1414 linhas rectangle "AGENT_MODUS_OPERANDI\n**627 linhas (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 linhas (20%)" as AG #BBDEFB rectangle "INDEX.adoc\n218 linhas (15%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS 213 linhas (15%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51 linhas (4%)" as PRO #E1BEE7 rectangle "SESSIONS_HISTORY 18 linhas (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>A ironia é total. O arquivo projetado para <strong>economizar</strong> de contexto tornou-se o principal <strong>consumidor</strong> de contexto. É como se o manual de uso do seu carro pesasse mais que o motor.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_auditoria_analisar_as_627_linhas">A auditoria: analisar as 627 linhas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Decido fazer uma auditoria seção por seção. Não para remover — para <strong>compreender</strong> o que merece estar em EAGER e o que poderia viver em outro lugar sem perda de conhecimento.</p> </div> <div class="paragraph"> <p>Eis a estrutura exata de`AGENT_MODUS_OPERANDI.adoc`e o que eu encontro:</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">Seção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Linhas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Conteúdo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Já presente em…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — Visão geral</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 resolvido, princípios fundamentais, analogia painel de instrumentos 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 — Estrutura dos ficheiros</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">Arborescência, política de carregamento, quando carregar o 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 — Regras 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 proibido, comandos destrutivos proibidos, segredos proibidos</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 da sessão</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">Modelo abertura, regras de trabalho, 6 etapas fim de sessão, checklist</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>§Fim sessão +<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — Métricas e limites</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">Sessão ideal (15-30 min, 1-3 ficheiros), sinais 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 sessões</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">Tabela de detecção, formato da proposta, exceções</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 — Melhoria contínua</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 acompanhamento, revisão 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 inicialização</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">novo projeto Bootstrap</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 — Referências</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">Arquivos de referência, recursos externos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>(arquivos 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">Glossário, histórico de versões</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O veredicto é irrecorrível:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Duplicatas integrais</strong>(167 linhas): P3, P4, P9 — tudo já está dentro`AGENT.adoc` ou <code>INDEX.adoc</code>, frequentemente palavra por palavra</p> </li> <li> <p><strong>Nunca consultado em prática</strong>(215 linhas) : P5, P6, P7, P8, Anexos — da meta-governança que nunca foi utilizada em nenhuma sessão</p> </li> <li> <p><strong>Conhecimento único</strong>(161 linhas) : P1 e P2 — o vocabulário LAZY/EAGER, a analogia, a política de carregamento</p> </li> </ul> </div> <div class="paragraph"> <p>Em 627 linhas,<strong>382 são barulho</strong>. E essas 382 linhas são carregadas <strong>a cada início de sessão</strong>, consumidas pelo agente, diluindo sua atenção mesmo antes de eu dizer olá.</p> </div> <div id="diag-audit-result" 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 Auditoria de AGENT_MODUS_OPERANDI.adoc — 627 linhas left to right direction rectangle "🟡 **Duplicados** ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Auditoria de AGENT_MODUS_OPERANDI.adoc — 627 linhas left to right direction rectangle "🟡 **Duplicados** 167 linhas (27%)" as DUP #FFF9C4 { card "P3 — Regras absolutas (34 linhas)" as D1 card "P4 — Ciclo de vida\n(133 linhas)" as D2 card "P9 — Referências\n(30 linhas)" as D3 } rectangle "�🔴 **Nunca consultado** 215 linhas (34%)" as JAM #FFCDD2 { card "P5 — Métricas\n(49 linhas)" as J1 card "P6 — Detecção (72 linhas)" as J2 card "P7 — Melhoria (39 linhas)" as J3 card "P8 — Bootstrap (13 linhas)" as J4 card "Anexos — Glossário (42 linhas)" as J5 } rectangle "�🟢 **Conhecimento único** 161 linhas (26%)" as UNI #C8E6C9 { card "P1 — Visão geral (64 linhas)" as U1 card "P2 — Estrutura dos arquivos (97 linhas)" 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 é a chave de tudo. Os duplicados (amarelo) são puro ruído — o agente os lê duas vezes, em dois arquivos diferentes. O nunca consultado (vermelho) é documentação morta — escrito com cuidado, nunca usado. Só o verde contém conhecimento que o agente não pode encontrar em outro lugar.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_medo_de_perder_a_engenharia">O medo de perder a engenharia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Neste momento, tenho a evidência diante de mim: devo reduzir`AGENT_MODUS_OPERANDI.adoc`. Mas eu hesito.</p> </div> <div class="paragraph"> <p>Este arquivo, eu escrevi à mão. Cada seção é o resultado de uma lição aprendida em uma sessão real. A parte P3 nasceu de um`rm -rf`acidental em`bakery-plugin`que me custou tokens reais do Firebase. A parte P4 é o resultado de quinze sessões em que eu esquecia de arquivar e perdia o fio. O procedimento em 6 etapas não saiu de um livro — saiu da dor.</p> </div> <div class="paragraph"> <p>Apagar essas seções seria jogar fora o histórico da minha própria engenharia. As lições que as produziram, as sessões durante as quais as descobri, os erros que nunca mais quero cometer. Não é texto — é experiência cristalizada.</p> </div> <div class="paragraph"> <p>É aqui que formulo o princípio que vai orientar a solução:</p> </div> <div class="paragraph"> <p><em><em>_ <strong>Nunca excluir. Sempre relocalizar.</strong>O conhecimento não precisa desaparecer do projeto. Ele apenas precisa não ser carregado automaticamente quando não for necessário. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_split_enciclopédico">A solução : split enciclopédico</h2> <div class="sectionbody"> <div class="paragraph"> <p>O modelo que proponho é simples e se inspira na forma como a Wikipédia cresceu: quando um artigo fica muito longo, não o cortamos — criamos um artigo detalhado e mantemos um resumo no artigo principal.</p> </div> <div class="paragraph"> <p>para`AGENT_MODUS_OPERANDI.adoc`, isso resulta :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Extrair</strong>as 161 linhas de conhecimento único (P1 + P2) em um novo arquivo`LAZY_EAGER_ESSENTIALS.adoc`— compactado em ~50 linhas, estritamente EAGER</p> </li> <li> <p><strong>renomear</strong> <code>AGENT_MODUS_OPERANDI.adoc</code> en <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code>— o arquivo original de 627 linhas, preservado <strong>intact</strong>, em armazenamento a frio</p> </li> <li> <p><strong>Nunca carregar</strong>o arquivo enciclopédia automaticamente — ele está lá para o ser humano, para a destilação futura, para o agente que será invocado daqui a seis meses com um modelo melhor</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 linhas (antes do split)" as BEFORE #FFCDD2 { } rectangle " " as ARROW1 rectangle " " as ARROW2 rectangle "**LAZY_EAGER_ESSENTIALS.adoc** **~50 linhas — EAGER**" as ESS #C8E6C9 { card "P1 condensada (15 linhas)" as E1 card "P2 condensada\n(35 linhas)" as E2 } rectangle ".agents/encyclopedies/**\n**LAZY_EAGER_ENCYCLOPEDIE.adoc**\n627 linhas — COLD" as ENC #BBDEFB { card "P1 para Anexos (integrais, intactos)" as C1 } BEFORE -[#4CAF50]-> ESS : "Extração de o conhecimento crítico" BEFORE -[#2196F3]-> ENC : "Preservação integral da engenharia" 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>O nome`encyclopedies/`Não é insignificante. Uma enciclopédia não é um dossiê de arquivos — é uma coleção de conhecimento organizada, consultável mas não portátil. Não se lê a Encyclopédie Universalis no metrô. Guardamo-la na biblioteca, e vamos lá quando temos uma pergunta específica.</p> </div> <div class="paragraph"> <p>É exatamente o papel desta pasta: uma biblioteca de referência fria, estruturada, exaustiva — que o agente não toca automaticamente.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_conteúdo_do_ficheiro_essentials">O conteúdo do ficheiro ESSENTIALS</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está como o novo arquivo se parece concretamente`LAZY_EAGER_ESSENTIALS.adoc`, extraído e compactado a partir de P1 e 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>Cinquenta linhas. É isso que o agente precisa para entender a mecânica. Tudo o mais — o histórico das lições, as analogias detalhadas, os procedimentos passo a passo, os anexos — vive na enciclopédia.</p> </div> <div class="paragraph"> <p>E o mais importante:<strong>nada foi excluído</strong>. Os 627 linhas de engenharia ainda estão lá, em`.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`. Elas estão apenas guardadas na biblioteca, em vez de no balcão de trabalho.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_resultado_50_de_contexto_eager">O resultado: -50% de contexto EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes do 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>Após o 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 após split enciclopédico — 837 linhas (-41%) rectangle "AGENT.adoc 287 linhas (34%)" as AG #BBDEFB ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Contexto EAGER após split enciclopédico — 837 linhas (-41%) rectangle "AGENT.adoc 287 linhas (34%)" as AG #BBDEFB rectangle "INDEX.adoc 218 linhas (26%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 linhas (25%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51 linhas (6%)" as PRO #E1BEE7 rectangle "ESSENTIALS 50 linhas (6%)" as ESS #A5D6A7 rectangle "SESSIONS_HISTORY\n18 linhas (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>O maior consumidor (AGENT_MODUS_OPERANDI, 627 linhas) foi substituído por um arquivo de 50 linhas. O ganho é imediato: 577 linhas de contexto liberadas. O agente respira.</p> </div> <div class="paragraph"> <p>E dentro`.agents/encyclopedies/`, o arquivo original de 627 linhas espera. Intacto. Com todas as suas seções — incluindo aquelas que são duplicatas, incluindo aquelas que nunca foram usadas. Porque um dia, um modelo melhor ou um cientista de dados humano quererá cruzar esses ângulos, essas redundâncias assumidas, essas lições aprendidas. E nesse dia, a matéria-prima estará lá.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_a_pasta_se_chama_encyclopedies">Por que a pasta se chama `encyclopedies/</h2> <div class="sectionbody"> <div class="paragraph"> <p>A escolha do nome não é cosmética. Ele codifica a filosofia do mecanismo.</p> </div> <div class="paragraph"> <p>Um <strong>arquivo</strong>.<code>archives/</code>) contém dados históricos organizados cronologicamente — como os COMPLETED_TASKS mensais. Um <strong>backup</strong> (<code>backup/</code>) é um snapshot com carimbo de data/hora — uma cópia de segurança de um estado passado.</p> </div> <div class="paragraph"> <p>Uma <strong>enciclopédia</strong>, é outra coisa. É uma coleção de conhecimento temático, estruturada por assunto, exaustiva mas não linear. Não se lê uma enciclopédia do início ao fim. início ao fim. Mergulha-se nela para responder a uma pergunta específica.</p> </div> <div class="paragraph"> <p>É exatamente o contrato deste dossiê :</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">Dossiê</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Função</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Acesso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Granularidade</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">Dados históricos (tarefas concluídas por mês)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY, estruturado</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">Snapshots frios (ondas de 10 sessões)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FRIO, cópia integral</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">Conhecimento temático exaustivo (metodologia, padrões)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FRIO, 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 distinção evita o fourre-tout. Cada arquivo sabe onde deve viver de acordo com <strong>o que contém</strong>, não de acordo com <strong>quando foi criado</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_continuação_lógica_da_série">A continuação lógica da série</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se você leu os dois primeiros artigos, eis como as três peças se encaixam:</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 Trilogia da Governança do Agente left to right direction package "�📖 **Artigo 0108** ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Trilogia da Governança do Agente left to right direction package "�📖 **Artigo 0108** Estratégia Eager/Lazy" as A1 #E8F5E9 { card "agente de memória entre sessões" as M1 card "Arquivos EAGER\n(auto-carregados)" as M2 card "Arquivos LAZY\n(sob demanda)" as M3 card "Procedimento de 6 etapas" as M4 } package "🧊 **Artigo 0110** Mecanismo Hot/Warm/Cold" as A2 #FFF9C4 { card "Envelhecimento do contexto" as V1 card "Janela deslizante 10 sessões" as V2 card "Onda fria idêntica" as V3 card "Sensor de dois gatilhos" as V4 } package "🔍 **Artigo 0111**\nAuditoria + Solução Enciclopédica" as A3 #BBDEFB { card "Auditoria dos ficheiros\nEAGER" as E1 card "Identificação\ndo desperdício" as E2 card "Dividir ESSENTIALS/enciclopédia" as E3 card "Preservação da engenharia" as E4 } A1 --> A2 : "A memória cresce → é preciso um mecanismo de envelhecimento" A2 --> A3 : "O envelhecimento não é suficiente → é necessário auditar o que merece estar em 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 : «Como dar uma memória ao agente entre duas sessões?</p> </li> <li> <p><strong>0110</strong>responde a : « Como impedir que essa memória afogue o agente ?</p> </li> <li> <p><strong>0111</strong>responde a: « E se o problema não for o tamanho dos arquivos, mas o que temos <strong>escolhido</strong> de colocar em EAGER ?</p> </li> </ul> </div> <div class="paragraph"> <p>O primeiro artigo construiu a estrutura. O segundo adicionou o mecanismo de envelhecimento. O terceiro audita o conteúdo — e descobre que a própria metodologia se tornou o problema.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_eu_teria_feito_diferente">O que eu teria feito diferente</h2> <div class="sectionbody"> <div class="paragraph"> <p>Retrospectivamente, vejo o erro de projeto inicial.`AGENT_MODUS_OPERANDI.adoc`a foi criado como um documento único — um manifesto. Essa foi a abordagem correta para formalizar o pensamento. Mas uma vez que o pensamento foi formalizado, o documento deveria ter sido dividido imediatamente: o essencial em EAGER, o exaustivo em cold.</p> </div> <div class="paragraph"> <p>Não o fiz porque estava orgulhoso do documento. 627 linhas de engenharia pura, escritas à mão, cada seção fruto de uma lição de sessão. Era minha obra. E, como todo autor, tive dificuldade em cortá-lo.</p> </div> <div class="paragraph"> <p>A lição:<strong>Não é porque um documento é bom que ele deve ser carregado automaticamente</strong>. A qualidade do conteúdo não tem qualquer relação com sua relevância para o contexto imediato do agente.</p> </div> <div class="paragraph"> <p>Hoje, a regra é simples: todo documento com mais de 100 linhas no contexto EAGER é um suspeito. Ele merece uma auditoria. Não uma condenação — uma auditoria. E a questão nunca é « devemos exclu‑lo? » mas « devemos carregá‑lo a cada sessão?</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_guia_para_auditar_seu_próprio_contexto">O guia para auditar seu próprio contexto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se você seguiu os dois primeiros artigos e implementou sua própria governança Eager/Lazy, aqui está um procedimento de auditoria em cinco etapas:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Medir</strong>:`wc -l`em todos os seus arquivos EAGER. O total deveria ser menos de 1000 linhas.</p> </li> <li> <p><strong>Identificar o maior</strong>: o arquivo que pesa mais de 20% do total é o suspeito número um.</p> </li> <li> <p><strong>Auditar seção por seção</strong>: para cada seção, pergunte-se « Essa informação já está em outro lugar? O agente já leu isso em outro arquivo? Isso foi usado nas últimas 5 sessões?</p> </li> <li> <p><strong>Classificador</strong>: duplicado, nunca usado, conhecimento único.</p> </li> <li> <p><strong>Divisor ou relocalizar</strong>: o que é único e crítico → ESSENTIALS compactado. Tudo o resto →<code>encyclopedies/</code>.</p> </li> </ol> </div> <div id="diag-audit-checklist" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-95d11b67afdc5242df4fd25cd1d42827.svg" alt="Procédure d’audit en 5 étapes" width="533" height="741"> </div> </div> <div class="paragraph"> <p>Este procedimento leva 15 minutos. Em um projeto de 50 sessões, ele economiza centenas de tokens por sessão futura. O ROI é imediato.</p> </div> </div> </div> <div class="sect1"> <h2 id="_uma_governança_viva">Uma governança viva</h2> <div class="sectionbody"> <div class="paragraph"> <p>O que esta série de três artigos me ensinou é que a governança de agentes não é um produto final. É un<strong>organismo vivo</strong>. Ela cresce com o projeto. Ela pega doenças de crescimento. Ela precisa de check-ups regulares.</p> </div> <div class="paragraph"> <p>Sessão 048 revelou que os arquivos estão inflando. Sessão 051 revelou que a própria metodologia está inflando. Sessão 060 provavelmente revelará outra coisa. É normal. É saudável. Uma governança que nunca se questiona é uma governança morta.</p> </div> <div class="paragraph"> <p>Os três mecanismos implementados — Eager/Lazy, Hot/Warm/Cold, split enciclopédico — formam um sistema de defesa em profundidade contra a saturação do contexto. Nenhum é suficiente por si só. Juntos, eles se complementam :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ansioso/Preguiçoso</strong>estrutura a informação <strong>por disponibilidade</strong></p> </li> <li> <p><strong>Quente/Morno/Frio</strong>estrutura a informação <strong>pela frescura</strong></p> </li> <li> <p><strong>Auditoria enciclopédica</strong>Estrutura a informação <strong>por densidade</strong></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 Defesa em Profundidade contra a Saturação do Contexto node "**Contexto Agente** ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam nodeBackgroundColor #E3F2FD title Defesa em Profundidade contra a Saturação do Contexto node "**Contexto Agente** ~800 linhas saudável" as CTX #C8E6C9 node "Camada 1\n**EAGER / LAZY**" as C1 #BBDEFB node "Camada 2\n**HOT / WARM / COLD**" as C2 #BBDEFB node "Camada 3 ESSENCIAIS / ENCICLOPÉDIA" as C3 #BBDEFB CTX --> C1 : "Estrutura por\n**disponibilidade**" CTX --> C2 : "Structure por **frescor**" CTX --> C3 : "Estrutura por **densidade**" 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>Com essas três camadas, o contexto do agente sobre`magic-stick`passou de 2087 linhas (antes de qualquer otimização) para cerca de 800 linhas — uma divisão por 2,6. Sem ter perdido uma única linha de documentação, um único arquivo de sessão, uma única lição aprendida.</p> </div> <div class="paragraph"> <p>Tudo está aqui. Só melhor organizado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Artigo 0108 — Estratégia Eager/Lazy :<a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Governar um agente IA com AsciiDoc</a></p> </li> <li> <p>Artigo 0110 — Mecanismo Hot/Warm/Cold :<a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Janela Deslizante e Onda Fria</a></p> </li> <li> <p>Meu site: <a href="https://cheroliv.com" class="bare">https://cheroliv.com</a></p> </li> <li> <p>O projeto`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>O conhecimento não precisa desaparecer. Ele apenas precisa não ser carregado quando não for necessário.</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="_resumo">Resumo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Após 48 sessões em um único projeto e 150+ no total, o sistema de governança Eager/Lazy que eu tinha construído com cuidado começou a se sufocar. Os arquivos de agentes, que deveriam ser leves, pesavam 5200 linhas acumuladas. O contexto auto-carregado aumentava mais rápido do que minha capacidade de controlá-lo. Este artigo conta como eu conceptualizei um mecanismo de backup — entre sliding window e uma onda fria idêntica — para manter um contexto ativo leve sem jamais perder nada.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_sinal_5200_linhas">O Sinal : 5200 linhas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estou no meio da sessão 048 sobre`magic-stick`, meu projeto de build de ISO Linux live. Opencode me observa. Como sempre, ele carregou automaticamente meus arquivos Eager no início da sessão —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Nada de anormal.</p> </div> <div class="paragraph"> <p>Exceto que algo está errado. As respostas são mais lentas. O raciocínio está mais diluído. O agente esquece detalhes que tinha diante dos olhos há duas mensagens.</p> </div> <div class="paragraph"> <p>Abro um terminal e digito:</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 linhas para INDEX. 55 para SESSIONS_HISTORY.<strong>1756 para COMPLETED_TASKS_ARCHIVE</strong>.</p> </div> <div class="paragraph"> <p>A pasta`sessions/`acrescenta mais ~3200 linhas. Total:<strong>5200 linhas</strong>de contexto que são carregados, de alguma forma, no cérebro temporário do agente.</p> </div> <div class="paragraph"> <p>A estratégia Eager/Lazy que eu tinha teorizado no artigo anterior funciona — mas ela tem um defeito de nascimento que eu não tinha antecipado : ela não tem<strong>sem mecanismo de envelhecimento</strong>. Cada sessão adiciona uma linha a <code>INDEX</code>, um parágrafo a <code>COMPLETED_TASKS</code>, um ficheiro em <code>sessions/</code>. Nada sai nunca. O contexto é uma bola de neve que aumenta a cada nova sessão.</p> </div> <div id="diag-growth" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-4c01a7afc09cf704c95519bf922f4b8c.svg" alt="Courbe de croissance des fichiers agents — de la session 1 à 48" width="468" height="591"> </div> </div> <div class="paragraph"> <p>Não é um bug, é uma consequência direta do procedimento de fim de sessão que arquiva meticulosamente cada detalhe. O sistema é vítima do seu próprio sucesso.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_diagnóstico_tríplice_redundância">O Diagnóstico : Tríplice Redundância</h2> <div class="sectionbody"> <div class="paragraph"> <p>Peço ao agente que diagnostique o problema. Sua resposta é imediata e cirú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">Arquivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Linhas</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">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 (carregado automático)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabela de todas as sessões desde a 001 —<strong>+1 linha por sessão</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">Tabela resumida —<strong>redundância com 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">ansioso (implícito)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detalhes completos de todas as sessões 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">~5200 total</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY (suposto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Arquivos individuais, mas<strong>não utilizadas</strong>parce que tudo já está em COMPLETED_TASKS</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O agente identifica quatro causas raízes :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE absorve tudo</strong>— Em vez de apontar para os arquivos`.sessions/`, ele copia integralmente cada sessão.</p> </li> <li> <p><strong>INDEX.adoc serve como histórico completo</strong>— A tabela "Sessões Recentes" contém 30+ entradas.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc redundante</strong>— Mesma informação que INDEX, formato diferente.</p> </li> <li> <p><strong>A regra LAZY não é respeitada</strong>— COMPLETED_TASKS é implicitamente EAGER porque contém tudo.</p> </li> </ol> </div> <div class="paragraph"> <p>Sua proposta é radical : limitar INDEX a 10 sessões, limpar COMPLETED_TASKS, mover SESSIONS_HISTORY para LAZY puro. Ganho imediato :<strong>~1900 linhas economizadas</strong>.</p> </div> <div class="paragraph"> <p>É limpo, eficiente e lógico. Mas tenho um problema com esta abordagem.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_eu_rejeitei_a_solução_óbvia">Por que eu rejeitei a solução óbvia</h2> <div class="sectionbody"> <div class="paragraph"> <p>A solução do agente é a de um engenheiro que otimiza um cache. Limitar. Truncar. Remover as redundâncias.</p> </div> <div class="paragraph"> <p>Mas essas "redundâncias" não são. Cada arquivo de governança captura un<strong>ângulo diferente</strong>na mesma realidade :</p> </div> <div class="ulist"> <ul> <li> <p><strong>ÍNDICE</strong>visão macro, dashboard executivo</p> </li> <li> <p><strong>SESSIONS_HISTORY</strong>= tabela cronológica linear, pontuada</p> </li> <li> <p><strong>COMPLETED_TASKS_ARCHIVE</strong>= narrativa detalhada com métricas</p> </li> <li> <p>sessions/*.adoc = arquivos individuais, contexto completo</p> </li> </ul> </div> <div class="paragraph"> <p>Não é duplicação boba. É<strong>perspectiva múltipla estruturada</strong>. É exatamente isso que precisamos para destilar — para que mais tarde, um humano (ou um LLM futuro melhor treinado) possa cruzar os ângulos e extrair padrões.</p> </div> <div class="paragraph"> <p>Imagine um cientista de dados dizendo a você: « Vamos remover 3 das 6 colunas, elas estão correlacionadas. » O que você responde a ele? Que a correlação não é redundância quando cada coluna captura uma dimensão diferente do mesmo fenômeno. Que é precisamente essa riqueza dimensional que torna o conjunto de dados utilizável.</p> </div> <div class="paragraph"> <p>É a minha intuição. E eu a defendo contra a racionalidade fria do agente.</p> </div> <div class="paragraph"> <p><em><em>_ Não vejo uma caixa de tudo silenciosa na minha ideia. Não enfiamos tudo, deslocamos o resultado estruturado do procedimento de fim de sessão — cada arquivo com seu ângulo, suas redundâncias que na verdade são um enriquecimento. É esse material multidimensional que será melhor para a destilação. </em>_</em></p> </div> <div class="paragraph"> <p>O agente leva o golpe. E se corrige.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_proposição_onda_fria_idêntica">A Proposição: Onda Fria Idêntica</h2> <div class="sectionbody"> <div class="paragraph"> <p>O agente então propõe um mecanismo mais fino, que respeita minha intuição de conjunto de dados rico, ao mesmo tempo em que resolve o problema técnico do contexto que explode.</p> </div> <div class="paragraph"> <p>O princípio é simples e inspira-se diretamente do pattern<strong>Quente/Morno/Frio Armazenamento</strong>aplicado à gestão de arquivos:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Quente (EAGER)</strong>= as 10 últimas sessões em INDEX, PROMPT_REPRISE da sessão N+1, os 2 últimos arquivos de sessão</p> </li> <li> <p><strong>Quente (LAZY)</strong>= SESSIONS_HISTORY recente, SCRIPT_VERIFICATION, toda a documentação de referência</p> </li> <li> <p><strong>Frio (backup/)</strong>= tudo o mais, deslocado<strong>intacto</strong>, sem transformação, sem reindexação</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... ---- A chave do mecanismo :**O backup não é um índice central, é uma cópia fiel da onda passada.**. Quando ultrapassamos o horizonte das 10 sessões ativas, não excluímos nada. Não reindexamos nada. Não fundimos nada. Pegamos o pacote de arquivos de agentes tal como estava na sessão N-10 e o movemos para`backup/`. Os arquivos ativos, eles, são truncados : * INDEX : apenas as 10 últimas linhas (sliding window) * SESSIONS_HISTORY : idem * COMPLETED_TASKS_ARCHIVE : novo arquivo para o período atual * sessions/ : apenas as 2 últimas sessões [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 Arquitetura Quente / Morno / Fria do Contexto do Agente package "HOT (EAGER)\nCarregado automaticamente\n~300 linhas" as HOT #FFCDD2 { file "INDEX.adoc (10 sessões)" as IDX_HOT file "PROMPT_REPRISE (sessão N+1)" as PRO_HOT file "AGENT.adoc\n(regras absolutas)" as AG_HOT } package "WARM (LAZY) Carregado sob demanda ~500 linhas" as WARM #FFF9C4 { file "SESSIONS_HISTORY\n(10 últimas)" as HIS_WARM file "SCRIPT_VERIFICATION (última)" as VER_WARM file "PROCEDURES.adoc (modelos)" as PRO_WARM file "*_REFERENCE.adoc\n(documento técnico)" as REF_WARM } package "COLD (backup/) Nunca carregado Leitura apenas 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(concluído)" as ARCH_COLD folder "sessões/ (001-039)" as SESS_COLD } folder "Y2026-040-???\n(futuro)" as FUTURE } HOT --> WARM : "agente sobe se necessário" WARM --> COLD : "Nunca automático O ser humano vai lá sozinho" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- O ganho imediato é massivo: o contexto EAGER passa de**~5200 linhas a ~300 linhas**. Uma divisão por 17. Sem ter perdido uma única linha de dados históricos. == Por que isso não é uma bolsa de tudo O agente, em sua primeira iteração, temia que`backup/`Torne-se uma caixa-preta — uma pasta onde se jogam arquivos que nunca serão relidos. É um medo legítimo. Mas ela se baseia numa confusão. Um saco de tudo é quando se lançam arquivos**sem estrutura, sem convenção, sem lógica de agrupamento**. Aqui, o backup é estruturado por período (Y2026-001-039), e cada pasta de backup contém**a mesma estrutura**que o arquivo`.agents/`ativo : INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/. Não é um saco de tudo. É um**instantâneo horodatado**. Se poderia até dizer que é um mecanismo de versionamento simplificado — à exceção de que ele não versiona os arquivos individualmente, mas o pacote completo da governança em um instante T. Quando você quiser encontrar uma informação antiga, não precisa de um índice central. Você tem duas opções: 1. **grep` direcionado**(blank)`grep -r "zsh" backup/Y2026-001-039/`— e você encontra tudo o que menciona zsh no período, independentemente do ângulo (INDEX, SESSIONS_HISTORY, arquivo de sessão). 2. **Reintegração manual**: você copia temporariamente a pasta de backup no contexto ativo e pede ao agente para analisar este período específico. O índice é implícito. Ele está na estrutura mesmo dos arquivos — cada um já sendo um índice a partir do seu próprio ângulo. == A Metáfora das Estantes Para tornar o mecanismo intuitivo, eu o concebi em três prateleiras: * **Prateleira 1 (EAGER)**— o plano de trabalho. O que eu preciso *agora*. ÍNDICE recente, PROMPT_REPRISE, regras absolutas. Leve, imediato, crítico. * **Prateleira 2 (LAZY)**— biblioteca de consulta. O que posso ir buscar a pedido. Referências técnicas, histórico recente, procedimentos. Mais volumoso, mas não carregado na memória. * **Porão (backup/)**— os arquivos frios. Tudo o que passou mas que eu não quero descartar. O agente nunca entra lá. O humano desce lá quando quiser destilar. O agente propôs inicialmente uma quarta prateleira — um`index-backup.adoc`que seria LAZY e conteria um sumário de todo o backup. Eu recusei. Seria uma redundância a mais em um sistema que já sofre de crescimento linear. A estrutura dos arquivos arquivados já é um índice. == O sensor de dois gatilhos A conceptualização era sólida, mas ainda havia um ponto cego:**Quando exatamente acionar a rotação ?**O artigo inicial o identificava como uma questão aberta. Dois dias depois, a resposta está codificada nos arquivos de governança de seis projetos: um sensor com dois gatilhos. === O Gatilho Automático — `N % 10 == 0 O primeiro gatilho é matemático. Quando o número da sessão é múltiplo de 10 — sessão 10, 20, 30, 40 — a rotação de backup é executada automaticamente dentro do procedimento de fim de sessão, logo após a etapa 6. Por que 10? É o compromisso entre duas forças opostas: uma janela muito curta (5 sessões) perde o contexto necessário à continuidade; uma janela muito longa (20 sessões) não resolve o problema de inchaço do contexto. Dez sessões, em um ritmo de uma a duas sessões por dia, cobrem aproximadamente uma semana de trabalho — suficiente para que o agente lembre das decisões recentes, mas não suficiente para que o contexto exploda. === O Gatilho por Limiar — 500 Linhas EAGER O segundo gatilho é dinâmico. Independentemente do número da sessão, se os arquivos EAGER acumulados ultrapassarem**500 linhas**, a rotação se dispara. Este limiar protege contra o cenário em que as sessões são excepcionalmente produtivas — muito conteúdo escrito em poucas sessões. Uma sessão que produz 120 linhas de conteúdo editorial faz aumentar COMPLETED_TASKS_ARCHIVE muito mais rápido do que uma sessão de depuração que corrige duas linhas. O limiar de 500 linhas, medido via`wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, captura essa assimetria. === O Gatilho Manual — "rotação de backup Finalmente, o ser humano permanece no controle. As palavras-chave`rotation backup`, `backup rotation` ou `lance la rotation backup`Disparam o procedimento mediante solicitação, independentemente do fim da sessão. Útil quando se sente que o contexto está ficando pesado, mas ainda não se está em um múltiplo de 10, ou quando se quer arquivar uma fase de trabalho antes de iniciar uma nova. [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 Rotação de Backup — Os Três Gatilhos start :Procédure de fin de session; note right: Mots-clés "fim da sessão"\nou "paramos aqui" :É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 mostra a inserção exata do sensor no procedimento de fim da sessão. A etapa 7 é opcional — ela só será executada se uma das duas condições for verdadeira — mas é sistematicamente *verificada*. A lista de verificação final inclui`[✅] 7. Backup roté (si applicable)`. === O Laço Fechado Este sensor fecha o laço aberto pelo artigo anterior. A governança Eager/Lazy havia resolvido o problema da memória do agente entre duas sessões. O mecanismo Hot/Warm/Cold resolveu o problema da memória que cresce. O sensor com dois gatilhos resolve o problema do *quand* — removendo ao ser humano a carga mental de monitorar o tamanho do 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 Os Três Camadas da Governança Agente left to right direction package "Camada 1 — Memória (Artigo 0108)" as C1 #E8F5E9 { rectangle "**EAGER** Painel de controle Carregado automaticamente" as EAG rectangle "**LAZY** Manual proprietário Carregado sob demanda" as LAZ EAG -[hidden]right-> LAZ } package "Camada 2 — Envelhecimento (Artigo 0110)" as C2 #FFF9C4 { rectangle "**HOT** 10 sessões ativas ~300 linhas" as HOT rectangle "**WARM** Referências Procedimentos" as WRM rectangle "**COLD** backup/ Onda de frio" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "Camada 3 — Gatilho (Hoje)" as C3 #BBDEFB { rectangle "**Auto** N % 10 == 0" as AUTO rectangle "**Limiar**\n> 500 linhas" as SEUIL rectangle "**Manuel** rotação de backup" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "A memória cresce\n→ é necessário um mecanismo\nde envelhecimento" C2 --> C3 : "O envelhecimento → é preciso um desencadeador para executá-lo" 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 ---- As três camadas se empilham logicamente. A primeira dá uma memória ao agente. A segunda impede que essa memória sufogue o agente. A terceira automatiza a manutenção dessa memória para que o humano não tenha que pensar nisso. === A Migração Efetiva no cheroliv.com O mecanismo não permaneceu teórico. Sobre`cheroliv.com`, a primeira rotação de backup foi executada em 29 de abril de 2026 — as sessões de -6 a 2 migraram para`.agents/backup/Y2026-sessions-neg6-a-002/` : |=== |Arquivo |Antes da rotação |Após rotação |ganho |`.agents/INDEX.adoc` |19 sessões listadas |10 sessões (3-12) |-9 entradas |`.agents/SESSIONS_HISTORY.adoc` |18 sessões |10 sessões |-8 entradas |`COMPLETED_TASKS_ARCHIVE` |161 linhas (sessões 1-12) |135 linhas (sessões 3-12) |-26 linhas |`sessions/` |20 arquivos |10 ficheiros |-10 arquivos |**cópia de segurança/** |Inexistente |1 onda fria (10 sessões arquivadas) |+1 pacote frio |=== O ganho em linhas foi modesto — o projeto é jovem, 12 sessões — mas o importante é que o**mecanismo está em posição**. A próxima rotação automática será acionada na sessão 20, ou mais cedo se as 500 linhas EAGER forem atingidas. == A Lição Humano-Agente Esta sessão 048 me ensinou algo fundamental sobre a colaboração com um agente de IA. O agente tem um viés natural : ele tenta**otimizar**, à **simplificar**, à **eliminar as redundâncias**. Este é o viés de um sistema treinado para produzir respostas limpas e concisas. Diante de um conjunto de dados rico e multidimensional, o primeiro reflexo dele é reduzi-lo à sua forma mais simples. O ser humano, ele, tem uma intuição diferente: ele sente que a redundância estruturada é um**trunfo**, não é um defeito. Que a diversidade dos ângulos sobre uma mesma realidade é precisamente o que permitirá, mais tarde, uma destilação de qualidade. Não é que o agente está errado. É que o seu 'óptimo' não é o meu. O agente otimiza para o**presente**— o contexto imediato, a resposta rápida à pergunta feita. O ser humano otimiza para o**futuro**— a capacidade de encontrar, cruzar, destilar em três meses ou três anos. ____ O que eu quero é o material bruto. Suas reflexões, suas hesitações, suas respostas às minhas perguntas. Não a sua síntese. A síntese, eu sei fazer melhor que você. Eu quero a matéria‑prima. ____ Esta frase que eu lhe disse no final da sessão resume tudo. O agente é uma ferramenta de produção. O humano é a ferramenta de destilação. A governança não foi feita para que o agente entenda tudo sozinho — foi feita para que o humano possa, mais tarde, trabalhar o material produzido. A onda fria idêntica é a tradução arquitetônica desta filosofia: não se joga nada, não se funde nada, não se reindexa nada. Move-se o pacote intacto. A destilação virá mais tarde, à mão, pelo humano. == Suquência Lógica do Artigo Anterior Se você leulink:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[o artigo sobre a estratégia Eager/Lazy], você reconhecerá a progressão natural: 1. **Artigo 0108**— A governança Eager/Lazy : *comment* estruturar o contexto do agente em dois níveis de disponibilidade 2. **Este artigo 0110**— O mecanismo de backup: *comment* como envelhecer este contexto sem perdê-lo quando ficar muito grande O primeiro artigo respondia à pergunta: « O agente não se lembra de nada entre duas sessões, como lhe dar uma memória? Ele responde à pergunta que decorre inevitavelmente da primeira: « A memória aumenta a cada sessão, como impedir que ela suffoque o agente sem apagá‑la ? A resposta está em um padrão:**Quente/Morno/Frio**, aplicado aos arquivos de governança. E em um princípio :**nunca perder nada, sempre realocar tudo**. == Links * Artigo anterior:link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governar um agente IA com AsciiDoc] * Meu site : https://cheroliv.com * O projeto`magic-stick`: https://github.com/cheroliv/magic-stick --- *Um bom sistema de governança nunca apaga dados. Ele os organiza.* ----</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="#_a_cena_un_projet_jhipster_un_build_qui_ne_charge_plus">A cena : un projet JHipster, un build qui ne charge plus</a></li> <li><a href="#_erro_1_a_variável_fantasma_reportsdir">Erro 1: a variável fantasma `reportsDir</a></li> <li><a href="#_erro_2_main_não_existe_mais_no_gradle_9">Erro 2 : <code>main = "…​"</code> não existe mais no Gradle 9</a></li> <li><a href="#_erro_3_sourcecompatibility_não_é_mais_uma_propriedade_de_projeto">Erro 3 : <code>sourceCompatibility</code> não é mais uma propriedade de projeto</a></li> <li><a href="#_erro_4_a_afirmação_groovy_de_três_operandos">Erro 4 : a afirmação Groovy de três operandos</a></li> <li><a href="#_erro_5_a_dependência_implícita_compilekotlin_openapigenerate">Erro 5 : a dependência implícita <code>compileKotlin</code> → `openApiGenerate</a></li> <li><a href="#_erro_6_generategitproperties_falha_em_filteroutputstream_write">Erro 6 : <code>generateGitProperties</code> falha em `FilterOutputStream.write()</a></li> <li><a href="#_finalmente_testcontainers_entra_em_cena">Finalmente: Testcontainers entra em cena</a></li> <li><a href="#_fase_1_a_pista_docker_java">Fase 1 : a pista docker-java</a></li> <li><a href="#_phase_2_pesquisa_web_e_trilha_de_navegação_github">Phase 2: pesquisa web e trilha de navegação GitHub</a></li> <li><a href="#_fase_3_a_armadilha_dos_artefatos_renomeados">Fase 3 : a armadilha dos artefatos renomeados</a></li> <li><a href="#_fase_4_forçar_a_resolução">Fase 4 : forçar a resolução</a></li> <li><a href="#_resultado_final">Resultado final</a></li> <li><a href="#_tabela_resumida_das_correções">Tabela resumida das correções</a></li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 15 minutes</div> <p>Você já conheceu esse momento onde um simples`./gradlew build`que você lança cem vezes por dia começa repentinamente a travar em um erro nunca visto? Multiplique isso por onze erros sucessivos, adicione uma boa dose de incompatibilidade Docker Engine 29, polvilhe com Gradle 9 que faz desaparecer APIs que utilizávamos há dez anos. Aqui está o log completo.</p> </div> <hr> <div class="paragraph"> <div class="title">Diagrama 1 — Migração Gradle 9 (cadeia de erros)</div> <p>Objetivo: mostrar a série de incompatibilidades.</p> </div> <div class="listingblock"> <div class="title">👉 Claro, centrado no Gradle.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml left to right direction title Migração Gradle 9 rectangle "1\nreportsDir" as A rectangle "2 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml left to right direction title Migração Gradle 9 rectangle "1\nreportsDir" as A rectangle "2 classePrincipal" as B rectangle "3 sourceCompatibility" as C rectangle "4 Groovy assert" as D A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">Diagrama 2 — Plugins JHipster incompatíveis</div> <p>Objetivo: isolar os plugins quebrados.</p> </div> <div class="listingblock"> <div class="title">👉 Visão limpa das dependências.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml left to right direction title Plugins a corrigir skinparam shadowing false skinparam roundcorner 18 rectangle "1 ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml left to right direction title Plugins a corrigir skinparam shadowing false skinparam roundcorner 18 rectangle "1 openApiGenerate" as A #FFF3E0 rectangle "2 gitProperties 2.5.7" as B #FFF3E0 rectangle "3 Versões" as C #E3F2FD rectangle "4 Montagem 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 runtime</p> </div> <div class="listingblock"> <div class="title">👉 Histórico claro do runtime.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1 ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1 Montado OK" as A #E8F5E9 rectangle "2 Testes Cucumber FALHA" as B #FFEBEE rectangle "3 Testcontainers 1.32 rejeitado" as C #FFF3E0 rectangle "4\nUpgrade\nversões" as D #E3F2FD rectangle "5 Compilação final OK" as E #E8F5E9 A --> B B --> C C --> D D --> E @enduml</pre> </div> </div> <hr> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-403cce144b6e403652d0a85cc9f6eaf9.png" alt="Diagram" width="1135" height="193"> </div> <div class="title">Figure 1. outra maneira de se representá-lo</div> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_un_projet_jhipster_un_build_qui_ne_charge_plus">A cena : un projet JHipster, un build qui ne charge plus</h2> <div class="sectionbody"> <div class="paragraph"> <p>O projeto`edster`est uma aplicação JHipster gerada em 2024. O script de construção raiz`build.gradle`permaneceu estável por meses. Então decidimos atualizar a versão :</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">Versão alvo</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">Mecanismo Docker</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>A mudança de versão Java ocorre via 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>Primeiro lançamento :</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>Nem mesmo conseguimos iniciar o carregamento do script de build. O problema está em`buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_erro_1_a_variável_fantasma_reportsdir">Erro 1: a variável fantasma `reportsDir</h2> <div class="sectionbody"> <div class="paragraph"> <p>O script`jhipster.cucumber-conventions.gradle`contém :</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>A variável definida é`cucumberReportsDir`. A usada é`reportsDir`-- que não está definida em nenhum lugar.</p> </div> <div class="paragraph"> <p><strong>Correção</strong></think> (Note: Since no French text was provided after the colon, there is nothing to translate. The output is therefore empty as per instructions.)<code>outputs.dir(cucumberReportsDir)</code></p> </div> </div> </div> <div class="sect1"> <h2 id="_erro_2_main_não_existe_mais_no_gradle_9">Erro 2 : <code>main = "…​"</code> não existe mais no Gradle 9</h2> <div class="sectionbody"> <div class="paragraph"> <p>Reprise imediata:</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 remove a propriedade`main`em proveito de`mainClass`nas tarefas`JavaExec`.</p> </div> <div class="paragraph"> <p><strong>Correção</strong>:`mainClass = "org.junit.platform.console.ConsoleLauncher"`</p> </div> </div> </div> <div class="sect1"> <h2 id="_erro_3_sourcecompatibility_não_é_mais_uma_propriedade_de_projeto">Erro 3 : <code>sourceCompatibility</code> não é mais uma propriedade de projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Novo erro:</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>O script raiz tinha:</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 remove essas propriedades no nível raiz. Eles devem viver dentro de um bloco`java`.</p> </div> <div class="paragraph"> <p><strong>Correção</strong>(Empty output)</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="_erro_4_a_afirmação_groovy_de_três_operandos">Erro 4 : a afirmação Groovy de três operandos</h2> <div class="sectionbody"> <div class="paragraph"> <p>O antigo script continha :</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>Em Groovy,<code>"21"</code> et <code>"24"`são strings truthy. A expressão resolve em</code>(…​ == "17") || true || true`, que é sempre verdadeira — mas a sintaxe é inválida para a afirmação estrita desejada.</p> </div> <div class="paragraph"> <p><strong>Correção</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="_erro_5_a_dependência_implícita_compilekotlin_openapigenerate">Erro 5 : a dependência implícita <code>compileKotlin</code> → `openApiGenerate</h2> <div class="sectionbody"> <div class="paragraph"> <p>O build está progredindo. Compilação Kotlin bem-sucedida. Então :</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 recusa as dependências implícitas entre tarefas. Como`compileKotlin`python print(" lê as fontes geradas por")<code>openApiGenerate</code>, é necessário declarar o link.</p> </div> <div class="paragraph"> <p><strong>Correção</strong>em`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`é necessário porque`openApiGenerate`é uma extensão (plugin OpenAPI Generator) e não uma tarefa diretamente acessível durante a fase de configuração.</p> </div> </div> </div> <div class="sect1"> <h2 id="_erro_6_generategitproperties_falha_em_filteroutputstream_write">Erro 6 : <code>generateGitProperties</code> falha em `FilterOutputStream.write()</h2> <div class="sectionbody"> <div class="paragraph"> <p>A compilação Java passa. Os recursos são processados. Então :</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>O plugin`gradle-git-properties`version 2.5.0 é incompatível com Java 21 / Gradle 9. Um bug interno tenta chamar`write(int)` por Groovy em um fluxo que ele fechou</p> </div> <div class="paragraph"> <p><strong>correção</strong>em`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_em_cena">Finalmente: Testcontainers entra em cena</h2> <div class="sectionbody"> <div class="paragraph"> <p>Até aqui, era depuração de script de build pura. Cada erro era uma incompatibilidade do Gradle 9 ou do Java 21 nos scripts de build. Após as seis correções acima, o`./gradlew assemble`passa com sucesso.</p> </div> <div class="paragraph"> <p>Mas`./gradlew build`executa também os testes, e os testes Cucumber usam o Testcontainers para iniciar um 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 é incapaz de comunicar com o Docker. Duas estratégias diferentes (variáveis de ambiente + soquete Unix) falham no mesmo erro.</p> </div> <div id="diag-docker-handshake" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers 1.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_a_pista_docker_java">Fase 1 : a pista docker-java</h2> <div class="sectionbody"> <div class="paragraph"> <p>Primeiro reflexo: o cliente Docker Java usado pelo Testcontainers envia a versão da API`1.32`no handshake HTTP, mas o Docker Engine 29.4.1 exige um mínimo de`1.40`O problema está do lado do cliente, não do daemon.</p> </div> <div class="paragraph"> <p>Verificação da versão do docker-java resolvida pelo 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, datando de Testcontainers 1.20.6. A última versão pública do docker-java é 3.5.1. Vamos tentar forçar a atualização da versão via`resolutionStrategy`no bloco`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>Reexecução do build. Mesmo erro:`client version 1.32 is too old`.</p> </div> <div class="paragraph"> <p>Verificação do cache Gradle: os JARs foram baixados novamente, mas o erro persiste. docker-java 3.5.1 ainda envia`1.32`. Esta versão, portanto, não é suficiente para Docker Engine 29.4.1.</p> </div> <div class="paragraph"> <p><strong>Ação de purificação</strong>: limpar completamente o cache do Gradle, só para ter certeza :</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>Recarga completa após limpeza. Mesmo erro.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_pesquisa_web_e_trilha_de_navegação_github">Phase 2: pesquisa web e trilha de navegação GitHub</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1 é insuficiente. Só resta procurar se alguém já encontrou este problema exato.</p> </div> <div class="paragraph"> <p>Pesquisa direcionada nos issues testcontainers-java e 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>Primeiros resultados imediatos :</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>O caminho de navegação está claro: o Docker Engine 29.x elevou sua versão mínima da API para`1.24`(defeito antigo) à`1.40`. Testcontainers 1.20.x utiliza o docker-java 3.4.x que negocia a versão da API enviando`1.32`. O daemon recusa educadamente mas firmemente.</p> </div> <div class="paragraph"> <p>No problema #11491, um mantenedor responde :</p> </div> <div class="paragraph"> <p>Esta resposta contém<strong>duas informações críticas</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+ resolve o problema</p> </li> <li> <p>Os módulos foram<strong>renomeados com o prefixo `testcontainers-</strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_a_armadilha_dos_artefatos_renomeados">Fase 3 : a armadilha dos artefatos renomeados</h2> <div class="sectionbody"> <div class="paragraph"> <p>A renomeação é bruta. No Testcontainers 2.x, nenhum dos nomes antigos funciona mais sob esse nome:</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">Nome antigo (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Novo nome (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">inalterado</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Primeira tentativa: aplicar a BOM Testcontainers 2.0.5 e os novos nomes de artefatos em`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>O BOM de testcontainers-bom não basta.</strong>Por quê? Porque o Spring Boot 3.4.5 expõe seu próprio BOM de gerenciamento de dependências.<code>spring-boot-dependencies</code>) que<strong>ganha</strong>no BOM do Testcontainers na resolução transitiva. Spring Boot corrige`testcontainers` à <code>1.20.6</code>, e portanto todos os artefatos que não estão explicitamente no BOM do Spring Boot (como os novos`testcontainers-*<code>) resolvem para os antigos nomes`1.20.6</code>-- que já não existem nesta versão.</p> </div> <div class="paragraph"> <p>Ao inspecionar o`dependencies --configuration testRuntimeClasspath`, encontra-se :</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 a substituição : Testcontainers 2.0.5 é <strong>requerido</strong>, mas Spring Boot força`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 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 (consumidor)" as BG #E3F2FD { rectangle "pedido\n`testcontainers-bom:2.0.5" as REQ rectangle "pedido `testcontainers-postgresql" as REQ2 } component "Maven Central" as MC #FFF3E0 component "Declarações" as DEC #E8F5E9 { rectangle "testcontainers-bom:2.0.5` corrige 2.0.5" as BOM2 rectangle "spring-boot-dependencies:3.4.5`\nfixa 1.20.6" as BOM1 } component "Resolução Gradle" as RES #FFEBEE { rectangle "Versão vencedora\n`testcontainers:1.20.6" as WIN #EF9A9A } BG --> DEC : "analisa as BOMs" BOM2 --> RES : "propõe 2.0.5" BOM1 --> RES : "propõe 1.20.6" WIN -> MC : "baixe\ntestcontainers: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_forçar_a_resolução">Fase 4 : forçar a resolução</h2> <div class="sectionbody"> <div class="paragraph"> <p>A estratégia se torna dupla:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Forçar o docker-java para sua versão 3.7.1 (testada como compatível com Docker Engine 29)</p> </li> <li> <p>Force o Testcontainers core para 2.0.5 contornando o BOM do 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 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle\n(com resolutionStrategy)" as BG #E8F5E9 { rectangle "BOM Testcontainers ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle\n(com resolutionStrategy)" as BG #E8F5E9 { rectangle "BOM Testcontainers `2.0.5" as BOM2 rectangle "resolutionStrategy\n.eachDependency" as RS #66BB6A } component "Conflito resolvido" as RESOLVED #E3F2FD { rectangle "docker-java\n`3.7.1` (forçado)" as DJ rectangle "testcontainers `2.0.5` (forçado)" as TC #81C784 rectangle "testcontainers-postgresql `2.0.5" as TPG rectangle "testcontainers-jdbc `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\npassa diretamente" RS -> DJ : "força 3.7.1" RS -> TC : "força 2.0.5" RESOLVED --> MC : "Baixe os JARs\ncompatíveis com Docker 29" BOM1 -[#gray,dashed]-> RESOLVED : "ignorado no 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>Correção final</strong>em`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`é a única maneira de contornar o BOM`spring-boot-dependencies`gerenciado pelo plugin Spring Boot. O teste de igualdade sobre`details.requested.name == "testcontainers"`é voluntariamente restritivo: forçamos apenas o módulo core. Os módulos`testcontainers-*`Seguem o BOM do Testcontainers 2.0.5 que declaramos explicitamente</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 conseguem criar seus containers PostgreSQL via Docker Engine 29.4.1. O erro de negócio final (HTTP 500 no teste Cucumber) é um problema de aplicação totalmente independente do script de build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_tabela_resumida_das_correções">Tabela resumida das correções</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">Arquivo</th> <th class="tableblock halign-left valign-top">Problema</th> <th class="tableblock halign-left valign-top">correção</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">Variável`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 proibido Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bloco`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">Asserção Groovy sintaticamente 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">Dependência 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`incompatível 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">Cache Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 testado, resolvido mas insuficiente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Limpeza + passagem 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 incompatível com Docker Engine 29</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Forçamento Testcontainers 2.0.5 + prefix`testcontainers-*`+ resolutionStrategy vs Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se o seu build JHipster/Gradle falhar após uma atualização de versão para Gradle 9 + Docker Engine 29, os erros se dividem em duas categorias :</p> </div> <div class="paragraph"> <p><strong>Erros de script de build</strong>(as 6 primeiras) : O Gradle 9 remove propriedades e sintaxes que vinham funcionando há anos (<code>sourceCompatibility=</code>, <code>main =</code>, <code>reportsDir</code>). São migrações mecânicas quando se conhece a nova API.</p> </div> <div class="paragraph"> <p><strong>Erros de tempo de execução Docker</strong>(as 2 últimas): Docker Engine 29.4.1 exclui clientes API < 1.40. Testcontainers 1.20.6 (imposto pelo Spring Boot 3.4.5) usa docker-java 3.4.1 que envia 1.32. Somente Testcontainers 2.0.5 + docker-java 3.7.1 resolve o problema, com a renomeação dos artefatos e a imposição de versão via`resolutionStrategy.eachDependency`como único meio de contornar o BOM implícito do Spring Boot.</p> </div> <div class="paragraph"> <p>O script de build Gradle na raiz do projeto está agora limpo.`./gradlew build`passa para o Java 21, Gradle 9.4.1, Spring Boot 3.4.5 e 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="_résumé">Résumé</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand on travaille avec un agent IA comme Opencode sur des projets complexes sur plusieurs sessions, on fait face à un problème fondamental : <strong>la fuite de contexte</strong>. L’agent ne se souvient pas de la session précédente. Tout ce qu’on lui a expliqué — l’architecture, les conventions, l’état du backlog — est perdu. Reconstruire ce contexte à chaque session est coûteux, lent et source d’erreur.</p> </div> <div class="paragraph"> <p>Cet article expose la stratégie artisanale que j’ai construite pour résoudre ce problème : un système de gouvernance persistant basé sur des fichiers AsciiDoc, avec une dichotomie <strong>Eager/Lazy</strong> pour optimiser la consommation du token de contexte, et une <strong>procédure de fin de session incontournable</strong> pour assurer la continuité.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_lundi_21_avril_9h00">La Scène : Lundi 21 Avril, 9h00</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je rouvre Opencode pour reprendre mon plugin Gradle <code>plantuml-plugin</code>. Hier soir, j’ai passé trois heures à discuter avec l’agent de l’architecture du pool de clés API — rotation round-robin, gestion des quotas, fallback automatique. Ce matin, l’agent me regarde avec des yeux de poisson rouge.</p> </div> <div class="paragraph"> <p><em><em>_ — Bonjour, je suis votre assistant Opencode. Comment puis-je vous aider aujourd’hui ? </em>_</em></p> </div> <div class="paragraph"> <p>Pas de — Ah oui, le pool de clés API, on en était à la structure YAML. Pas de — Attention, <code>PlantumlManager</code> est un objet Kotlin singleton, pas une classe. Pas de — Non, on a décidé hier que <code>SyntaxValidationResult</code> restait une sealed class nested dans <code>PlantumlService</code>.</p> </div> <div class="paragraph"> <p>Tout est à refaire. Ou plutôt : tout est à réexpliquer. Je vais passer les vingt premières minutes de ma session à reconstituer un contexte que l’agent a déjà eu entre les mains hier. Vingt minutes de tokens brûlés. Vingt minutes où je pourrais coder, mais où je fais du pédagogique obligatoire.</p> </div> <div class="paragraph"> <p>Ce n’est pas un bug d’Opencode. C’est la nature même des LLM conversationnels : entre deux sessions, la mémoire de travail est <strong>entièrement effacée</strong>. L’agent ne se souvient pas de la mission précédente, des décisions prises, des pièges identifiés, du code qu’on a écrit ensemble.</p> </div> <div class="paragraph"> <p>J’ai vécu ça des dizaines de fois. Sur quatre projets simultanés. Avec des sessions qui s’enchaînent sur des semaines. J’ai calculé : en moyenne, <strong>30 à 40 % du temps de session</strong> était consacré à recontextualiser l’agent. À la session 87 du projet <code>plantuml-plugin</code>, j’ai craqué. Je ne pouvais plus me permettre de réexpliquer pour la dixième fois que <code>AttemptEntry</code> est une data class top-level dans <code>DiagramProcessor.kt</code>.</p> </div> <div class="paragraph"> <p>Il me fallait un système. Pas un hack. Une vraie gouvernance.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_genèse_du_chaos_à_la_méthode">La Genèse : Du Chaos à la Méthode</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_les_premières_sessions_lâge_des_ténèbres">Les Premières Sessions : L’Âge des Ténèbres</h3> <div class="paragraph"> <p>Mon premier projet avec Opencode, <code>plantuml-plugin</code>, a démarré sans aucune gouvernance. Je pose une question, l’agent répond, on itère, la session se termine, et le lendemain on repart de zéro. C’était la session 1, puis la 2, puis la 3…​ jusqu’à la session 62 où je réalise que j’ai perdu des heures cumulées à réexpliquer la même architecture.</p> </div> <div class="paragraph"> <p>À la session 62, les chiffres sont là : <strong>198 tests unitaires passent</strong>, <strong>42 tests fonctionnels validés</strong>, le plugin fonctionne. Mais le coût cognitif est insupportable. Chaque nouvelle session commence par un monologue de vingt minutes sur la structure du projet.</p> </div> </div> <div class="sect2"> <h3 id="_lépisode_du_site_yml_détruit_session_2_bakery_plugin">L’Épisode du site.yml Détruit (Session 2, bakery-plugin)</h3> <div class="paragraph"> <p>La méthode naît aussi d’une catastrophe. Sur le projet <code>bakery-gradle</code>, à la session 2, je demande à l’agent de modifier le fichier <code>site.yml</code>. L’agent, sans vérifier si le fichier est versionné, fait un <code>Write</code> complet qui écrase le contenu. Résultat : les tokens réels (clés API Firebase, secrets de déploiement) sont remplacés par des placeholders factices. Le fichier n’était pas dans git — il était dans <code>.gitignore</code> pour protéger les secrets.</p> </div> <div class="paragraph"> <p>Sans sauvegarde. Sans <code>git restore</code> possible. Je suis bloqué. Il me faut reconstruire manuellement le fichier de configuration, retrouver les tokens dans mes gestionnaires de mots de passe, tout recoller.</p> </div> <div class="paragraph"> <p>C’est de cette frustration que naît la <strong>Règle Absolue 1b</strong> :</p> </div> <div class="paragraph"> <p><em><em>_ <strong>NE JAMAIS écraser</strong> un fichier config avec un <code>Write</code> complet quand un <code>Edit</code> partiel suffit. <strong>NE JAMAIS remplacer</strong> des valeurs sensibles par des valeurs factices. <strong>Vérifier <code>git check-ignore</code> et <code>git ls-files</code></strong> avant toute modification. </em>_</em></p> </div> <div class="paragraph"> <p>Cette règle, aujourd’hui gravée dans le marbre de tous mes fichiers <code>AGENT.adoc</code> et <code>INDEX.adoc</code> sur quatre projets, est née d’une erreur réelle qui m’a coûté une heure de travail manuel.</p> </div> </div> <div class="sect2"> <h3 id="_la_migration_markdown_asciidoc_session_1_cheroliv_com">La Migration Markdown → AsciiDoc (Session 1, cheroliv.com)</h3> <div class="paragraph"> <p>Le 25 avril 2026, sur <code>cheroliv.com</code>, je prends une décision radicale : convertir l’intégralité de la gouvernance de Markdown vers AsciiDoc. Ce n’est pas esthétique. C’est fonctionnel. AsciiDoc offre une structure sémantique que les LLM lisent mieux : sections hiérarchiques, tableaux typés, admonitions (<code>NOTE</code>, <code>WARNING</code>, <code>CAUTION</code>), attributs de document lisibles par la machine.</p> </div> <div class="paragraph"> <p>La session 1 de <code>cheroliv.com</code> formalise la structure :</p> </div> <div class="ulist"> <ul> <li> <p>Conversion de <code>AGENTS.md</code> en <code>AGENT.adoc</code></p> </li> <li> <p>Création des agents spécialisés : <code>CODER.adoc</code>, <code>SCRUM_MASTER.adoc</code>, <code>PLANTUML_DESIGNER.adoc</code></p> </li> <li> <p>Création de la structure Eager/Lazy : <code>INDEX.adoc</code>, <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 seul commit : <code>90975e9 refactor: migrate agent governance from Markdown to AsciiDoc</code>. Et le site continue de fonctionner.</p> </div> <div id="diag-timeline" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-1ffbad829836ed4bec6c66e6b3038145.svg" alt="Timeline de croissance des sessions sur les 4 projets" width="2373" height="290"> </div> </div> <div class="paragraph"> <p>La timeline ci-dessus illustre la progression réelle. Le point de bascule est la session 87 : c’est là que la frustration du recontextualisation répétée dépasse le seuil de tolérance, et que la méthode Eager/Lazy cesse d’être une idée pour devenir une obligation.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_stratégie_eagerlazy_en_profondeur">La Stratégie : Eager/Lazy en Profondeur</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_philosophie_cache_informatique_appliqué_à_la_cognition">Philosophie : Cache Informatique Appliqué à la Cognition</h3> <div class="paragraph"> <p>Mon approche s’inspire directement de la gestion de cache informatique. Tout ce qui est <strong>critique et fréquemment utilisé</strong> doit être immédiatement accessible (<strong>Eager</strong>). Tout ce qui est <strong>contextuel ou volumineux</strong> doit être chargé sur demande (<strong>Lazy</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 (Tableau de Bord)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lazy (Manuel du Propriétaire)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Taille</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">< 100 lignes, < 10k tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Illimité, détaillé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Chargement</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto, en début de session</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sur demande de l’agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Contenu</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Règles absolues, mission courante, état critique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archives de sessions, historique complet, procédures détaillées, références techniques</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Rôle</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Orienter immédiatement l’agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Répondre aux questions de contexte profond</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_les_fichiers_eager_le_tableau_de_bord">Les Fichiers Eager : Le Tableau de Bord</h3> <div class="paragraph"> <p>Ces fichiers vivent à la racine de chaque projet et sont chargés automatiquement par l’agent au début de chaque session. Ils forment le <strong>tableau de bord</strong> — information critique, immédiatement accessible.</p> </div> <div id="diag-eager-lazy" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-05c08d0c2b5bf285c4c1fee60314a0e7.svg" alt="Architecture Eager/Lazy des fichiers de gouvernance" width="1769" height="5760"> </div> </div> <div class="paragraph"> <p><strong><code>AGENT.adoc</code></strong> — Le fichier maître. Sur <code>cheroliv.com</code>, il fait 200 lignes et contient :</p> </div> <div class="ulist"> <ul> <li> <p>Les règles absolues du projet (pas de commit sans permission, pas de <code>rm</code> sans confirmation)</p> </li> <li> <p>La structure du projet et les conventions de code</p> </li> <li> <p>Les commandes essentielles (<code>./gradlew serve</code>, <code>./gradlew test</code>)</p> </li> <li> <p>Les épopées et le backlog produit (user stories priorisées)</p> </li> <li> <p>Les critères de qualité transverses (accessibilité, responsive, compatibilité)</p> </li> </ul> </div> <div class="paragraph"> <p>Sur <code>bakery-plugin</code>, la Règle 0 est différente : <strong><code>./gradlew -q publishToMavenLocal</code> obligatoire après chaque modification du code source</strong>. Parce que tester le plugin sans republier le JAR local m’a fait perdre une heure à débugger un code qui n’était pas encore empaqueté.</p> </div> <div class="paragraph"> <p><strong><code>PROMPT_REPRISE.adoc</code></strong> — La mission de la session en cours. Mis à jour à chaque fin de session, il contient :</p> </div> <div class="ulist"> <ul> <li> <p>Le numéro de session et la mission prioritaire</p> </li> <li> <p>Le résumé de la session précédente (ce qui a été fait, ce qui reste à faire)</p> </li> <li> <p>Les critères d’acceptation de la session courante</p> </li> <li> <p>Les rappels techniques spécifiques</p> </li> </ul> </div> <div class="paragraph"> <p><strong><code>.agents/INDEX.adoc</code></strong> — Le point d’entrée. Il résume les règles absolues, les sessions récentes, et surtout le <strong>portefeuille de projets</strong> gérés avec la même méthodologie. À ce jour, cinq projets y figurent :</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 | ---- **`*_ESSENTIALS.adoc`** -- Un ajout récent (Session 109, plantuml-plugin) pour optimiser encore le contexte Eager. Au lieu de charger 200 lignes de contexte métier sur le pool de clés API, je charge 50 lignes de l'essentiel, et les 150 autres lignes restent en LAZY dans `*_REFERENCE.adoc`. Résultat mesuré : passage de **~25k tokens EAGER à ~10k tokens** (gain de 60%). L'agent n'a plus besoin de rappels énergivores. ==== Le Chaînon Manquant : `opencode.json` Je dois vous avouer une chose que j'ai failli oublier de documenter. Au-dessus de tous ces fichiers .adoc, il y a un minuscule fichier JSON sans lequel rien ne fonctionne. Il s'appelle `opencode.json` et il fait six lignes. Littéralement six lignes. [source,json] ---- { "$schema": "https://opencode.ai/config.json", "instructions": [ "AGENT.adoc" ] } ---- C'est ce fichier qui dit à Opencode : « Au démarrage, charge `AGENT.adoc` automatiquement. » Sans lui, l'agent est une page blanche exactement comme je le décrivais au début de l'article. Avec lui, l'agent a déjà entre les mains les règles absolues, l'architecture du projet, et les commandes essentielles — avant même que je dise bonjour. J'ai découvert l'importance de ce fichier par hasard. Sur `bakery-plugin`, il n'existait pas. Je me demandais pourquoi l'agent était systématiquement plus « perdu » sur ce projet que sur les autres. Les règles absolues étaient bien dans `AGENT.adoc` — mais `AGENT.adoc` n'était jamais chargé. L'agent ne lisait que ce que je lui disais de lire, manuellement, à chaque session. C'était la session 11 de `bakery-plugin` quand j'ai réalisé l'absence du `opencode.json`. Je l'ai créé — et la session 12 a démarré comme les autres. Ce fichier est tellement évident pour moi maintenant que je ne pensais même plus à lui. Une erreur classique du développeur qui connaît trop son outil. Aujourd'hui, je le crée systématiquement *avant* `AGENT.adoc`. C'est la première pierre. ==== La Dualité de `INDEX.adoc` Une autre subtilité qui mérite d'être explicitée : `INDEX.adoc` vit dans `.agents/` — un dossier que j'ai présenté comme LAZY. Pourtant, je le liste comme EAGER dans tous mes tableaux. Il y a une tension apparente ici. La réalité terrain : les fichiers `.agents/INDEX.adoc` sont bien chargés automatiquement en début de session, au même titre que `AGENT.adoc` et `PROMPT_REPRISE.adoc`. Ils sont dans `.agents/` pour des raisons d'organisation — ne pas envahir la racine — mais leur comportement est EAGER. Sur `plantuml-plugin`, `INDEX.adoc` fait 200 lignes et contient les règles absolues *complètes* avec leur historique (les leçons des sessions passées), les EPICs avec scores, et le portefeuille de projets. C'est le document que l'agent consulte pour savoir « où on en est ». Sur `bakery-plugin`, il fait 150 lignes avec la roadmap et les sessions récentes. La redondance volontaire entre `AGENT.adoc` et `INDEX.adoc` peut surprendre. Les règles absolues sont présentes dans les deux. Pourquoi ? Parce qu'elles remplissent deux rôles différents : dans `AGENT.adoc`, elles sont *explicatives* (le storytelling de la règle, la leçon apprise) ; dans `INDEX.adoc`, elles sont *exécutives* (la règle nue, sans justification, pour une consultation rapide). L'agent lit `AGENT.adoc` une fois pour *comprendre* ; il relit `INDEX.adoc` à chaque session pour *appliquer*. Deux usages, deux formats. [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 Dualité AGENT.adoc ←→ INDEX.adoc left to right direction rectangle "AGENT.adoc\n(Racine — EAGER)" as AGENT #E3F2FD { rectangle "📖 **Format Narratif**\nLe storytelling de la règle\nla leçon apprise, le contexte" as NARR rectangle "🏗️ **Architecture Complète**\nStructure projet, composants\nBacklog détaillé US" as ARCHI rectangle "📋 **Règles Explicatives**\nPourquoi la règle existe\nHistorique de l'incident" as EXPL } rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 { rectangle "⚡ **Format Exécutif**\nLa règle nue, sans justification\nConsultation rapide" as EXEC rectangle "📊 **Roadmap & EPICs**\nTableau récapitulatif\nProgression, Score, Priorité" as ROAD rectangle "🌐 **Portefeuille Projets**\nVue transverse\n5 projets synchronisés" as PORT } AGENT --> INDEX : "Agent lit AGENT.adoc\n1 fois pour **comprendre**" INDEX --> AGENT : "Agent relit INDEX.adoc\nchaque session pour **appliquer**" 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 ---- Cette redondance assumée est un choix de conception. Elle consomme ~50 lignes supplémentaires de tokens EAGER — mais elle garantit que l'agent a toujours les règles sous les yeux, y compris dans le format concis qui facilite l'obéissance immédiate. === Les Fichiers LAZY : Le Manuel du Propriétaire Ces fichiers vivent dans `.agents/` et ne sont lus que quand l'agent en a besoin. Ils constituent la véritable richesse de la méthode, car ils accumulent la connaissance du projet sans polluer le contexte courant. [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\n(EAGER -- 200 lignes)" as IDX #E8F5E9 file "AGENT_SESSION_MANAGER.adoc\n(Template session)" as ASM file "SESSION_CHECKLIST.adoc\n(Quand changer)" as CHK file "PROCEDURES.adoc\n(6 étapes + LAZY/EAGER)" as PRO file "SESSIONS_HISTORY.adoc\n(Toutes sessions)" as HIS folder "sessions/" as SESS { file "1-chore-migration.adoc" as S1 file "109-formalisation-lazy.adoc" as S109 #FFECB3 file "133-epic11-article.adoc" as S133 file "... +130 autres" as SMORE } folder "archives/" as ARCH { file "COMPLETED_TASKS_2026-04.adoc" as CTA file "SESSIONS_HISTORY_83-95.adoc" as SHIST folder "sessions_summaries/" 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 : "Indexe" IDX --> HIS : "Indexe" IDX --> ARCH : "Référence" note right of S109 Session 109 = Formalisation stratégie LAZY/EAGER Token : ~25k → ~10k end note @enduml ---- L'arborescence ci-dessus montre la structure réelle du dossier `.agents/` sur `plantuml-plugin`, le projet le plus mature. Notez la profondeur en trois couches : fichiers racine (métadonnées), dossier `sessions/` (archives chronologiques), et dossier `archives/` (agrégations et résumés). C'est cette profondeur qui transforme la gouvernance d'un simple fichier TODO en une **mémoire organisationnelle complète**. **`.agents/sessions/{N}-{titre}.adoc`** -- Les archives détaillées de chaque session. Actuellement : * `plantuml-plugin` : **133 sessions archivées** (de la session 1 à 133) * `bakery-plugin` : **11 sessions** * `magic-stick` : **23 sessions** * `cheroliv.com` : **9 sessions formelles** + 7 sessions pré-système reconstituées rétroactivement Chaque archive contient le contexte complet de la session, les décisions prises, les problèmes rencontrés et leur résolution, les commandes exécutées et leur output. **`.agents/SESSIONS_HISTORY.adoc`** -- Un tableau récapitulatif de toutes les sessions avec un score. Exemple sur `cheroliv.com` :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>| -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</pre> </div> </div> <div class="paragraph"> <p><strong><code>.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc</code></strong> — Les tâches terminées archivées par mois, pour ne pas surcharger le backlog actif. Quand une user story est terminée, elle migre ici. Le backlog reste lisible : maximum 10 items actifs.</p> </div> <div class="paragraph"> <p><strong><code>.agents/PROCEDURES.adoc</code></strong> — Templates détaillés de la procédure de fin de session. Long, mais lu une seule fois par l’agent quand il apprend la méthode. Ensuite, la procédure devient mécanique.</p> </div> <div class="paragraph"> <p><strong><code>.agents/AGENT_MODUS_OPERANDI.adoc</code></strong> — La documentation stratégique complète. Sur <code>plantuml-plugin</code>, ce fichier fait <strong>900+ lignes</strong> et se nomme en réalité <code>AGENT_METHODOLOGIES.adoc</code> — j’ai changé le nom entre l’écriture de cet article et la mise en place effective. Ce genre de divergence de naming est inévitable dans un système artisanal qui évolue. L’important est la convention de nommage : si le fichier documente la <strong>méthode</strong>, il commence par <code>AGENT_</code> ou un préfixe explicite. Il documente la méthodologie Eager/Lazy, les patterns à suivre, les anti-patterns à éviter. Il est LAZY parce qu’un agent n’a pas besoin de relire toute la stratégie à chaque session, seulement quand il y a ambiguïté.</p> </div> <div class="paragraph"> <p><strong><code>*_REFERENCE.adoc</code></strong> — Les références techniques spécifiques au projet. Sur <code>magic-stick</code>, deux fichiers LAZY denses :</p> </div> <div class="ulist"> <ul> <li> <p><code>AB_PARTITION_REFERENCE.adoc</code> (147 lignes) — Architecture partition A/B GPT, scripts <code>update-system.sh</code>, tailles estimées, mécanisme de rollback</p> </li> <li> <p><code>BOOT_TEST_REFERENCE.adoc</code> (144 lignes) — Procédure QEMU + VNC pour tester le boot de l’ISO sans matériel physique, checklist BIOS/UEFI, limitations CI/CD</p> </li> </ul> </div> <div class="paragraph"> <p>Sur <code>plantuml-plugin</code> :</p> </div> <div class="ulist"> <ul> <li> <p><code>ARCHITECTURE.adoc</code> (134 lignes) — Structure des 11 data classes, points d’attention (pièges à éviter), commandes de test optimisées</p> </li> <li> <p><code>API_KEY_POOL_REFERENCE.adoc</code> — Détails complets du pool de clés (LAZY pendant que <code>ESSENTIALS</code> est EAGER)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_les_agents_spécialisés_une_équipe_virtuelle">Les Agents Spécialisés : Une Équipe Virtuelle</h2> <div class="sectionbody"> <div class="paragraph"> <p>La gouvernance ne se limite pas à des fichiers passifs. J’ai formalisé des <strong>rôles d’agents spécialisés</strong> dans des fichiers LAZY dédiés, qui définissent le workflow attendu selon le type de tâche.</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">Agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Projet</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CODER</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>CODER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implémentation FTL/CSS/JS, balises sémantiques, critères d’accessibilité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>SCRUM Master</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SCRUM_MASTER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Planification US, découpage en sous-tâches, détection des dépendances</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PlantUML Designer</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PLANTUML_DESIGNER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Création de diagrammes, syntaxe PUML, intégration JBake</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le fichier <code>CODER.adoc</code> sur <code>cheroliv.com</code> contient des règles concrètes : <em>Un seul <code><h1></code> par page</em>, <em>Préfixer les chemins avec `${content.rootpath}`</em>, <em>Déclarer la langue `<html lang="${content.lang!"fr"}">`</em>. Ces conventions, écrites une fois, sont respectées automatiquement par l’agent depuis la session 1.</p> </div> <div class="paragraph"> <p>Le fichier <code>SCRUM_MASTER.adoc</code> impose une structure de livrable : <strong>Objectif</strong>, <strong>Tâches</strong> (ordonnées avec assignation), <strong>Critères d’acceptation</strong>, <strong>Risques</strong>. Quand je demande un plan d’action, l’agent produit cette structure sans que je l’aie demandée. La gouvernance <strong>programme</strong> l’agent.</p> </div> <div class="sect3"> <h4 id="_quand_les_agents_spécialisés_deviennent_indispensables">Quand les Agents Spécialisés Deviennent Indispensables</h4> <div class="paragraph"> <p>La création des agents spécialisés suit une courbe naturelle. Au début d’un projet, vous n’en avez pas besoin — <code>AGENT.adoc</code> suffit largement. Mais quand le projet grandit (disons, au-delà de 20 sessions), deux signaux doivent vous alerter :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>L’agent mélange les conventions de deux domaines distincts (ex: syntaxe PlantUML et règles CSS)</p> </li> <li> <p>Vous passez plus de temps à corriger l’agent sur des conventions que vous lui avez déjà expliquées 5 fois</p> </li> </ol> </div> <div class="paragraph"> <p>Sur <code>cheroliv.com</code>, c’est arrivé à la session…​ 1. Oui, dès le départ. Parce que ce projet est un site web avec trois langages (FTL, CSS, JS), du contenu AsciiDoc, et des diagrammes PlantUML — trois domaines qui n’ont rien à voir. L’agent CODER a besoin de connaître les tailles de police et les media queries ; l’agent PLANTUML_DESIGNER a besoin de connaître la syntaxe <code>@startuml</code>. Sans séparation, l’agent CODER me proposait des diagrammes, et vice versa. Le chaos.</p> </div> <div class="paragraph"> <p>Sur <code>jhipster-gradle-plugins</code>, j’ai créé deux agents spécialisés adaptés au développement de plugins Gradle : <code>PLUGIN_DEVELOPER.adoc</code> et <code>BACKLOG_MANAGER.adoc</code>. Le premier encode toutes les conventions Kotlin/Gradle (pas de <code>!!</code>, data classes pour les modèles, <code>@TaskAction</code> pour les tâches). Le second sait que <code>persistence</code> doit être stable avant que <code>assistant</code> ne démarre son développement — une dépendance critique dans un mono-repo.</p> </div> <div class="paragraph"> <p>L’erreur à ne pas commettre : créer trop d’agents trop tôt. <code>plantuml-plugin</code> a attendu la session 108 avant de formaliser un agent spécialisé pour le pool de clés API. Avant ça, le contexte métier tenait dans <code>AGENT.adoc</code>. La règle empirique : un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes de documentation.</p> </div> </div> <div class="sect3"> <h4 id="_la_convention_de_nommage_des_sessions">La Convention de Nommage des Sessions</h4> <div class="paragraph"> <p>Un détail qui paraît futile mais qui devient critique quand on atteint 100 sessions. Comment nommer les fichiers d’archive ?</p> </div> <div class="paragraph"> <p>J’ai appris à mes dépens qu’une convention est nécessaire — quatre projets, quatre formats différents au début, et je ne m’y retrouvais plus. Aujourd’hui, la convention que j’ai stabilisée est :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- {N}-{type}-{sujet-kebab-case}.adoc ---- Exemples concrets : * `1-chore-migration-gouvernance-agent.adoc` — session 1, type chore * `10-solidification-tests.adoc` — session 10, sans type explicite (le sujet suffit) * `036-debug-graphify-symlink-epic9.adoc` — session 36 avec numéro sur 3 chiffres pour le tri Le numéro de session est le critère de tri principal. Les projets utilisant des numéros sur 3 chiffres (001, 036, 133) évitent les problèmes de tri lexicographique quand on dépasse 99. C'est ce que j'utilise désormais sur `magic-stick` : `001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`. Le type est facultatif et dérivé des mots-clés de la session (debug, feature, refactor, docs, chore, test). Le sujet en kebab-case est la partie la plus importante : il doit permettre de retrouver une session sans ouvrir le fichier. Si vous vous demandez « c'était quelle session où on a corrigé le timeout des tests d'intégration ? », la réponse est `124-fix-timeout-integration-test.adoc`. Pour les sessions historiques reconstituées (projets nés avant la gouvernance), j'utilise des numéros négatifs. Sur `cheroliv.com`, les sessions -6 à 0 couvrent toute l'histoire pré-gouvernance du projet. Et pour les sessions « non documentées » ou perdues, je crée une entrée dans `SESSIONS_HISTORY.adoc` sans archive correspondante, avec un score `?`. C'est plus honnête que faire semblant. [plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Convention de Nommage des Sessions start :Une session se termine; note right: Trigger "fin de session" if (Session antérieure\nà la gouvernance ?) then (oui) :Numéro **NÉGATIF**\n-6, -5 ... 0; note right: Historique\nreconstitué :Suffixe : reconstitution; else (non) :Numéro **POSITIF**\nsur 3 chiffres si > 99; note right: 001, 036, 133\npour le tri lexicographique :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 :Formuler le **SUJET** en kebab-case; note right Ex: fix-timeout-integration-test Doit permettre de retrouver sans ouvrir le fichier end note endif :Nom final : {N}-{type}-{sujet}.adoc; 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 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 **?**\n**sans archive**; note right: L'honnêteté\nplutôt que le vide endif stop @enduml ---- ==== `TEST_COVERAGE_ANALYSIS.adoc` — L'Étape 5 Décortiquée L'étape 5 de la procédure de fin de session est la plus mystérieuse. Elle dit « Mettre à jour `TEST_COVERAGE_ANALYSIS.adoc` si des tests ont été ajoutés ou modifiés. » Mais à quoi ressemble ce fichier ? Sur `plantuml-plugin`, il a évolué de quelques lignes à une structure complète. Voici sa forme stabilisée : [source] ---- = Analyse de Couverture de Tests == Suivi des Tests |=== | Classe de test | Type | Tests | Statut | Dernière MAJ | PlantumlServiceTest | unit | 45/45 | ✅ PASS | 2026-04-23 | ApiKeyPoolTest | integration | 15/15 | ✅ PASS | 2026-04-20 |=== == Historique par Session | Session | Tests ajoutés | Tests modifiés | Couverture | 133 | 0 | 2 | 100% | 132 | 5 | 0 | 100% |=== ---- L'intérêt n'est pas le fichier lui-même — c'est l'obligation de *noter* ce qui a changé. Sans cette étape, après 50 sessions, vous ne savez plus quels tests couvrent quoi. L'agent non plus. Le fichier devient le référentiel unique de vérité sur la couverture de tests du projet. Pour les projets sans tests traditionnels (comme `magic-stick` qui teste des scripts bash), l'étape 5 est remplacée par `SCRIPT_VERIFICATION.adoc`. Le mécanisme est le même : un fichier qui suit l'état de validation des scripts. Adaptez l'étape 5 à votre projet, mais ne la sautez jamais. Elle est le filet de sécurité qui empêche la régression silencieuse. Si votre projet n'a *aucun* test — ni unitaire, ni fonctionnel, ni script — créez quand même le fichier vide avec une section « À faire : définir une stratégie de test. » C'est un marque-page qui rappellera à votre futur vous que ce sujet n'est pas traité. [plantuml, format=svg, id=diag-session-flow, alt="Flux d'une session type avec Eager/Lazy et agents"] ---- @startuml skinparam backgroundColor #FEFEFE start :Début session; note right: L'agent est une page blanche :Chargement EAGER auto; note right * AGENT.adoc (règles absolues) * PROMPT_REPRISE.adoc (mission N) * INDEX.adoc (état projet) end note if (Mission claire ?) then (oui) :Exécution directe; else (non) :Charge LAZY sur demande; note right * SESSIONS_HISTORY.adoc (contexte passé) * sessions/{N-1}-*.adoc (décisions) * *_REFERENCE.adoc (architechture) end note endif :Délégation agent spécialisé ?; 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 :Travail de la session; :Fin de session (trigger utilisateur); :Procédure 6 étapes; note right 1. Archive sessions/N-*.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 :Checklist [✅] x 6; stop @enduml ---- Le diagramme ci-dessus montre le cycle de vie complet d'une session. Le point clé est la bifurcation après le chargement EAGER : soit la mission est assez claire pour exécuter directement (80% des cas), soit l'agent charge du LAZY pour résoudre une ambiguïté (20% des cas). C'est cette discrimination qui économise les tokens. == La Procédure de Fin de Session : La Règle d'Or === Pourquoi elle est Incontournable Sans cette procédure, la stratégie Eager/Lazy ne sert à rien. C'est elle qui transforme le travail de la session en information persistante. Elle s'exécute **à la demande explicite de l'utilisateur** (mots-clés : "fin de session", "je quitte", etc.), et elle est **obligatoire** -- aucune exception, aucune omission. Le fichier `SESSION_CHECKLIST.adoc` définit des métriques de session idéale : * Durée : 15-30 minutes * Fichiers modifiés : 1-3 maximum * Échanges LLM : 5-10 messages * Contexte tokens : < 50k Et des signes qu'il faut changer de session : _Le LLM répète des erreurs déjà corrigées_, _Plus de 3 fichiers modifiés en parallèle_, _Conversation > 50 messages_. La règle d'or : **Mieux vaut 5 sessions de 20 minutes qu'une session de 2 heures avec debugging chaos.** === Le Flux des 6 Étapes (Silencieusement) [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 start :L'utilisateur dit "fin de session"; note right: Mots-clés déclencheurs :Agent détecte le trigger; :Étape 1\nCréer archive\n`.agents/sessions/N-*.adoc`; note right: Tout le contexte de la session :Étape 2\nMettre à jour\n`PROMPT_REPRISE.adoc`; note right: Mission N + critères d'acceptation N+1 :Étape 3\nMettre à jour\n`SESSIONS_HISTORY.adoc`; note right: Ligne récap : # / Date / Type / Sujet / Score :Étape 4\nMettre à jour\n`INDEX.adoc`; note right: État courant, roadmap, fichiers modifiés :Étape 5\nMettre à jour\n`TEST_COVERAGE_ANALYSIS.adoc`; note right: Si tests ajoutés ou modifiés :Étape 6\nMettre à jour\n`COMPLETED_TASKS_ARCHIVE.adoc`; note right: Archiver tâches terminées :Afficher la checklist de confirmation; note right: Vérifier que chaque [✅] est mérité stop @enduml ---- === Les Résultats de 150+ Sessions Voici ce que donne cette procédure appliquée systématiquement sur mes quatre projets : **plantuml-plugin** : * **133 sessions** depuis le début du projet * **240/240 tests PASS** (100% couverture) -- EPICs 1-7 terminées * **57 scénarios Cucumber BDD** validés * Règle de sûreté sur les fichiers de config née d'une erreur réelle (Session 2 bakery-plugin) **bakery-plugin** : * **11 sessions** en deux semaines * Migration Supabase → Firebase terminée (9 tests corrigés) * EPIC 6 (publishProfile) fonctionnel en production * Règle 0 créée : `publishToMavenLocal` obligatoire après chaque modif **magic-stick** : * **23 sessions** pour construire un système live Xubuntu avec partition A/B * Première ISO générée à la session 10 * Tests de boot QEMU + VNC formalisés (documentation LAZY de 144 lignes) * CI/CD SourceForge fonctionnel **cheroliv.com** : * **9 sessions formelles** + reconstitution de 7 sessions pré-système * Article 0101 (OpenCode PATH) publié * Article 0108 (celui-ci) réécrit après analyse de ses lacunes * Gouvernance complète migrée de Markdown vers AsciiDoc === La Checklist Finale Après exécution silencieuse des 6 étapes, l'agent doit afficher une checklist de confirmation :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>✅ Procédure de fin de session exécutée 📋 Checklist : [✅] 1. Archive session N créée [✅] 2. PROMPT_REPRISE.adoc mis à jour pour session N+1 [✅] 3. SESSIONS_HISTORY.adoc mis à jour [✅] 4. INDEX.adoc mis à jour [✅] 5. TEST_COVERAGE_ANALYSIS.adoc mis à jour (si applicable) [✅] 6. COMPLETED_TASKS_ARCHIVE.adoc mis à jour</pre> </div> </div> <div class="paragraph"> <p><strong>Règle absolue</strong> : aucune étape ne peut être marquée <code>[✅]</code> si le fichier n’a pas été effectivement modifié et vérifié.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_guide_de_bootstrap_jour_1_session_0">Le Guide de Bootstrap : Jour 1, Session 0</h2> <div class="sectionbody"> <div class="paragraph"> <p>Vous êtes convaincu par la méthode. Vous voulez l’appliquer à un nouveau projet. Par où commencer ?</p> </div> <div class="paragraph"> <p>J’ai vécu ce moment le 28 avril 2026. J’ouvre Opencode sur <code>jhipster-gradle-plugins</code>, mon mono-repo de deux plugins Gradle JHipster. C’est un projet qui existe déjà — le code est là, les tâches Gradle fonctionnent. Mais la gouvernance agent ? Zéro. Page blanche. Comme <code>plantuml-plugin</code> à sa session 1, il y a des mois.</p> </div> <div class="paragraph"> <p>Voici la procédure exacte que j’ai suivie, et que je suivrai pour tout nouveau projet. Notez bien l’ordre — il est important.</p> </div> <div id="diag-bootstrap" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e11aa343b861c2c558099445242ab4be.svg" alt="Flux de bootstrap en 6 étapes pour initialiser la gouvernance agent sur un nouveau projet" width="1749" height="3371"> </div> </div> <div class="sect2"> <h3 id="_étape_0_créer_opencode_json">Étape 0 : Créer <code>opencode.json</code></h3> <div class="paragraph"> <p>C’est le premier fichier. Pas <code>AGENT.adoc</code>, pas <code>INDEX.adoc</code>. <code>opencode.json</code> d’abord, pour une raison simple : si vous créez <code>AGENT.adoc</code> en premier, vous allez oublier de créer le pont qui le charge automatiquement. Je l’ai fait sur <code>bakery-plugin</code>, je sais de quoi je parle.</p> </div> </div> <div class="sect2"> <h3 id="_étape_1_créer_les_dossiers">Étape 1 : Créer les Dossiers</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">mkdir -p .agents/sessions .agents/archives</code></pre> </div> </div> <div class="paragraph"> <p>Deux dossiers vides. <code>sessions/</code> recevra les archives de chaque session. <code>archives/</code> recevra les COMPLETED_TASKS_ARCHIVE mensuels. Ces dossiers doivent exister <strong>avant</strong> que l’agent n’ait besoin d’écrire dedans. Un agent qui doit créer le dossier ET le fichier en même temps, c’est un agent qui peut échouer silencieusement.</p> </div> </div> <div class="sect2"> <h3 id="_étape_2_créer_agent_adoc_le_fichier_maître">Étape 2 : Créer <code>AGENT.adoc</code> — Le Fichier Maître</h3> <div class="paragraph"> <p>Structure minimale pour la première version (elle grandira) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>= {NOM_PROJET} — Directives Agent [CAUTION]</code></pre> </div> </div> <div class="paragraph"> <p><strong>ARRÊT OBLIGATOIRE</strong> avant rm, Write, suppression :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>LIRE le fichier en entier</p> </li> <li> <p>VÉRIFIER git ls-files</p> </li> <li> <p>DEMANDER confirmation</p> </li> <li> <p>ATTENDRE "oui"</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_projet">Projet</h2> <div class="sectionbody"> <div class="paragraph"> <p><strong>Nom</strong> : …​ <strong>Stack</strong> : …​ <strong>Documentation</strong> : AsciiDoc</p> </div> </div> </div> <div class="sect1"> <h2 id="_règles_absolues">Règles Absolues</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_0_environnement_de_dev">0. ENVIRONNEMENT DE DEV</h3> <div class="paragraph"> <p>Commandes essentielles…​</p> </div> </div> <div class="sect2"> <h3 id="_1_commitsgit">1. COMMITS/GIT</h3> <div class="paragraph"> <p>Interdiction formelle…​</p> </div> </div> <div class="sect2"> <h3 id="_1b_fichiers_de_configuration_règle_absolue_de_sûreté">1b. FICHIERS DE CONFIGURATION — RÈGLE ABSOLUE DE SÛRETÉ</h3> <div class="paragraph"> <p>Ne jamais écraser…​</p> </div> </div> <div class="sect2"> <h3 id="_2_tests_en_fin_de_session">2. TESTS EN FIN DE SESSION</h3> <div class="paragraph"> <p>Interdiction formelle…​</p> </div> </div> <div class="sect2"> <h3 id="_3_procédure_de_fin_de_session">3. PROCÉDURE DE FIN DE SESSION</h3> <div class="paragraph"> <p>Les 6 étapes obligatoires…​</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_gestion_du_contexte_lazyeager">Gestion du Contexte — LAZY/EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>Fichiers EAGER / Fichiers LAZY…​</p> </div> <div class="paragraph"> <p>Ce template minimal permet à l’agent de démarrer. La version riche — avec la structure du projet, les composants clés, les EPICs, le backlog — viendra à la session 1, quand l’agent aura déjà les règles de base en main et pourra vous aider à enrichir le document.</p> </div> <div class="sect2"> <h3 id="_étape_3_créer_prompt_reprise_adoc_la_mission_session_1">Étape 3 : Créer <code>PROMPT_REPRISE.adoc</code> — La Mission Session 1</h3> <div class="paragraph"> <p>Un fichier qui dit explicitement : « Ceci est la session 1, mission à définir. » Maximum 70 lignes, avec une section Session 0 (résumé du bootstrap) et une section Session 1 (priorités à définir avec l’utilisateur).</p> </div> </div> <div class="sect2"> <h3 id="_étape_4_créer_agentsindex_adoc_le_point_dentrée">Étape 4 : Créer <code>.agents/INDEX.adoc</code> — Le Point d’Entrée</h3> <div class="paragraph"> <p>Le fichier qui contiendra les règles absolues (version exécutive) et le tableau des sessions. Pour le bootstrap, il liste les règles 0 à 3 dans leur format concis, le portefeuille de projets (en incluant le nouveau projet avec un emoji 🆕), et la roadmap vide prête à être remplie.</p> </div> </div> <div class="sect2"> <h3 id="_étape_5_créer_les_fichiers_lazy_structurants">Étape 5 : Créer les Fichiers LAZY Structurants</h3> <div class="paragraph"> <p>Dans l’ordre :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/SESSIONS_HISTORY.adoc</code> — un tableau avec uniquement la session 0</p> </li> <li> <p><code>.agents/SESSION_CHECKLIST.adoc</code> — le template « Quand changer de session »</p> </li> <li> <p><code>.agents/PROCEDURES.adoc</code> — la procédure complète des 6 étapes + EAGER/LAZY</p> </li> <li> <p><code>.agents/AGENT_SESSION_MANAGER.adoc</code> — le template d’archive</p> </li> <li> <p><code>.agents/TEST_COVERAGE_ANALYSIS.adoc</code> — le tableau de suivi des tests, vide au départ</p> </li> </ol> </div> <div class="paragraph"> <p>Si votre projet a un domaine métier complexe (comme <code>jhipster-gradle-plugins</code> avec son mono-repo persistence/assistant), créez les agents spécialisés dès maintenant :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/PLUGIN_DEVELOPER.adoc</code> — les conventions de code et le boundary de dépendances (si plugin)</p> </li> <li> <p><code>.agents/BACKLOG_MANAGER.adoc</code> — la structure de planification et les risques identifiés</p> </li> </ol> </div> <div class="paragraph"> <p>Ne créez pas d’agents que vous n’utiliserez pas. Un agent sans conventions concrètes à encoder est un fichier mort qui pollue <code>.agents/</code>.</p> </div> </div> <div class="sect2"> <h3 id="_étape_6_ajouter_le_projet_au_portefeuille_de_tous_les_projets">Étape 6 : Ajouter le Projet au Portefeuille de TOUS les Projets</h3> <div class="paragraph"> <p>C’est l’étape qu’on oublie systématiquement. Chaque <code>INDEX.adoc</code> de chaque projet contient un tableau « Portefeuille de Projets » qui liste TOUS les projets avec la même méthodologie. Quand vous créez un nouveau projet, vous devez :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ajouter une ligne dans le portefeuille du nouveau projet (logique)</p> </li> <li> <p>Ajouter une ligne dans le portefeuille de TOUS les projets existants — oui, tous</p> </li> </ol> </div> <div class="paragraph"> <p>Sur mes quatre (maintenant cinq) projets, cela veut dire ouvrir les <code>INDEX.adoc</code> de <code>magic-stick</code>, <code>bakery-gradle</code>, <code>cheroliv.com</code>, <code>plantuml-gradle</code> et y ajouter la ligne <code>jhipster-gradle-plugins | Session 1 | …​ | 2026-04-28 🆕</code>.</p> </div> <div class="paragraph"> <p>C’est fastidieux. C’est manuel. C’est aussi la seule façon de garantir que, quel que soit le projet sur lequel vous travaillez, l’agent sait quels autres projets existent et quel est leur état. À la session 012 de <code>magic-stick</code>, l’agent a détecté deux incohérences dans le portefeuille — <code>bakery-gradle</code> avait son COMPLETED_TASKS_ARCHIVE en retard, et <code>plantuml-gradle</code> avait un décalage entre sa documentation de procédure (5 étapes) et son INDEX (6 étapes). Sans ce tableau transverse, ces incohérences seraient restées invisibles.</p> </div> <div id="diag-portfolio-graph" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c2b21ca8d7481b154894427d05899032.svg" alt="Graphe du portefeuille de projets — références croisées entre INDEX.adoc" width="1501" height="802"> </div> </div> <div class="paragraph"> <p>Je vous entends d’ici : « Mais c’est de la duplication ! » Oui. C’est de la duplication volontaire. Chaque <code>INDEX.adoc</code> est autonome. Si vous ouvrez une session sur <code>magic-stick</code>, l’agent doit savoir que <code>plantuml-gradle</code> en est à la session 133 sans avoir à ouvrir un fichier dans un autre répertoire. C’est le prix de l’indépendance entre projets — et il est de 5 lignes par portefeuille.</p> </div> </div> <div class="sect2"> <h3 id="_ce_que_le_bootstrap_coûte">Ce que le Bootstrap Coûte</h3> <div class="paragraph"> <p>Tout ça prend 20 minutes. Vingt minutes une fois, pour ne plus jamais en perdre vingt au début de chaque session. Le ROI est immédiat : dès la session 2, l’agent reprend là où vous avez laissé la session 1.</p> </div> <div class="paragraph"> <p>Sur <code>jhipster-gradle-plugins</code>, ce bootstrap m’a pris exactement 18 minutes — de <code>mkdir .agents/</code> au dernier <code>INDEX.adoc</code> mis à jour dans le portefeuille de <code>magic-stick</code>. La session 1, qui suivra, démarrera avec un agent qui connaît déjà la structure du mono-repo, les commandes Gradle, et le boundary critique entre <code>persistence/</code> (lightweight) et <code>assistant/</code> (lourd). Vingt minutes bien investies.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_les_4_maintenant_5_projets_5_gouvernances_1_méthode">Les 4 (maintenant 5) Projets, 5 Gouvernances, 1 Méthode</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le système Eager/Lazy n’est pas un boilerplate copié-collé. Chaque projet a adapté la méthode à ses spécificités.</p> </div> <div class="sect2"> <h3 id="_cheroliv_com_le_site_personnel">cheroliv.com : Le Site Personnel</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Contenu éditorial, accessibilité WCAG 2.1 AA, JBake statique. <strong>Adaptation</strong> : Six épopées priorisées (P0-P4), agents spécialisés (CODER, SCRUM_MASTER, PLANTUML_DESIGNER), critères d’acceptation transverses sur l’accessibilité. <strong>Règle emblématique</strong> : <code>./gradlew serve</code> obligatoire, interdiction formelle du script <code>jbake.sh</code> externe.</p> </div> </div> <div class="sect2"> <h3 id="_bakery_gradle_le_plugin_multi_purpose">bakery-gradle : Le Plugin Multi-Purpose</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Plugin Gradle avec tâches de publication, génération de code Firebase, parsing YAML. <strong>Adaptation</strong> : Règle 0 (publishToMavenLocal), règle de sûreté sur les fichiers de config renforcée par l’incident du <code>site.yml</code>, EPIC 9 et 10 sur la configuration multi-fichiers. <strong>Règle emblématique</strong> : <code>publishToMavenLocal</code> après chaque modification du code source du plugin.</p> </div> </div> <div class="sect2"> <h3 id="_plantuml_gradle_le_plugin_ia">plantuml-gradle : Le Plugin IA</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Intégration LangChain4j, génération de diagrammes PlantUML via LLM, tests avec clés API cloud. <strong>Adaptation</strong> : Documentation LAZY dense (ARCHITECTURE, API_KEY_POOL_REFERENCE, DATASET_FINETUNING), EPICs numérotés (1-11 terminés, 107+ en cours), séparation EAGER/LAZY optimisée (gain de 60% de tokens). <strong>Règle emblématique</strong> : Fichiers <code>*_ESSENTIALS.adoc</code> (50 lignes) vs <code>*_REFERENCE.adoc</code> (illimité) pour le pool de clés API.</p> </div> </div> <div class="sect2"> <h3 id="_magic_stick_le_système_live">magic-stick : Le Système Live</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Build d’ISO Linux live (Xubuntu), partitionnement GPT A/B, CI/CD avec SourceForge. <strong>Adaptation</strong> : Références techniques LAZY complexes (AB_PARTITION, BOOT_TEST), SCRIPT_VERIFICATION.adoc comme étape 5 spécifique (pas de tests traditionnels, mais vérification de scripts bash). <strong>Règle emblématique</strong> : <code>isoTestAB</code> skipé en CI (runners non privilégiés), tests réservés aux environnements locaux avec Docker <code>--privileged</code>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_règles_absolues_transverses">Règles Absolues Transverses</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quelques règles critiques qui apparaissent dans le fichier <code>AGENT.adoc</code> Eager et s’appliquent à toutes les sessions sur tous les projets :</p> </div> <div class="paragraph"> <p><strong>Environnement de dev</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Utiliser la commande propre au projet (<code>./gradlew serve</code>, <code>./gradlew functionalTest</code>, etc.)</p> </li> <li> <p>❌ Interdit d’utiliser des scripts externes non versionnés</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Git</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Lecture seule autorisée (<code>git status</code>, <code>git diff</code>, <code>git log</code>)</p> </li> <li> <p>❌ <code>git add</code>, <code>git commit</code>, <code>git push</code> interdits sans permission explicite</p> </li> <li> <p>❌ <code>git commit --amend</code> interdit sauf conditions méticuleusement respectées</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fichiers de Configuration</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ Ne jamais écraser un fichier config avec un <code>Write</code> complet quand un <code>Edit</code> partiel suffit</p> </li> <li> <p>❌ Ne jamais remplacer des valeurs sensibles par des valeurs factices</p> </li> <li> <p>❌ Vérifier <code>git check-ignore</code> et <code>git ls-files</code> avant toute modification</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Tests</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ Ne jamais lancer de tests en procédure de fin de session sans permission explicite</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Outils Interdits</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ <code>TodoWrite</code> et <code>Task</code> — la gouvernance se fait via les fichiers AsciiDoc, pas via des outils externes</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_les_anti_patterns_ce_que_150_sessions_mont_appris">Les Anti-Patterns : Ce Que 150+ Sessions M’ont Appris</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avec le recul, certaines erreurs sont devenues des patterns tellement prévisibles que je peux les lister comme des anti-patterns — des pièges dans lesquels tout nouveau projet tombera probablement. Les voici, classés par ordre de fréquence.</p> </div> <div id="diag-antipatterns" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c4b4c7d8bfdda0f1287bc4f14752a381.svg" alt="Les 7 anti-patterns de la gouvernance agent — arbre des pièges à éviter" width="1783" height="5600"> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_1_lagent_sans_opencode_json">Anti-Pattern 1 : L’Agent sans <code>opencode.json</code></h3> <div class="paragraph"> <p>C’est l’erreur numéro un. Vous avez écrit un magnifique <code>AGENT.adoc</code> de 200 lignes, mais il n’est jamais chargé automatiquement. L’agent démarre nu. Vous passez 20 minutes à le recontextualiser — exactement ce que la méthode est censée éviter.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : L’agent pose des questions basiques sur la structure du projet alors que tout est dans <code>AGENT.adoc</code>. <strong>Correction</strong> : Créer <code>opencode.json</code> avec le bloc <code>instructions: ["AGENT.adoc"]</code>. Vérifier que le fichier existe dans le working directory d’Opencode.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_2_trop_dagents_trop_tôt">Anti-Pattern 2 : Trop d’Agents Trop Tôt</h3> <div class="paragraph"> <p>À la session 2 de votre projet, vous créez 5 agents spécialisés. Aucun n’a de contenu réel, ce sont tous des stubs. Résultat : <code>.agents/</code> est pollué de fichiers vides, et l’agent hésite sur lequel charger.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des fichiers d’agent contenant uniquement « À définir » ou une structure vide de 10 lignes. <strong>Correction</strong> : Un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes ou qu’il encode au moins 5 règles concrètes. En dessous, le contenu tient dans <code>AGENT.adoc</code>.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_3_le_prompt_reprise_fantôme">Anti-Pattern 3 : Le PROMPT_REPRISE Fantôme</h3> <div class="paragraph"> <p><code>PROMPT_REPRISE.adoc</code> est mis à jour…​ mais uniquement à la fin de la session, quand l’agent exécute la procédure. Entre-temps, la mission réelle de la session a dérivé — on a corrigé un bug imprévu au lieu d’implémenter la feature planifiée. Le <code>PROMPT_REPRISE.adoc</code> de fin de session ne reflète pas ce qui s’est <strong>vraiment</strong> passé.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : La section « Priorités » de <code>PROMPT_REPRISE.adoc</code> mentionne une feature qui n’a pas été touchée, alors que vous avez passé la session sur un bug critique. <strong>Correction</strong> : Mettre à jour <code>PROMPT_REPRISE.adoc</code> en temps réel quand la session dérive de sa mission initiale. Ne pas attendre la procédure de fin de session pour documenter le changement de cap. 30 secondes d’édition pendant la session valent mieux qu’un <code>PROMPT_REPRISE</code> mensonger.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_4_larchive_vide">Anti-Pattern 4 : L’Archive Vide</h3> <div class="paragraph"> <p>La procédure de fin de session crée l’archive…​ mais l’agent, pressé d’afficher sa checklist, remplit le template avec des placeholders. <code>{detail}</code> devient « Détail à compléter plus tard ». Ce « plus tard » n’arrive jamais.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des archives de session contenant les mots « TODO », « à compléter », ou des sections vides. <strong>Correction</strong> : La règle absolue dit qu’aucune étape ne peut être marquée [✅] si le fichier n’a pas été effectivement modifié. Appliquez-la à vous-même : relisez l’archive avant d’afficher la checklist. Si une section est vide, remplissez-la maintenant.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_5_le_portefeuille_fantôme">Anti-Pattern 5 : Le Portefeuille Fantôme</h3> <div class="paragraph"> <p>Vous créez un nouveau projet avec une gouvernance parfaite. Mais vous oubliez de l’ajouter au portefeuille des autres projets. Trois semaines plus tard, vous ouvrez une session sur <code>magic-stick</code> et l’agent vous dit que vous avez 4 projets. Vous en avez 5. L’agent ne le sait pas.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Le comptage des projets dans les portefeuilles ne correspond pas à la réalité. <strong>Correction</strong> : Scriptez la mise à jour du portefeuille, ou au minimum maintenez une checklist post-bootstrap qui inclut « Mettre à jour le portefeuille de tous les projets existants ». C’est l’étape la plus fastidieuse de la méthode, et donc la plus souvent omise.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_6_la_redondance_cachée">Anti-Pattern 6 : La Redondance Cachée</h3> <div class="paragraph"> <p>Vous copiez-collez le même backlog de 50 lignes dans <code>AGENT.adoc</code> et <code>INDEX.adoc</code>. À la session suivante, vous mettez à jour l’un mais pas l’autre. Vos deux fichiers EAGER se contredisent.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des divergences entre les EPICs listées dans <code>AGENT.adoc</code> et celles dans <code>INDEX.adoc</code>. <strong>Correction</strong> : La redondance doit être <strong>assumée et bornée</strong>. <code>AGENT.adoc</code> contient le backlog détaillé avec user stories. <code>INDEX.adoc</code> contient UNIQUEMENT le tableau récapitulatif des EPICs (nom, progression, priorité). Si les deux divergent, c’est <code>INDEX.adoc</code> qui fait foi — parce que c’est lui qui est mis à jour à chaque fin de session. Documentez cette règle dans votre <code>AGENT.adoc</code> : « En cas de divergence entre AGENT.adoc et INDEX.adoc, INDEX.adoc est la source de vérité. »</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_7_la_session_trop_longue">Anti-Pattern 7 : La Session Trop Longue</h3> <div class="paragraph"> <p>Vous ignorez les signaux du <code>SESSION_CHECKLIST.adoc</code>. 2 heures, 85 messages, 12 fichiers modifiés. L’agent tourne en boucle, vous aussi. Vous auriez dû changer de session il y a 45 minutes.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Le LLM répète des erreurs déjà corrigées, le contexte tokens dépasse 80k, vous avez modifié à la fois <code>persistence/</code> et <code>assistant/</code> dans la même session. <strong>Correction</strong> : Le <code>SESSION_CHECKLIST.adoc</code> existe pour une raison. Respectez-le. La règle d’or n’est pas une suggestion. 5 sessions de 20 minutes > 1 session de 2 heures.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_asciidoc">Pourquoi AsciiDoc ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai choisi AsciiDoc pour plusieurs raisons pragmatiques qui ont un impact direct sur l’efficacité de la gouvernance :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Structure sémantique riche</strong> : sections, tableaux, admonitions, attributs de document. Un agent lit mieux un document structuré qu’un fond de texte.</p> </li> <li> <p><strong>Attributs de document</strong> (<code>:jbake-type:</code>, <code>:jbake-status:</code>) qui permettent de définir des métadonnées lisibles par la machine et l’humain.</p> </li> <li> <p><strong>Compatibilité avec JBake</strong> : mon site statique est généré par JBake, qui traite nativement l’AsciiDoc. Les fichiers de gouvernance et les articles de blog partagent le même format. Mon article de blog <strong>sur</strong> la gouvernance est écrit dans le même format que la gouvernance elle-même.</p> </li> <li> <p><strong>Longévité</strong> : AsciiDoc est un format de documentation technique éprouvé, avec une spécification stable.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_résultat_une_continuité_sans_couture">Résultat : Une Continuité sans Couture</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depuis que j’ai mis ce système en place, passer d’une session Opencode à l’autre est devenu fluide. L’agent reprend exactement où je l’ai laissé, sans que j’aie à recontextualiser quoi que ce soit.</p> </div> <div class="paragraph"> <p>Les décisions prises à la session 3 sont accessibles à la session 133. Le backlog reste cohérent sur cinq projets simultanés. Les règles de sécurité (notamment sur git et les fichiers de config) sont respectées parce qu’elles sont omniprésentes dans le fichier Eager.</p> </div> <div class="paragraph"> <p>Les chiffres parlent :</p> </div> <div class="ulist"> <ul> <li> <p><strong>150+ sessions archivées</strong> au total</p> </li> <li> <p><strong>60% de tokens EAGER économisés</strong> après optimisation (Session 109)</p> </li> <li> <p><strong>Zéro rappel nécessaire</strong> sur le contexte métier du pool de clés API</p> </li> <li> <p><strong>100% des tests PASS</strong> sur plantuml-plugin (240/240)</p> </li> <li> <p><strong>Une seule catastrophe</strong> (Session 2 bakery-plugin) qui a donné naissance à la règle de sûreté absolue</p> </li> </ul> </div> <div class="paragraph"> <p>C’est un <strong>système artisanal</strong>, construit avec les outils du métier (AsciiDoc, git, Gradle), sans dépendance à une plateforme propriétaire. Il reflète ma conviction fondamentale : <strong>un développeur crédible construit et utilise ses propres outils</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_liens">Liens</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Mon site : [cheroliv.com](<a href="https://cheroliv.com" class="bare">https://cheroliv.com</a>)</p> </li> <li> <p>Le projet <code>bakery-gradle</code> : [github.com/cheroliv/bakery-gradle-plugin](<a href="https://github.com/cheroliv/bakery-gradle-plugin" class="bare">https://github.com/cheroliv/bakery-gradle-plugin</a>)</p> </li> <li> <p>Le projet <code>plantuml-gradle</code> : [github.com/cheroliv/plantuml-gradle-plugin](<a href="https://github.com/cheroliv/plantuml-gradle-plugin" class="bare">https://github.com/cheroliv/plantuml-gradle-plugin</a>)</p> </li> <li> <p>Le projet <code>magic-stick</code> : [github.com/cheroliv/magic-stick](<a href="https://github.com/cheroliv/magic-stick" class="bare">https://github.com/cheroliv/magic-stick</a>)</p> </li> <li> <p>Le projet <code>cheroliv.com</code> : [github.com/cheroliv/cheroliv.github.io](<a href="https://github.com/cheroliv/cheroliv.github.io" class="bare">https://github.com/cheroliv/cheroliv.github.io</a>)</p> </li> </ul> </div> <hr> <div class="paragraph"> <p><strong>Le code qu’on écrit pour soi est le laboratoire du code qu’on enseigne aux autres.</strong></p> </div> </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="#_a_cena_quatro_screenshots_dois_renders">A cena: quatro screenshots, dois renders</a> <ul class="sectlevel2"> <li><a href="#_renderização_local">Renderização local</a></li> <li><a href="#_renderizado_online">Renderizado online</a></li> </ul> </li> <li><a href="#_o_diagnóstico_serve_não_apontava_para_a_pasta_correta">O diagnóstico: <code>serve</code> não apontava para a pasta correta</a></li> <li><a href="#_a_causa_raiz_o_cli_do_jbake_não_funciona_assim">A causa raiz: O CLI do JBake não funciona assim</a></li> <li><a href="#_a_solução_argumentos_posicionais_não_flags">A solução: argumentos posicionais, não flags</a></li> <li><a href="#_verificação_rápida_com_curl">Verificação rápida com curl</a></li> <li><a href="#_por_que_esse_bug_era_sutil">Por que esse bug era sutil</a></li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 10 minutes</div> <p>Você conhece aquele momento em que o seu site local parece nada, mas uma vez colocado online tudo fica impecável? Isso aconteceu comigo com meu plugin Gradle JBake. A tarefa`serve`exibia botões quadrados, texto escuro sobre fundo preto, e um CSS estranhamente ausente. Porém`publishSite`gerava o mesmo site, ele, impecável. O culpado não era nem o CSS, nem o navegador, nem o cache. Era uma linha de código Kotlin — e um mau hábito com os argumentos na linha de comando.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_quatro_screenshots_dois_renders">A cena: quatro screenshots, dois renders</h2> <div class="sectionbody"> <div class="paragraph"> <p>Era depois de uma falha do sistema. Eu tinha tirado quatro capturas de tela para comparar o renderizado local (<code>./gradlew serve`sobre`localhost:8820</code>) com a renderização online (`publishSite`no GitHub Pages). Dois screenshots por página: topo e base.</p> </div> <div class="sect2"> <h3 id="_renderização_local">Renderização local</h3> <div class="paragraph"> <p><strong>Topo da página</strong>— Os botões <strong>Project</strong> e <strong>Template</strong> são<strong>pequenos, retangulares</strong>, nas cores padrão (azul e verde). O cartão <strong>Start Writing</strong> tem um<strong>fundo preto uniforme</strong>, sem moldura.</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>Rodapé</strong>— O subtítulo <strong>"Últimos artigos e recursos</strong>" é<strong>quase ilegível</strong>, muito escuro sobre fundo preto. As datas sob as imagens do blog ("17 October 2013", etc.) são<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_online">Renderizado online</h3> <div class="paragraph"> <p><strong>Topo da página</strong>— Os mesmos botões são<strong>grandes, ovinos, verde neon flashy</strong>, texto em maiúsculas. O cartão tem um<strong>quadro branco arredondado com sombra projetada</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>rodapé</strong>— O subtítulo é<strong>bem legível</strong>. As datas são<strong>visíveis</strong>. Os cartões dos artigos têm<strong>cantos arredondados</strong>e os títulos são<strong>em negrito</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>Primeiro reflexo: o tema. Utilizo um sistema de tema dinâmico (claro, escuro, alto contraste) baseado em`localStorage`. Talvez o local store desencadeava um tema high-contrast? Não. Já havia escritohttps://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[um artigo inteiro sobre o pré-carregamento dos temas], eu sei como isso funciona. E então, mesmo em modo high-contrast, a estrutura CSS (botões ovais, sombras) devia estar lá. Ela não estava lá.</p> </div> <div class="paragraph"> <p>Segundo reflexo: o cache do navegador. Não, eu tinha feito o teste com perfis limpos. O diff persistia.</p> </div> <div class="paragraph"> <p>Terceiro reflexo:`serve`não servia os mesmos arquivos que`publishSite`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_o_diagnóstico_serve_não_apontava_para_a_pasta_correta">O diagnóstico: <code>serve</code> não apontava para a pasta correta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Meu plugin Gradle`bakery`tem duas tarefas principais:</p> </div> <div class="ulist"> <ul> <li> <p><code>bake</code>: gera o site estático em`build/bake/`</p> </li> <li> <p><code>serve</code>: inicia um servidor web local</p> </li> <li> <p><code>publishSite</code>: empurra`build/bake/`para GitHub Pages</p> </li> </ul> </div> <div class="paragraph"> <p>A divergência só poderia vir de`serve`. Si <code>publishSite`publicava o conteúdo correto, é que`build/bake/`estava bom. Se`serve`exibia outra coisa, o que significa que não servia`build/bake/</code>.</p> </div> <div class="paragraph"> <p>Vamos olhar o código. Em`SiteManager.kt`, a tarefa`serve`é definida assim :</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`é o ponto de entrada da CLI JBake 2.7.0. A ideia: passar</code>-b`para a pasta de origem e`-s`para a pasta de destino, então iniciar o modo servidor. Mas…​</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_causa_raiz_o_cli_do_jbake_não_funciona_assim">A causa raiz: O CLI do JBake não funciona assim</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0 aguarda alguns<strong>argumentos posicionais</strong>para a fonte e o destino, seguido de flags opcionais. A assinatura é :</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>Mas no meu código, eu escrevia :</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 interpretava isso :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ analisar o sinalizador \"bake\" (booleano), consumido</p> </li> <li> <p><code>/path/to/site</code>→ torna-se argumento posicional 1 (fonte)</p> </li> <li> <p><code>-s</code>→ analisar o opção "serve" (booleano), servidor iniciado<strong>imediatamente</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ torna-se um argumento órfão, ignorado ou mal interpretado</p> </li> </ol> </div> <div class="paragraph"> <p>Resultado: JBake estava tomando`/path/to/site`como fonte,<strong>não levava em conta o destino</strong>fornecida (<code>build/bake</code>), e utilizava seu diretório padrão (frequentemente`./output`ou uma cópia temporária). O arquivo`css/styles.css`o build era portanto sobrescrito ou ignorado, e é um velho CSS padrão (sem as variáveis personalizadas, sem os arredondamentos, sem as sombras) que estava sendo servido.</p> </div> <div class="paragraph"> <p>Em comparação,<code>bake</code> et <code>publishSite`utilizam o<strong>plugin Gradle JBake oficial</strong>(`jbake-gradle-plugin</code>) que escreve bem em`build/bake/`via a API Gradle. Eles não passam pela CLI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_argumentos_posicionais_não_flags">A solução: argumentos posicionais, não flags</h2> <div class="sectionbody"> <div class="paragraph"> <p>A correção é trivial — uma vez que se sabe. Basta passar a fonte e o destino como argumentos posicionais, depois`-s`por último:</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>É isso. Três linhas alteradas, bug resolvido.</p> </div> <div class="paragraph"> <p>Após publicação local do plugin (<code>publishToMavenLocal</code>), un `./gradlew serve`lança JBake com a sintaxe correta :</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>E desta vez, o servidor Jetty integrado ao JBake serve bem o conteúdo de`build/bake/`— idêntico ao que é publicado online.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/serve-vs-publish-diagram.svg" alt="serve vs publish diagram" width="1763" height="5484"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificação_rápida_com_curl">Verificação rápida com curl</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para garantir que o servidor esteja servindo o conteúdo correto, um simples`curl`confirma que`index.html`contém`data-bs-theme="light"`e que`build/bake/css/styles.css`pesa bem 31 402 bytes — idêntico ao arquivo gerado 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>O render local agora<strong>pixel-idêntico</strong>ao renderizado implantado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_esse_bug_era_sutil">Por que esse bug era sutil</h2> <div class="sectionbody"> <div class="paragraph"> <p>Você vê por que era difícil de pegar?</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Nenhum erro explícito</strong>JBake não travava. Ele "funcionava", simplesmente com uma pasta errada.</p> </li> <li> <p><strong>O build funcionava</strong>:`./gradlew bake`gerava corretamente os arquivos em`build/bake/`.</p> </li> <li> <p><strong>O despliegue estava funcionando</strong>:`publishSite`empurrava o bom conteúdo online</p> </li> <li> <p><strong>Só <code>serve</code> estava quebrado</strong>: a tarefa de desenvolvimento, aquela que usamos constantemente para iterar.</p> </li> <li> <p><strong>O hábito de <code>-key value</strong>: como desenvolvedor, somos condicionados por anos de CLI Unix (</code>-o output`, <code>-i input</code>). O CLI do JBake é uma exceção — a fonte e o destino são posicionais.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se você mantém um plugin Gradle que envolve JBake (ou qualquer ferramenta CLI),<strong>leia a documentação dos argumentos</strong>mesmo se você pensa que os conhece. Uma hipótese implícita (<code>-s</code> = "set destination") pode custar horas de depuração visual.</p> </div> <div class="paragraph"> <p>Aqui, o fix era literalmente para mudar:</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>Três tokens deslocados, e meu site local volta a ficar tão bonito quanto o site em produção.</p> </div> <div class="paragraph"> <p><strong>Lição</strong>: quando a renderização difere entre local e produção sem razão óbvia, suspeite primeiro do <strong>pipeline</strong> — não o CSS, não o navegador, e muito menos o framework. Frequentemente é a etapa logo antes da renderização que está trapaceando.</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="#_a_cena_um_agente_cego_num_mundo_de_ferramentas">A cena: um agente cego num mundo de ferramentas</a></li> <li><a href="#_anatomia_do_bug_dois_shells_dois_mundos">Anatomia do bug: dois shells, dois mundos</a></li> <li><a href="#_os_culpados_zshrc_vs_zshenv">Os culpados: .zshrc vs .zshenv</a></li> <li><a href="#_diagnóstico_passo_a_passo">Diagnóstico passo a passo</a> <ul class="sectlevel2"> <li><a href="#_verificar_o_path_do_agente">Verificar o PATH do agente</a></li> <li><a href="#_2_identifique_o_que_está_em_zshrc_mas_não_está_em_zshenv">2. Identifique o que está em <code>.zshrc</code> mas não está em `.zshenv</a></li> <li><a href="#_3_verificar_se_o_zshenv_existe">3. Verificar se o .zshenv existe</a></li> </ul> </li> <li><a href="#_a_solução_zshenv_os_caminhos_corretos">A solução: .zshenv + os caminhos corretos</a> <ul class="sectlevel2"> <li><a href="#_criar_zshenv_com_todos_os_caminhos_essenciais">Criar .zshenv com todos os caminhos essenciais</a></li> <li><a href="#_por_que_não_source_sdkman_init_sh_no_zshenv">Por que não <code>source sdkman-init.sh</code> no .zshenv?</a></li> </ul> </li> <li><a href="#_o_caso_nvm_quando_o_gerenciador_de_versões_esquece_de_deixar_uma_marca">O caso NVM: quando o gerenciador de versões esquece de deixar uma marca</a> <ul class="sectlevel2"> <li><a href="#_o_problema_nvm">O problema NVM</a></li> <li><a href="#_a_solução_criar_o_symlink_current_para_nvm">A solução: criar o symlink <code>current</code> para NVM</a></li> <li><a href="#_automatizar_a_atualização_do_symlink">Automatizar a atualização do symlink</a></li> </ul> </li> <li><a href="#_tabela_resumo_dos_caminhos">Tabela resumo dos caminhos</a></li> <li><a href="#_armadilhas_e_mitigações">Armadilhas e mitigações</a></li> <li><a href="#_lições_aprendidas">Lições aprendidas</a></li> <li><a href="#_verificação_final">Verificação final</a></li> <li><a href="#_links">Links</a> <ul class="sectlevel2"> <li><a href="#_documentação_oficial">Documentação oficial</a></li> <li><a href="#_ferramentas_mencionadas">Ferramentas mencionadas</a></li> <li><a href="#_para_ir_além">Para ir além</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 13 minutes</div> <p>Você inicia o OpenCode no seu terminal, tudo funciona. O agente tenta um`gh`— não encontrado. Um`java -version`— ausente. Um`node`— em nenhum lugar. Porém, essas ferramentas estão realmente aqui no <em>votre</em> shell. O problema? OpenCode lança shells.<strong>não interativos</strong>que nunca leem seu`.zshrc`. Como diagnosticar e corrigir isso corretamente.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_a_cena_um_agente_cego_num_mundo_de_ferramentas">A cena: um agente cego num mundo de ferramentas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Era uma terça-feira à noite. Eu acabara de instalarhttps://opencode.ai[OpenCode], o agente IA que prometia transformar a minha forma de codar. Primeiro teste: pedir a ele para listar os meus repositórios do 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>Estranho.`gh`funcionava perfeitamente no meu terminal. Estou tentando outra coisa:</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>Então:</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>— tudo era invisível para o agente. Meu terminal, porém, via tudo. Como se o agente e eu vivêssemos em dois mundos paralelos.</p> </div> <div class="paragraph"> <p>Levei horas para entender. Horas de`echo $PATH`, de <code>which java</code>, de crescente frustração. Finalmente percebi que o problema não eram as ferramentas — era o<strong>shell</strong>. OpenCode, assim como todo agente que inicia subprocessos, trabalha em shells<strong>não interativos</strong>. E o Zsh, nesses shells, ignora simplesmente seu`.zshrc`.</p> </div> <div class="paragraph"> <p>O que se segue é o relato completo deste diagnóstico, da resolução e da lição que tirei. Se você utiliza um agente de IA — OpenCode, Aider, Cursor ou mesmo scripts cron — esse problema o afetará um dia.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomia_do_bug_dois_shells_dois_mundos">Anatomia do bug: dois shells, dois mundos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando você abre um terminal, o Zsh o trata como um shell<strong>interativo</strong>. Ele carrega`.zshrc`, que inicializa tudo: SDKMAN, NVM, pnpm, os aliases, o seu prompt bonito. O seu ambiente está completo.</p> </div> <div class="paragraph"> <p>Mas quando o OpenCode executa um comando, ele não inicia um terminal interativo. Ele inicia um shell<strong>não interativo</strong>— um shell de tarefa, sem humano atrás da tela. E Zsh, neste contexto, salta`.zshrc`. Ele lê apenas`.zshenv`.</p> </div> <div class="paragraph"> <p>Por que essa distinção existe? Porque um shell não-interativo foi projetado para executar scripts, não para atender a um usuário humano. Carregar os aliases, o prompt e as completions em um script que roda em segundo plano seria um desperdício. O problema é que o seu PATH — a informação mais crítica para localizar os executáveis — costuma ser inicializado em`.zshrc`, não em`.zshenv`.</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 "Você" as user actor "OpenCode ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor "Você" as user actor "OpenCode (agente)" as agent participant "Shell interativo (.zshrc carregado)" as ishell participant "Shell não interativo (.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>A raiz do problema:<strong>Zsh apenas carrega <code>.zshrc</code> para shells interativos</strong>. OpenCode, como todo agente de IA que inicia subprocessos, utiliza shells não-interativos. Esses shells leem apenas`.zshenv`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_os_culpados_zshrc_vs_zshenv">Os culpados: .zshrc vs .zshenv</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh dispõe de<strong>quatro arquivos de inicialização</strong>, cada um com um papel preciso. É um design elegante — mas isso também é o nó do 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">arquivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Obtido quando</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">Altera o 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>sempre</strong>(interativo + não interativo + login)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variáveis de ambiente essenciais, PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Sim — é o lugar dele/ela</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">Apenas shells de login</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comandos lentos (uma vez por sessão)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Possível</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>Shells interativos apenas</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias, prompt, completão, ferramentas interativas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Não para as variáveis 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 login (depois .zshrc)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mensagens de boas-vindas, finalização</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">raramente</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>A tabela dá uma indicação, mas é preciso compreendê-la em profundidade. Pense nisso como os cómodos de uma casa:</p> </div> <div class="ulist"> <ul> <li> <p>`.zshenv`é o<strong>hall de entrada</strong>— todos passam por lá, visitante ou residente. Se você colocar algo aqui, qualquer shell poderá vê-lo.</p> </li> <li> <p>`.zshrc`é o<strong>sala</strong>— apenas os residentes (shells interativos) entram ali. Os visitantes (shells não interativos) permanecem no hall.</p> </li> <li> <p><code>.zprofile</code> et `.zlogin`são peças especializadas para shells de login (como quando você se conecta via SSH).</p> </li> </ul> </div> <div class="paragraph"> <p>O drama é que a maioria de nós colocamos o PATH na sala. E o agente de IA, ele, nunca tem o direito de entrar lá.</p> </div> <div class="paragraph"> <p>O problema em um 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>Quando você abre um terminal, o Zsh é interativo: ele lê`.zshrc`, tudo funciona. Quando o OpenCode lança um shell para executar um comando, o Zsh é não-interativo: ele pula`.zshrc`, só lê`.zshenv`. Et si `.zshenv`não existe ou não contém o PATH — é o deserto.</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 que o Zsh faz isso?</strong>É uma escolha de design herdada do Unix. Um shell não interativo deve ser<strong>rápido</strong> et <strong>reprodutível</strong>. Carregar os aliases, os prompts coloridos e as inicializações pesadas do SDKMAN em um script de cron ou um agente de IA seria lento e frágil. A separação, portanto, é lógica :`.zshenv`para o essencial (variáveis, PATH)`.zshrc`para o conforto (aliases, prompt, completamos). O problema ocorre quando colocamos o essencial no conforto.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_diagnóstico_passo_a_passo">Diagnóstico passo a passo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de corrigir, é preciso entender exatamente o que falta. Este é um método de diagnóstico reprodutível — guarde-a nos favoritos se você trabalha com agentes de IA.</p> </div> <div class="sect2"> <h3 id="_verificar_o_path_do_agente">Verificar o PATH do agente</h3> <div class="paragraph"> <p>Comparamos o que o seu terminal interativo vê com o que um shell não interativo vê — ou seja, o que o OpenCode vê.</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>Agora, vamos simular o que o agente vê — um shell não-interativo :</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 caminhos de seis desapareceram.</strong>O agente está amputado de 83% do seu ambiente. É como se você fosse solicitado a cozinhar sem metade dos seus utensílios — você poderia ferver água, mas pouco mais.</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>Encomenda`zsh -c 'echo $PATH'`é seu<strong>ferramenta de diagnóstico número 1</strong>. Se uma ferramenta que você utiliza diariamente estiver ausente do resultado, seu agente de IA também não poderá vê-la. Teste-a antes e depois de cada modificação de`.zshenv`.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_identifique_o_que_está_em_zshrc_mas_não_está_em_zshenv">2. Identifique o que está em <code>.zshrc</code> mas não está em `.zshenv</h3> <div class="paragraph"> <p>Agora, estamos procurando o culpado em`.zshrc`. Filtrar as linhas que mencionam nossas ferramentas :</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>Costuma-se encontrar :</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>Tudo isso é<strong>invisível</strong>para OpenCode. E o`PATH`da linha 119 nem mesmo é`export`é — ele nunca sai do shell atual. É um detalhe técnico crucial: uma variável sem`export`Permanece local ao shell que a define. Os sub-shells — como aqueles lançados pelo OpenCode — nunca a herdam.</p> </div> </div> <div class="sect2"> <h3 id="_3_verificar_se_o_zshenv_existe">3. Verificar se o .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>Se a resposta é « ARQUIVO AUSENTE », é aí que tudo se decide.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_zshenv_os_caminhos_corretos">A solução: .zshenv + os caminhos corretos</h2> <div class="sectionbody"> <div class="paragraph"> <p>A estratégia é simples, mas exige precisão: colocar dentro`.zshenv` <strong>apenas</strong>caminhos essenciais, sem executar os scripts de inicialização pesados. não movemos`.zshrc`em`.zshenv`— extraímos o essencial.</p> </div> <div class="sect2"> <h3 id="_criar_zshenv_com_todos_os_caminhos_essenciais">Criar .zshenv com todos os caminhos essenciais</h3> <div class="paragraph"> <p>`.zshenv`é o<strong>arquivo único</strong>que Zsh garante de sourcear em<strong>todos</strong>os contextos. É aqui que o PATH deve ir.</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>Utiliza-se`$HOME/.nvm/current/bin`e não`$HOME/.nvm/versions/node/v22.19.0/bin`. A razão : as versões do Node mudam. Um caminho fixo se torna falso no próximo`nvm install`. Mais detalhes na seção seguinte.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_por_que_não_source_sdkman_init_sh_no_zshenv">Por que não <code>source sdkman-init.sh</code> no .zshenv?</h3> <div class="paragraph"> <p>A abordagem mais tentadora seria simplesmente reproduzir em`.zshenv`o que fazemos em`.zshrc`— carregar os scripts de inicialização. Nós<strong>poderia</strong>estar tentado de fazer:</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>Lento</strong> : `sdkman-init.sh`faz resoluções de rede e verificações a cada shell. Em um shell não interativo, é um custo desnecessário.</p> </li> <li> <p><strong>frágil</strong>: SDKMAN espera um contexto interativo. Sua inicialização pode falhar silenciosamente em um pipe ou em um subshell.</p> </li> <li> <p><strong>inútil</strong>: SDKMAN coloca seus candidatos em`~/.sdkman/candidates/<tool>/current/bin`— links simbólicos estáveis apontando para a versão ativa. Pode‑se utilizá‑los<strong>diretamente</strong>.</p> </li> </ul> </div> <div class="paragraph"> <p>A abordagem correta: contornar a inicialização do SDKMAN e apontar diretamente para os symlinks`current`. É a chave de toda a solução :<strong>usar a estrutura de arquivos como contrato, em vez do código de inicialização</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 rectangle "Abordagem Lenta\n(source sdkman-init.sh)" as slow { card ".zshenv source sdkman-init.sh 2-3 segundos por shell ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "Abordagem Lenta\n(source sdkman-init.sh)" as slow { card ".zshenv source sdkman-init.sh 2-3 segundos por shell Verificações de rede Risco de falha" as s1 #FDEDEC } rectangle "Abordagem rápida (symlinks diretos)" as fast { card ".zshenv export PATH=...current/bin 0 ms Sem rede Sem inicialização" 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="_o_caso_nvm_quando_o_gerenciador_de_versões_esquece_de_deixar_uma_marca">O caso NVM: quando o gerenciador de versões esquece de deixar uma marca</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_problema_nvm">O problema NVM</h3> <div class="paragraph"> <p>É aqui que a investigação me levou mais longe. SDKMAN tem um design elegante: quando se faz`sdk install java 25.0.2-tem`, ele cria um symlink :</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 link simbólico é<strong>sempre atualizado</strong>Apontem-no em`.zshenv`e você está coberto, não importa qual seja o shell. Bonito.</p> </div> <div class="paragraph"> <p>NVM, ele, não cria<strong>nada</strong>de tal. Sem symlink`current`. Não há ponto de ancoragem estável. É necessário apontar para um caminho versionado embutido, que se parece com isso :</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>No próximo`nvm install 24`, este caminho está morto. Seu`.zshenv`apontará para uma versão que não é mais a versão ativa. É uma bomba-relógio.</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 que o NVM faz isso?</strong>NVM funciona modificando dinamicamente o PATH a cada`nvm use`. Foi projetado para desenvolvedores que mudam de versão frequentemente, em um shell interativo. O symlink`current`Não estava nas especificações iniciais — é um esquecimento de design que vamos corrigir nós mesmos.</p> </div> </td> </tr> </table> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-vs-sdkman.svg" alt="nvm vs sdkman" width="1746" height="5676"> </div> </div> </div> <div class="sect2"> <h3 id="_a_solução_criar_o_symlink_current_para_nvm">A solução: criar o symlink <code>current</code> para NVM</h3> <div class="paragraph"> <p>Como o NVM não faz isso, nós o fazemos nós mesmos. O princípio é o mesmo que o SDKMAN — um symlink`current`que sempre aponta para a versão ativa. Cria-se uma vez, então automatiza-se para que se atualize sozinho.</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>Agora, em`.zshenv`, 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>Em vez 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_a_atualização_do_symlink">Automatizar a atualização do symlink</h3> <div class="paragraph"> <p>Um symlink não vale nada se não se atualiza. O symlink`current`deve ser atualizado quando fazemos`nvm use` ou <code>nvm install</code>. A solução : um<strong>embrulho</strong>— uma função que envolve o comando verdadeiro`nvm`e atualiza o symlink após cada chamada</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>Como funciona, em detalhe:</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 envolvedor ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur participant "nvm envolvedor (_nvm)" as wrapper participant "nvm real\n(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>O wrapper`_nvm`chama o comando verdadeiro`nvm`, então atualiza o symlink. O alias`nvm='_nvm'`certifique-se de que ao digitar`nvm`, passamos pelo wrapper. E na inicialização do shell, fazemos o mesmo depois`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`é uma função interna do NVM que resolve o caminho completo de uma versão. Isso evita de reconstruir o caminho manualmente.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tabela_resumo_dos_caminhos">Tabela resumo dos caminhos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de passar para as armadilhas, um resumo visual da transformação. À esquerda, o que você tinha (tudo em`.zshrc`, invisível para o agente). à direita, o que você tem agora (os caminhos essenciais em`.zshenv`, visíveis em todo lugar).</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">ferramenta</th> <th class="tableblock halign-left valign-top">Antes (.zshrc apenas)</th> <th class="tableblock halign-left valign-top">Depois (.zshenv + symlink)</th> <th class="tableblock halign-left valign-top">Visível pelo 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 não exportado no .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/apps`em .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`carregado no .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/java/current/bin`no .zshenv</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> </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`carregado no .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/gradle/current/bin`em .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">NVM Node</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`nvm use --lts`no .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.nvm/current/bin`em .zshenv (link simbólico)</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`no .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$PNPM_HOME`no .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">JetBrains Toolbox</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto-adicionado pelo Toolbox em .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.local/share/JetBrains/Toolbox/scripts`no .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`no PATH .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Explícitamente em .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="_armadilhas_e_mitigações">Armadilhas e mitigações</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nem tudo é perfeito com essa abordagem. Aqui estão os problemas que encontrei, e como contorná-los.</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">armadilha</th> <th class="tableblock halign-left valign-top">descrição</th> <th class="tableblock halign-left valign-top">mitigação</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Caminho duplicado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Se .zshenv e .zshrc adicionam o mesmo caminho, aparece duas vezes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`.zshenv`é fonte<strong>antes</strong>.zshrc. Os dois são lidos em um shell interativo. O PATH pode duplicar. É estético, não funcional. Para evitá‑lo: coloque apenas no .zshenv os caminhos <em>ausentes</em> do PATH padrão.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM : versão fixa no .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">colocar`~/.nvm/versions/node/v22.19.0/bin`hard-coded torna-se falso no próximo`nvm install`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Usar o symlink`$HOME/.nvm/current/bin`+ o wrapper`_nvm`no .zshrc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN: source sdkman-init.sh no .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lento, frágil, inútil em um shell não interativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Usar os symlinks`candidates/<tool>/current/bin`diretamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias ausente após modificação</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O wrapper`nvm='_nvm'`no .zshrc só tem efeito após recarregar</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reiniciar o shell ou`source ~/.zshrc`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode não vê as mudanças</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O agente já lançou seus subshells com o .zshenv antigo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reinicie o OpenCode após a modificação de .zshenv</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv demasiado carregado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Colocar funções pesadas ou inicializações interativas no .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv = variáveis de ambiente + PATH apenas. Não`source`, sem funções pesadas, sem prompts.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lições_aprendidas">Lições aprendidas</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>.zshrc` é interativo, <code>.zshenv</code> é universal</strong>— Se uma variável deve existir em <em>todos</em> os shells (agentes IA, cron, scripts, IDE), ela vai para`.zshenv`. A sala é confortável, mas o hall de entrada é o único lugar onde todos passam.</p> </li> <li> <p><strong>Os gerentes de versões não são iguais</strong>— SDKMAN cria symlinks`current`por design. NVM não. É preciso preencher essa lacuna manualmente. É uma lição importante: antes de configurar seu PATH, verifique se o gerenciador oferece um ponto de ancoragem estável.</p> </li> <li> <p><strong>Não source os init scripts em .zshenv</strong>—<code>sdkman-init.sh</code> et `nvm.sh`são projetados para um shell interativo. Eles são lentos e frágeis em um contexto não-interativo. Os symlinks`current`são suficientes e são instantâneos</p> </li> <li> <p><strong>Sempre testar em shell não-interativo</strong>—`zsh -c 'echo $PATH'`simula exatamente o que um agente vê. Este é o teste de validação. Sem este teste, você não sabe se sua configuração funciona para os agentes.</p> </li> <li> <p><strong>O padrão wrapper é reutilizável</strong>— O mesmo padrão`_nvm`+`alias nvm='_nvm'`Aplica-se a qualquer ferramenta que modifique o PATH dinamicamente sem deixar um rastro estável. É uma ferramenta a mais na sua caixa de ideias.</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 interativo : ✅ Shell não interativo : ❌ ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Shell interativo : ✅ Shell não interativo : ❌ OpenCode : ❌ Cron : ❌ Scripts : ❌" as av1 #FDEDEC } rectangle "DEPOIS" as apres { card "Shell interativo : ✅\nShell não interativo : ✅\nOpenCode : ✅\nCron : ✅\nScripts : ✅" as ap1 #E8F8E8 } avant --> apres : .zshenv +\nsymlink ~/.nvm/current @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verificação_final">Verificação final</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depois de ter criado`.zshenv`e o symlink NVM, verifique que tudo funciona — nos dois 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 devem ter sucesso. Se sim, seu agente de IA verá as mesmas ferramentas que você. Se não, volte ao diagnóstico passo a passo — você provavelmente esqueceu um caminho ou o symlink NVM não está atualizado.</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>Automatize este teste.</strong>Adicione esta verificação em um script de healthcheck que você executa após cada atualização das suas ferramentas. Un`zsh -c 'which java && which node && which gh'`Em CI, é uma garantia contra as surpresas.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p></think> (No text provided to translate; output remains empty.) Um shell não-interativo é como um convidado silencioso: ele lê apenas o que está exibido na porta de entrada. Se o PATH estiver na sala de estar, ele nunca o verá. <em>__</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_documentação_oficial">Documentação oficial</h3> <div class="ulist"> <ul> <li> <p><a href="https://zsh.sourceforge.io/Doc/Release/Files.html">Documentação do Zsh: Arquivos de inicialização</a>— A referência oficial sobre os arquivos de inicialização do Zsh. É lá que tudo é explicado, mesmo que se esqueça frequentemente.</p> </li> <li> <p><a href="https://opencode.ai/docs/config/">OpenCode : configuração</a>— Como configurar OpenCode e seu ambiente de execução</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_ferramentas_mencionadas">Ferramentas mencionadas</h3> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nvm-sh/nvm">NVM no GitHub</a>— Node Version Manager. Gerenciador de versões Node.js.</p> </li> <li> <p><a href="https://sdkman.io">SDKMAN — site oficial</a>— SDKMAN! O gerenciador de versões para a JVM (Java, Kotlin, Gradle…​)</p> </li> <li> <p><a href="https://sdkman.io/install">SDKMAN : instalação</a>— Guia de instalação do SDKMAN.</p> </li> <li> <p><a href="https://cli.github.com">gh` — GitHub CLI</a>— A ferramenta de linha de comando GitHub, essencial para todo desenvolvedor.</p> </li> <li> <p><a href="https://gradle.org">Gradle — site oficial</a>— O sistema de build que instalamos via SDKMAN.</p> </li> <li> <p><a href="https://pnpm.io">pnpm — site oficial</a>— O gerenciador de pacotes Node.js rápido e econômico em espaço.</p> </li> <li> <p><a href="https://www.jetbrains.com/toolbox-app/">JetBrains Toolbox</a>— O gerenciador de IDE JetBrains, que adiciona seus scripts ao PATH.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_para_ir_além">Para ir além</h3> <div class="ulist"> <ul> <li> <p><a href="https://blog.andy2003.org/posts/2022/zsh-dotfiles/">Dotfiles do Zsh : um guia completo</a>— Artigo aprofundado sobre a gestão de dotfiles Zsh.</p> </li> <li> <p><a href="https://wiki.archlinux.org/title/Zsh">Zsh no ArchWiki</a>— Uma das melhores documentações comunitárias sobre Zsh.</p> </li> <li> <p><a href="https://github.com/nvm-sh/nvm/issues">NVM problemas GitHub</a>— Para ver as discussões ao redor do symlink`current`e 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="#_o_problema_diagramas_sempre_atrasados_em_relação_ao_código">O problema: diagramas sempre atrasados em relação ao código</a></li> <li><a href="#_a_solução_um_pipeline_determinístico_knowledge_graph_plantuml">A solução: um pipeline determinístico Knowledge Graph → PlantUML</a></li> <li><a href="#_passo_1_instalar_graphify_e_extrair_o_knowledge_graph">Passo 1: Instalar Graphify e extrair o Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_instalação">Instalação</a></li> <li><a href="#_configurar_as_exclusões">Configurar as exclusões</a></li> <li><a href="#_extrair_o_knowledge_graph">Extrair o Knowledge Graph</a></li> </ul> </li> <li><a href="#_passo_2_o_plugin_gradle_transforma_o_knowledge_graph_em_plantuml">Passo 2 : O plugin Gradle transforma o Knowledge Graph em PlantUML</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_do_pipeline">Arquitetura do pipeline</a></li> <li><a href="#_os_componentes_internos">Os componentes internos</a></li> <li><a href="#_regras_de_renderização">Regras de renderização</a></li> </ul> </li> <li><a href="#_passo_3_uso_diário">Passo 3 : Uso diário</a> <ul class="sectlevel2"> <li><a href="#_diagrama_completo">Diagrama completo</a></li> <li><a href="#_filtrar_por_comunidade">Filtrar por comunidade</a></li> <li><a href="#_filtrar_por_tipo_de_aresta">Filtrar por tipo de aresta</a></li> <li><a href="#_filtrar_por_tipo_de_nó_e_confiança">Filtrar por tipo de nó e confiança</a></li> <li><a href="#_diretório_de_saída_personalizado">Diretório de saída personalizado</a></li> <li><a href="#_referência_completa_das_propriedades">Referência completa das propriedades</a></li> </ul> </li> <li><a href="#_o_pipeline_completo_em_um_workflow_gradle">O pipeline completo em um workflow Gradle</a> <ul class="sectlevel2"> <li><a href="#_tipo_de_workflow">Tipo de workflow</a></li> <li><a href="#_integração_no_ciclo_de_desenvolvimento">Integração no ciclo de desenvolvimento</a></li> <li><a href="#_atualização_incremental">Atualização incremental</a></li> </ul> </li> <li><a href="#_dogfooding_o_plugin_se_documenta_por_si_mesmo">Dogfooding: o plugin se documenta por si mesmo</a></li> <li><a href="#_por_que_é_determinístico_e_por_que_isso_importa">Por que é determinístico (e por que isso importa)</a></li> <li><a href="#_diagramas_do_próprio_pipeline">Diagramas do próprio pipeline</a></li> <li><a href="#_integração_na_governança_do_projeto">Integração na governança do projeto</a></li> <li><a href="#_preparação_lista_de_verificação_em_5_minutos">Preparação: lista de verificação em 5 minutos</a></li> <li><a href="#_armadilhas_e_mitigações">Armadilhas e mitigações</a></li> <li><a href="#_o_que_se_obtém_no_final">O que se obtém no final</a></li> <li><a href="#_links">Links</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 12 minutes</div> <p>Sua base de código cresce. As dependências entre módulos se multiplicam. A documentação da arquitetura torna-se obsoleta antes mesmo de ser escrita. E se seu build Gradle pudesse <em>automaticamente</em> gerar diagramas atualizados a partir da estrutura real do código ? É exatamente isso que o pipeline Graphify + PlantUML Gradle Plugin :`graphify . --no-viz`extrai o Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`o transforma em diagramas PlantUML. Zero LLM, zero 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="_o_problema_diagramas_sempre_atrasados_em_relação_ao_código">O problema: diagramas sempre atrasados em relação ao código</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo projeto que ultrapassa alguns milhares de linhas conhece esse sintoma:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Desenha-se um diagrama de arquitetura no início do projeto.</p> </li> <li> <p>O código evolui, as dependências mudam</p> </li> <li> <p>O diagrama se torna uma mentira decorativa</p> </li> <li> <p>Ninguém o atualiza porque é chato</p> </li> <li> <p>Os novos chegados baseiam-se nisso e cometem erros</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>A questão não é <em>é necessário ter diagramas?</em> — todo mundo sabe que sim. A questão é:<strong>Quem os mantém atualizados?</strong></p> </div> <div class="paragraph"> <p>A resposta: ninguém. A menos que seja automático.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_um_pipeline_determinístico_knowledge_graph_plantuml">A solução: um pipeline determinístico Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>O princípio é simples: em vez de desenhar os diagramas à mão, os<strong>gera a partir da estrutura real do código</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify\n(pip install graphifyy)" as Graphify collections "graphify-out/graph.json\n(Knowledge Graph)" as KGJSON component "PlantUML Gradle Plugin ^^^^^ 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(Knowledge Graph)" as KGJSON component "PlantUML Gradle Plugin (generateKnowledgeGraphDiagram)" as Plugin component "Analisador de Grafo de Conhecimento" as Parser component "KnowledgeGraphRenderer" as Renderer component "PlantumlService (validação + renderização 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>Dois comandos. É isso.</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>O resultado? Arquivos`.puml` et <code>.png`em`diagrams/knowledge-graph/</code>, versionados no Git, sempre atualizados com o código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_instalar_graphify_e_extrair_o_knowledge_graph">Passo 1: Instalar Graphify e extrair o Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_instalação">Instalação</h3> <div class="paragraph"> <p>Graphify é uma ferramenta Python que analisa sua base de código e constrói um grafo de conhecimento estruturado:</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_as_exclusões">Configurar as exclusões</h3> <div class="paragraph"> <p>Criar um arquivo`.graphifyignore`à raiz do projeto para excluir os arquivos que não fazem parte da lógica de negócios :</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="_extrair_o_knowledge_graph">Extrair o 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>O flag`--no-viz`Salta a geração de HTML (desnecessária em um pipeline Gradle). O resultado é um arquivo`graphify-out/graph.json`contendo :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Nós</strong>: classes, funções, ficheiros — com o seu tipo e comunidade</p> </li> <li> <p><strong>Arestas</strong>: relações entre nós (EXTRACTED do código, INFERRED pelo LLM)</p> </li> <li> <p><strong>Comunidades</strong>: agrupamentos automáticos de nós ligados</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Exemplo de estrutura`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>O código-fonte (<code>.kt</code>, <code>.java</code>) é analisado localmente pelo tree-sitter,<strong>sem apelo LLM</strong>. Apenas os arquivos de documentação (<code>.adoc</code>, <code>.md</code>) precisam de uma chamada LLM para a extração semântica. Portanto`--update`sobre do código Kotlin é quase instantâneo.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_o_plugin_gradle_transforma_o_knowledge_graph_em_plantuml">Passo 2 : O plugin Gradle transforma o Knowledge Graph em PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitetura_do_pipeline">Arquitetura do pipeline</h3> <div class="paragraph"> <p>O plugin`com.cheroliv.plantuml`incorpora uma tarefa`generateKnowledgeGraphDiagram`que transforma`graph.json`em diagramas PlantUML de maneira<strong>totalmente determinista</strong>:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1195" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_os_componentes_internos">Os 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">Papel</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">Analisar`graph.json`— suporta 3 formatos : graphify nativo (<code>nodes</code>+<code>links</code>), legacy (<code>communities</code>), plano. Resolve os IDs numéricos para rótulos.</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 deterministicamente um`KnowledgeGraph`em código PlantUML. Grupos por tipo, comunidades em pacotes, legenda 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">Tarefa Gradle que orquestra: parse → render → validate → PNG. Configurável via propriedades do 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 dados :`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">Validação sintática + renderização PNG (reutilizado por todas as tarefas do plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_regras_de_renderização">Regras de renderização</h3> <div class="paragraph"> <p>O renderer aplica convenções visuais determinísticas :</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 aresta</th> <th class="tableblock halign-left valign-top">Notação PlantUML</th> <th class="tableblock halign-left valign-top">Significação</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>(traço cheio, preto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relação extraída do código fonte (certeza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deduzido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(traço pontilhado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relação inferida pelo LLM (pontuação de confiança)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBÍGUO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(traço vermelho pontilhado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relação ambígua (a verificar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>As comunidades são renderizadas como pacotes PlantUML com uma paleta de cores automática.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_3_uso_diário">Passo 3 : Uso diário</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>Saída:`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_comunidade">Filtrar por comunidade</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_aresta">Filtrar por tipo de aresta</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_nó_e_confiança">Filtrar por tipo de nó e confiança</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="_diretório_de_saída_personalizado">Diretório de saída 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="_referência_completa_das_propriedades">Referência completa das propriedades</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">Propriedade</th> <th class="tableblock halign-left valign-top">defeito</th> <th class="tableblock halign-left valign-top">Descrição</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 as comunidades por nome (correspondência de subcadeia)</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"><em>(todos)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de arestas separados por vírgulas:`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">Limite mínima de confiança para as arestas</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 nós a exibir</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 nós separados por vírgulas (ex.<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">Diretório de saída para os arquivos`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_pipeline_completo_em_um_workflow_gradle">O pipeline completo em um workflow Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tipo_de_workflow">Tipo de workflow</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="_integração_no_ciclo_de_desenvolvimento">Integração no ciclo de desenvolvimento</h3> <div class="paragraph"> <p>O pipeline integra-se naturalmente nas etapas-chave do desenvolvimento:</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE state "Desenvolvimento" as dev state "Extraction ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE state "Desenvolvimento" as dev state "Extraction graphify . --no-viz" as extract state "Geração ./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="_atualização_incremental">Atualização incremental</h3> <div class="paragraph"> <p>Quando o código muda, não reconstruímos todo o grafo do zero :</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`reextraído apenas os arquivos modificados (detectados por SHA256 em`graphify-out/cache/</code>). Em código Kotlin, é quase instantâneo porque o tree-sitter trabalha localmente sem chamada ao LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dogfooding_o_plugin_se_documenta_por_si_mesmo">Dogfooding: o plugin se documenta por si mesmo</h2> <div class="sectionbody"> <div class="paragraph"> <p>O plugin PlantUML existe para transformar prompts em diagramas. Ele também pode transformar o Knowledge Graph da sua <em>próprio</em> codebase em diagramas de documentação. É <em>dogfooding</em>: o plugin consome o seu próprio serviço.</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 (utilizador → diagramas)" as normal { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal (utilizador → 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 "Grafo de Conhecimento do Pipeline\n(determinista, sem 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 → documentação do 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 "Mesmo LlmService, mesmo ApiKeyPool, mesmo PlantumlService — ZERO duplicação" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>Tarefas Gradle associadas :</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">tarefa</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Descrição</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">Não</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforma`graph.json`em PlantUML (determinístico)</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">Sim</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">gere alguns`.prompt`a partir do grafo, os trata via 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_que_é_determinístico_e_por_que_isso_importa">Por que é determinístico (e por que isso importa)</h2> <div class="sectionbody"> <div class="paragraph"> <p>O ponto-chave do pipeline`generateKnowledgeGraphDiagram`:<strong>ele não chama nenhum LLM</strong>. A transformação`graph.json`→ PlantUML é uma função 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 "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>Os benefícios 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">vantagem</th> <th class="tableblock halign-left valign-top">Impacto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reproducibilidade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">mesmo`graph.json`→ mesmo diagrama. Exatamente. Sempre.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo zero</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sem chamada LLM = sem tokens = sem fatura da API.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero latência</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render demora ~100ms, não 1-5 segundos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatível CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma chave API necessária. Nenhum teste flaky devido a uma resposta LLM variável.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Versionável</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`gerado é texto. Pode`diff</code>, o revisor no PR, versioná-lo no Git.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagramas_do_próprio_pipeline">Diagramas do próprio pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para fechar o ciclo, aqui está o diagrama do pipeline como seria gerado pelo plugin :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1804" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integração_na_governança_do_projeto">Integração na governança do projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>No nosso projeto, este pipeline integra-se numa estratégia de gestão de contexto EAGER/LAZY para o agente IA. O Knowledge Graph substitui a documentação de arquitetura manual por um grafo estruturado, consultável e auto-atualizado.</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(sempre carregado)" 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 — Estratégia\n(sob demanda)" 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(sempre carregado)" 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 — Estratégia\n(sob demanda)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (consultas direcionadas)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML gerado automaticamente" 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>O casamento dos dois sistemas é complementar :</p> </div> <div class="ulist"> <ul> <li> <p><strong>A estratégia trata do QUANDO e do COMO</strong>— governança, workflow, arquivamento</p> </li> <li> <p><strong>Graphify gerencia o quê e o onde</strong>— estrutura do código, relações, consultas direcionadas</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ A estratégia de sessão gerencia o<strong>QUANDO</strong> et le <strong>como</strong>(governança, workflow, limites), Graphify gerencia o<strong>O QUE</strong> et le <strong>ONDE</strong>(estrutura do código, relações, consultas direcionadas). O pipeline PlantUML gerencia o<strong>COM O QUE</strong>(diagramas determinísticos, versionados, sempre atualizados). </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_preparação_lista_de_verificação_em_5_minutos">Preparação: lista de verificação em 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">encomenda</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 as exclusões</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Criar`.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">Extrair o 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">Gerar os 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">Fazer commit dos 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="_armadilhas_e_mitigações">Armadilhas e mitigações</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">armadilha</th> <th class="tableblock halign-left valign-top">Descrição</th> <th class="tableblock halign-left valign-top">mitigação</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo muito denso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Um grande projeto gera centenas de nós ilegíveis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar`-Pplantuml.kg.maxNodes=30`e filtrar por comunidade</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Exclusões demasiado largas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Muitos arquivos em`.graphifyignore`reduce o valor do grafo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Começar por excluir apenas credentials e build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Direção das setas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">As arestas INFERRED podem ter uma direção ambígua</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar por`-Pplantuml.kg.edgeTypes=EXTRACTED`para as relações certas apenas</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">O código muda, mas o grafo não é reconstruído</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar`graphify . --update`régulièrement ou o hook git`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo atualizado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">As atualizações incrementais são quase gratuitas (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Apenas os docs (<code>.adoc</code>) consumem tokens LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_o_que_se_obtém_no_final">O que se obtém no final</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 rectangle "ANTES" as avant { card "Diagramas desenhados à mão Sempre obsoletos ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "ANTES" as avant { card "Diagramas desenhados à mão Sempre obsoletos Ninguém os atualiza" as av1 #FDEDEC } rectangle "depois" as apres { card "Diagramas gerados automaticamente Sempre atualizados com o código Versionados no Git Determinísticos e reproduzíveis" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>Os benefícios 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">Benefício</th> <th class="tableblock halign-left valign-top">Detalhe</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentação sempre atualizada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os diagramas refletem o código atual, não um instantâneo manual</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero esforço de manutenção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os diagramas são regenerados a cada build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Redução da dívida técnica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não precisa mais manter os diagramas à mão</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexto visual para os novos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Um novo desenvolvedor entende a arquitetura olhando os diagramas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Potencial de fine-tuning</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os pares (subgrafo → diagrama) são exemplos de treinamento de IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validação automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`verifica cada diagrama gerado</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 = visão completa da arquitetura</p></td> </tr> </tbody> </table> <div class="paragraph"> <p></think></p> </div> <div class="paragraph"> <p>O <em>porquê</em> : diagramas sempre atualizados. O <em>como</em> : dois comandos em um pipeline Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify no GitHub</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">Plugin Gradle PlantUML</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">A super dica do comando fg</a>— artigo anterior sobre o workflow 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="#_o_problema_diagramas_sempre_atrasados_em_relação_ao_código">O problema: diagramas sempre atrasados em relação ao código</a></li> <li><a href="#_a_solução_um_pipeline_determinístico_grafo_de_conhecimento_plantuml">A solução : um pipeline determinístico Grafo de Conhecimento → PlantUML</a></li> <li><a href="#_passo_1_instalar_graphify_e_extrair_o_knowledge_graph">Passo 1: Instalar Graphify e extrair o Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_instalação">Instalação</a></li> <li><a href="#_configurar_as_exclusões">Configurar as exclusões</a></li> <li><a href="#_extrair_o_knowledge_graph">Extrair o Knowledge Graph</a></li> </ul> </li> <li><a href="#_etapa_2_o_plugin_gradle_transforma_o_knowledge_graph_em_plantuml">Etapa 2 : O plugin Gradle transforma o Knowledge Graph em PlantUML</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_do_pipeline">Arquitetura do pipeline</a></li> <li><a href="#_os_componentes_internos">Os componentes internos</a></li> <li><a href="#_regras_de_renderização">Regras de renderização</a></li> </ul> </li> <li><a href="#_passo_3_uso_diário">Passo 3: Uso diário</a> <ul class="sectlevel2"> <li><a href="#_diagrama_completo">diagrama completo</a></li> <li><a href="#_filtrar_por_comunidade">Filtrar por comunidade</a></li> <li><a href="#_filtrar_por_tipo_de_aresta">Filtrar por tipo de aresta</a></li> <li><a href="#_filtrar_por_tipo_de_nó_e_confiança">Filtrar por tipo de nó e confiança</a></li> <li><a href="#_diretório_de_saída_personalizado">Diretório de saída personalizado</a></li> <li><a href="#_referência_completa_das_propriedades">Referência completa das propriedades</a></li> </ul> </li> <li><a href="#_o_pipeline_completo_em_um_fluxo_de_trabalho_gradle">O pipeline completo em um fluxo de trabalho Gradle</a> <ul class="sectlevel2"> <li><a href="#_tipo_de_workflow">tipo de workflow</a></li> <li><a href="#_integração_no_ciclo_de_desenvolvimento">Integração no ciclo de desenvolvimento</a></li> <li><a href="#_atualização_incremental">Atualização incremental</a></li> </ul> </li> <li><a href="#_o_dogfooding_o_plugin_se_documenta_sozinho">O dogfooding : o plugin se documenta sozinho</a></li> <li><a href="#_por_que_isso_é_determinístico_e_por_que_isso_importa">Por que isso é determinístico (e por que isso importa)</a></li> <li><a href="#_diagramas_do_próprio_pipeline">Diagramas do próprio pipeline</a></li> <li><a href="#_integração_na_governança_do_projeto">Integração na governança do projeto</a></li> <li><a href="#_configuração_lista_de_verificação_em_5_minutos">Configuração: lista de verificação em 5 minutos</a></li> <li><a href="#_armadilhas_e_mitigações">Armadilhas e mitigações</a></li> <li><a href="#_o_que_se_obtém_no_final">O que se obtém no final</a></li> <li><a href="#_links">Links</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 12 minutes</div> <p>Seu codebase está crescendo. As dependências entre módulos estão se multiplicando. A documentação de arquitetura torna-se obsoleta antes mesmo de ser escrita. E se o seu build Gradle pudesse <em>automaticamente</em> gerar diagramas atualizados a partir da estrutura real do código? É exatamente isso que o pipeline Graphify + PlantUML Gradle Plugin faz:`graphify . --no-viz`extrai o Knowledge Graph`./gradlew generateKnowledgeGraphDiagram`o transforma em diagramas PlantUML. Zero LLM, zero manual, 100% determinístico.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_diagramas_sempre_atrasados_em_relação_ao_código">O problema: diagramas sempre atrasados em relação ao código</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo projeto que ultrapassa algumas milhares de linhas conhece esse síndrome :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Desenha-se um diagrama de arquitetura no início do projeto</p> </li> <li> <p>O código evolui, as dependências mudam</p> </li> <li> <p>O diagrama torna-se uma mentira decorativa</p> </li> <li> <p>Ninguém o atualiza porque é penoso</p> </li> <li> <p>Os recém-chegados baseiam-se nisso e cometem erros.</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>A questão não é <em>precisa de diagramas ?</em> — todo mundo sabe que sim. A questão é :<strong>quem os mantém atualizados?</strong></p> </div> <div class="paragraph"> <p>A resposta: ninguém. Exceto se for automático.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_um_pipeline_determinístico_grafo_de_conhecimento_plantuml">A solução : um pipeline determinístico Grafo de Conhecimento → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>O princípio é simples: em vez de desenhar os diagramas à mão, nós os<strong>gerado a partir da estrutura real do 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 de Conhecimento)" as KGJSON component "PlantUML Gradle Plugin\n(generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "Renderizador de Grafo de Conhecimento" as Renderer component "PlantumlService (validação + renderização 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>Dois comandos. É só isso.</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>O resultado? Arquivos`.puml` et <code>.png`em`diagrams/knowledge-graph/</code>, versionados no Git, sempre atualizados com o código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_instalar_graphify_e_extrair_o_knowledge_graph">Passo 1: Instalar Graphify e extrair o Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_instalação">Instalação</h3> <div class="paragraph"> <p>Graphify é uma ferramenta Python que analisa seu codebase e constrói um grafo de conhecimento estruturado :</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_as_exclusões">Configurar as exclusões</h3> <div class="paragraph"> <p>Criar um arquivo`.graphifyignore`na raiz do projeto para excluir os arquivos que não fazem parte da lógica de negócio:</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="_extrair_o_knowledge_graph">Extrair o 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>A flag`--no-viz`Pula a geração HTML (inutil em um pipeline Gradle). O resultado é um arquivo`graphify-out/graph.json`contendo :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Nós</strong>: classes, funções, ficheiros — com o seu tipo e comunidade</p> </li> <li> <p><strong>arestas</strong>: relações entre nós (EXTRACTED a partir do código, INFERRED pelo LLM)</p> </li> <li> <p><strong>Comunidades</strong>: agrupamentos automáticos de nós ligados</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Exemplo de estrutura`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>O código fonte (<code>.kt</code>, <code>.java</code>) é analisado localmente pelo tree-sitter,<strong>irrecorrível LLM</strong>. Apenas os arquivos de documentação (<code>.adoc</code>, <code>.md</code>) exigem uma chamada LLM para extração semântica. Portanto`--update`em código Kotlin é quase instantâneo.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_2_o_plugin_gradle_transforma_o_knowledge_graph_em_plantuml">Etapa 2 : O plugin Gradle transforma o Knowledge Graph em PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitetura_do_pipeline">Arquitetura do pipeline</h3> <div class="paragraph"> <p>O plugin`com.cheroliv.plantuml`inclui uma tarefa`generateKnowledgeGraphDiagram`que transforma`graph.json`em diagramas PlantUML de maneira<strong>totalmente determinista</strong>:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1210" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_os_componentes_internos">Os 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">Papel</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">Analisar`graph.json`suporta 3 formatos: graphify nativo (<code>nodes</code>+<code>links</code>), legado (<code>communities</code>), flat. Resolve os IDs numéricos como labels.</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 um de forma determinista`KnowledgeGraph`em código PlantUML. Grupos por tipo, comunidades em pacotes, legenda 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">Tarefa Gradle que orquestra: parse → render → validate → PNG. Configurável via propriedades do 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 dados :`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">Validação sintática + renderização PNG (reutilizado por todas as tarefas do plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_regras_de_renderização">Regras de renderização</h3> <div class="paragraph"> <p>O renderer aplica convenções visuais determinísticas:</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 aresta</th> <th class="tableblock halign-left valign-top">Notação 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>(traço cheio, preto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relação extraída do código fonte (certeza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deduzido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(traço pontilhado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relação inferida pelo LLM (pontuação de confiança)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBÍGUO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(traço vermelho pontilhado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">relação ambígua (a verificar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>As comunidades são renderizadas como pacotes PlantUML com uma paleta de cores automática.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_3_uso_diário">Passo 3: Uso diário</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>Saída :`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtrar_por_comunidade">Filtrar por comunidade</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_aresta">Filtrar por tipo de aresta</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_nó_e_confiança">Filtrar por tipo de nó e confiança</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="_diretório_de_saída_personalizado">Diretório de saída 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="_referência_completa_das_propriedades">Referência completa das propriedades</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">Propriedade</th> <th class="tableblock halign-left valign-top">defeito</th> <th class="tableblock halign-left valign-top">Descrição</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 comunidades por nome (correspondência de substring)</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"><em>(todos)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipos de arestas separados por vírgulas :`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">Limite mínima de confiança para as arestas</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">(ilimitado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Número máximo de nós para exibir</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 nós separados por vírgulas (ex.<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">Diretório de saída para os arquivos`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_pipeline_completo_em_um_fluxo_de_trabalho_gradle">O pipeline completo em um fluxo de trabalho Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tipo_de_workflow">tipo de workflow</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="_integração_no_ciclo_de_desenvolvimento">Integração no ciclo de desenvolvimento</h3> <div class="paragraph"> <p>O pipeline se integra naturalmente nas etapas-chave do desenvolvimento:</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE state "Desenvolvimento" as dev state "Extração ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE state "Desenvolvimento" as dev state "Extração graphify . --no-viz" as extract state "Geração ./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="_atualização_incremental">Atualização incremental</h3> <div class="paragraph"> <p>Quando o código muda, não reconstruímos todo o grafo do zero :</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`reextrai apenas os arquivos modificados (detectados por SHA256 em`graphify-out/cache/</code>). No código Kotlin, é quase instantâneo porque o tree-sitter trabalha localmente sem chamada LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_o_dogfooding_o_plugin_se_documenta_sozinho">O dogfooding : o plugin se documenta sozinho</h2> <div class="sectionbody"> <div class="paragraph"> <p>O plugin PlantUML existe para transformar prompts em diagramas. Ele também pode transformar o Knowledge Graph da sua <em>própria</em> codebase em diagramas de documentação. Isso é <em>dogfooding</em> : o plugin consome seu próprio serviço.</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 "Pipeline normal\n(usuário → 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 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normal\n(usuário → 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 (determinístico, sem 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 → documentação do 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 "Mesmo LlmService, mesmo ApiKeyPool, mesmo PlantumlService — ZERO duplicação" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>Tarefas do Gradle associadas:</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">Tarefa</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Descrição</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">Não</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforme`graph.json`em PlantUML (determinístico)</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">Sim</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gere alguns`.prompt`desde o grafo, ele os trata via 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_que_isso_é_determinístico_e_por_que_isso_importa">Por que isso é determinístico (e por que isso importa)</h2> <div class="sectionbody"> <div class="paragraph"> <p>O ponto-chave do pipeline`generateKnowledgeGraphDiagram`:<strong>Ele não chama nenhum LLM</strong>. A transformação`graph.json`PlantUML é uma função 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 determinístico (generateKnowledgeGraphDiagram)" as det { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline determinístico (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\n(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>Os benefícios 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">Vantagem</th> <th class="tableblock halign-left valign-top">Impacto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reprodutibilidade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mesmo`graph.json`→ mesmo diagrama. Exatamente. Todas as vezes.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo zero</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sem chamada LLM = sem tokens = sem fatura da API.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero latência</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render demora ~100ms, não 1-5 segundos.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatível CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nenhuma chave de API necessária. Nenhum teste flaky devido a uma resposta LLM variável.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">versionável</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`gerado é texto. Nós podemos`diff</code>, o reviewer no PR, versioná-lo no Git.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagramas_do_próprio_pipeline">Diagramas do próprio pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para fechar o laço, eis o diagrama do pipeline tal como seria gerado pelo plugin :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1819" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integração_na_governança_do_projeto">Integração na governança do projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em nosso projeto, este pipeline se integra em uma estratégia de gestão de contexto EAGER/LAZY para o agente IA. O Knowledge Graph substitui a documentação de arquitetura manual por um grafo estruturado, consultável e autoatualizado.</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 "EAGER (sempre carregado)" as eager { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER (sempre carregado)" 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 — Estratégia\n(sob demanda)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (consultas direcionadas)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML (gerado automaticamente)" 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>A união dos dois sistemas é complementar :</p> </div> <div class="ulist"> <ul> <li> <p><strong>A estratégia gerencia o QUANDO e o COMO</strong>— governança, fluxo de trabalho, arquivamento</p> </li> <li> <p><strong>Graphify trata o QUÊ e o ONDE</strong>— estrutura do código, relações, consultas direcionadas</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ A estratégia de sessão trata o<strong>quando</strong> et le <strong>como</strong>(governança, workflow, limites), Graphify gerencia o<strong>O que</strong> et le <strong>onde</strong>(estrutura do código, relações, consultas direcionadas). O pipeline PlantUML gerencia o<strong>COM O QUE</strong>(diagramas determinísticos, versionados, sempre atualizados). </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_configuração_lista_de_verificação_em_5_minutos">Configuração: lista de verificação em 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">(Note: Since no French text was provided in the user’s input for translation, the output is an empty string as per the instruction to translate only the given fragment.)</th> <th class="tableblock halign-left valign-top">etapa</th> <th class="tableblock halign-left valign-top">encomenda</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 as exclusões</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Criar`.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">Extrair o 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">Gerar os 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 os 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="_armadilhas_e_mitigações">Armadilhas e mitigações</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">Armadilha</th> <th class="tableblock halign-left valign-top">Descrição</th> <th class="tableblock halign-left valign-top">mitigação</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gráfico muito denso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Um grande projeto gera centenas de nós ilegíveis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Usar`-Pplantuml.kg.maxNodes=30`e filtrar por comunidade</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Exclusões demasiado amplas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Demasiados arquivos em`.graphifyignore`reduz o valor do grafo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Começar por excluir apenas credentials e build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Direção das setas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">As arestas INFERRED podem ter uma direção ambígua</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrar por`-Pplantuml.kg.edgeTypes=EXTRACTED`para as relações certas apenas</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">O código muda mas o grafo não é reconstruído</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizar`graphify . --update`regularmente ou o hook do Git`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Custo atualizado</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">As atualizações incrementais são quase gratuitas (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Apenas os docs (<code>.adoc</code>) consumem tokens LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_o_que_se_obtém_no_final">O que se obtém no final</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 rectangle "antes" as avant { card "Diagramas desenhados à mão Sempre obsoletos ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "antes" as avant { card "Diagramas desenhados à mão Sempre obsoletos Ninguém os atualiza" as av1 #FDEDEC } rectangle "DEPOIS" as apres { card "Diagramas gerados automaticamente Sempre atualizado com o código Versionados no Git Determinísticos e reprodutíveis" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>Os benefícios 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">Benefício</th> <th class="tableblock halign-left valign-top">Detalhe</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentação sempre atualizada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os diagramas refletem o código atual, não um snapshot manual</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero esforço de manutenção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Os diagramas se regeneram a cada build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Redução da dívida técnica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não é mais necessário manter os diagramas manualmente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexto visual para os novos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Um novo desenvolvedor compreende a arquitetura observando os 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">Os pares (subgrafo → diagrama) são exemplos de treinamento de IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validação automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`verifica cada diagrama gerado</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 = visão completa da arquitetura</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ Quem tem um _porquê</em> pode suportar todos os <em>como</em>. </em>__</p> </div> <div class="paragraph"> <p>O <em>porquê</em> : diagramas sempre atualizados. O <em>como</em> : dois comandos em um pipeline Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify no 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">As super dicas do comando fg</a>— artigo anterior sobre o fluxo de trabalho do 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="#_o_problema_um_terminal_ocupado">O problema: um terminal ocupado</a></li> <li><a href="#_os_três_comandos_indispensáveis">Os três comandos indispensáveis</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_suspender_sigtstp">Ctrl+Z — Suspender (SIGTSTP)</a></li> <li><a href="#_fg_retomar_em_primeiro_plano">fg — Retomar em primeiro plano</a></li> <li><a href="#_bg_retomar_em_segundo_plano">bg — Retomar em segundo plano</a></li> <li><a href="#_jobs_listar_os_jobs_do_shell">jobs — Listar os jobs do shell</a></li> </ul> </li> <li><a href="#_cenário_1_o_build_longo">Cenário 1: o build longo</a> <ul class="sectlevel2"> <li><a href="#_passo_a_passo">passo a passo</a></li> </ul> </li> <li><a href="#_cenário_2_o_editor_esquecido">Cenário 2: O editor esquecido</a></li> <li><a href="#_cenário_3_o_processo_opencode_suspenso">Cenário 3 : O processo opencode suspenso</a></li> <li><a href="#_cenário_4_gerenciar_vários_trabalhos_simultaneamente">Cenário 4: Gerenciar vários trabalhos simultaneamente</a> <ul class="sectlevel2"> <li><a href="#_resumo_dos_comandos_dos_trabalhos">Resumo dos comandos dos trabalhos</a></li> </ul> </li> <li><a href="#_diferenças_entre_fg_bg_ctrlz_ctrlc_e">Diferenças entre fg, bg, Ctrl+Z, Ctrl+C e &</a></li> <li><a href="#_o_ciclo_de_vida_completo_de_um_trabalho">O ciclo de vida completo de um trabalho</a></li> <li><a href="#_dicas_avançadas">Dicas avançadas</a> <ul class="sectlevel2"> <li><a href="#_fg_com_o_trabalho_mais_recente_e_a_alternância">fg com o trabalho mais recente e a alternância</a></li> <li><a href="#_matar_um_trabalho_corretamente">matar um trabalho corretamente</a></li> <li><a href="#_désown_desanexar_do_shell">désown : desanexar do shell</a></li> <li><a href="#_combinar_com_nohup_para_os_processos_longos">Combinar com nohup para os processos longos</a></li> </ul> </li> <li><a href="#_armadilhas_e_erros_comuns">Armadilhas e erros comuns</a> <ul class="sectlevel2"> <li><a href="#_confundir_ctrlz_e_ctrlc">Confundir Ctrl+Z e Ctrl+C</a></li> <li><a href="#_os_trabalhos_são_locais_ao_shell">Os trabalhos são locais ao shell</a></li> <li><a href="#_os_jobs_não_sobrevivem_ao_fechamento_do_shell">Os jobs não sobrevivem ao fechamento do shell</a></li> <li><a href="#_os_processos_interativos_e_fg">Os processos interativos e fg</a></li> </ul> </li> <li><a href="#_diagrama_resumo">Diagrama resumo</a></li> <li><a href="#_por_que_fg_é_subestimado">Por que fg é subestimado</a></li> <li><a href="#_memória_técnica_os_sinais">Memória técnica: os sinais</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 10 minutes</div> <p>Você lança`./gradlew build`, o terminal está bloqueado por 3 minutos, e você precisa fazer outra coisa <em>aguardando</em>? Não é necessário abrir uma nova aba.`Ctrl+Z`suspende o processo,`fg`o traz exatamente para onde você o deixou. É a dica Unix mais subestimada do dia a dia de um desenvolvedor.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_um_terminal_ocupado">O problema: um terminal ocupado</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo desenvolvedor já passou por essa situação:</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>O terminal está bloqueado. Você não pode mais digitar nenhum comando. E você precisa consultar um arquivo, executar um`git status`, ou verificar uma porta ocupada.</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 ( processo )" 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>A maioria dos desenvolvedores abre um novo terminal. Mas existe uma solução mais elegante, mais rápida e nativa: o gerenciamento de jobs.</p> </div> </div> </div> <div class="sect1"> <h2 id="_os_três_comandos_indispensáveis">Os três comandos indispensáveis</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_suspender_sigtstp">Ctrl+Z — Suspender (SIGTSTP)</h3> <div class="paragraph"> <p>`Ctrl+Z`envia o sinal`SIGTSTP`ao processo em primeiro plano. O processo é<strong>suspenso</strong>— não morto — e o terminal recupera o seu 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>O número entre colchetes`[1]`é o<strong>número do emprego</strong>. Le `+`indica o trabalho padrão</p> </div> </div> <div class="sect2"> <h3 id="_fg_retomar_em_primeiro_plano">fg — Retomar em primeiro plano</h3> <div class="paragraph"> <p>`fg`Traz o trabalho suspenso para o primeiro plano. O processo retoma exatamente onde havia parado.</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>Com um número de trabalho 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_retomar_em_segundo_plano">bg — Retomar em segundo plano</h3> <div class="paragraph"> <p>`bg`Retoma o processo <em>sem</em> bloquear o terminal. Ideal para builds longos.</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 `&`no final significa que o processo está sendo executado em segundo plano.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_listar_os_jobs_do_shell">jobs — Listar os jobs do 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 5) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primeiro plano ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primeiro plano (terminal bloqueado)" as fg #LightCoral state "Suspenso\n(Ctrl+Z)" as stopped #LightYellow state "Fundo\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="_cenário_1_o_build_longo">Cenário 1: o build longo</h2> <div class="sectionbody"> <div class="paragraph"> <p>É o caso de uso mais comum. Você inicia um build Gradle, o terminal está bloqueado, e você precisa fazer outra coisa.</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 processo" 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="_passo_a_passo">passo a passo</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="_cenário_2_o_editor_esquecido">Cenário 2: O editor esquecido</h2> <div class="sectionbody"> <div class="paragraph"> <p>Você está em`vim`, você precisa consultar outro arquivo <em>sans</em> sair`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>Mas é pesado. Com`Ctrl+Z`, é imediato:</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="410" height="510"> </div> </div> <div class="paragraph"> <p>NOTA:`vim`restaura perfeitamente o seu estado após um`fg`: posição do cursor, conteúdo do buffer, histórico de desfazer — tudo está preservado.</p> </div> </div> </div> <div class="sect1"> <h2 id="_cenário_3_o_processo_opencode_suspenso">Cenário 3 : O processo opencode suspenso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este é o cenário que motivou este artigo. Você utiliza`opencode`(ferramenta CLI para pilotar um LLM no seu código), e o processo está suspenso.</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 (agente LLM)" as agent participant "carapaça" 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>A vantagem é dupla :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Sem perda de contexto</strong>: a sessão LLM, o histórico de conversa, os arquivos abertos — tudo está preservado</p> </li> <li> <p><strong>Sem reinicialização</strong>: não é necessário reiniciar o opencode, recarregar o contexto, explicar novamente o problema ao LLM</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_cenário_4_gerenciar_vários_trabalhos_simultaneamente">Cenário 4: Gerenciar vários trabalhos simultaneamente</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et `bg`aceitam um número de job para direcionar um processo específico quando vários estão suspensos.</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="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 13) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Trabalhos suspensos" as jobs #LightYellow { card "[1] vim config.yml" as j1 card "[2] ./gradlew test" as j2 card "[3] htop" as j3 } rectangle "Ações" as actions #LightGreen { card "fg %2\n→ primeiro plano" as a1 card "bg %3 → fundo" as a2 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "Trabalhos suspensos" as jobs #LightYellow { card "[1] vim config.yml" as j1 card "[2] ./gradlew test" as j2 card "[3] htop" as j3 } rectangle "Ações" as actions #LightGreen { card "fg %2\n→ primeiro plano" as a1 card "bg %3 → fundo" as a2 card "fg %1\n→ primeiro plano" as a3 } jobs --> actions : fg/bg + numéro de job actions --> j2 : Reprend actions --> j3 : En arrière-plan note bottom of jobs Chaque job conserve son état exact entre les suspend/resume end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_resumo_dos_comandos_dos_trabalhos">Resumo dos comandos dos trabalhos</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">pedido</th> <th class="tableblock halign-left valign-top">efeito</th> <th class="tableblock halign-left valign-top">Exemplo</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">Suspende o processo em primeiro plano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Envio 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">Retoma o job padrão em primeiro 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">Retoma o job n em primeiro 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">Retome o trabalho padrão em 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">Retoma o job n em 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">Lista os jobs do shell corrente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code>(com 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">Termine o job 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="_diferenças_entre_fg_bg_ctrlz_ctrlc_e">Diferenças entre fg, bg, Ctrl+Z, Ctrl+C e &</h2> <div class="sectionbody"> <div class="paragraph"> <p>Muitos desenvolvedores confundem esses mecanismos. Eis um esclarecimento decisivo.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 15) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Suspende o processo\n(ele ainda está na memória)\nUtilizável com fg/bg" as c1 } rectangle "**Ctrl+C**\nSIGINT" as ctrlc #LightCoral { card "Finaliza o processo\n(sem possibilidade de retorno)\nPerda de todo o estado" as c2 } rectangle "**& **\n(fundo)" as ampersand #LightGreen { card "Inicie diretamente em segundo plano ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Suspende o processo\n(ele ainda está na memória)\nUtilizável com fg/bg" as c1 } rectangle "**Ctrl+C**\nSIGINT" as ctrlc #LightCoral { card "Finaliza o processo\n(sem possibilidade de retorno)\nPerda de todo o estado" as c2 } rectangle "**& **\n(fundo)" as ampersand #LightGreen { card "Inicie diretamente em segundo plano Terminal livre imediatamente" as c3 } rectangle "**fg**\n(primeiro plano)" as fg_ #SkyBlue { card "Traga um trabalho suspenso em primeiro plano Terminal ocupado" as c4 } rectangle "**bg** (background)" as bg_ #Lavender { card "Retoma um trabalho suspenso em segundo plano\nTerminal livre" 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">Atalho/Comando</th> <th class="tableblock halign-left valign-top">Sinal</th> <th class="tableblock halign-left valign-top">Efeito</th> <th class="tableblock halign-left valign-top">Voltar 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 o processo (congelado, na memória)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sim:`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">Mate o processo (terminado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não : processo destruído</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">Mate o processo + core dump</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não : processo destruído</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">Execute em segundo plano diretamente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`fg`para trazê-lo de volta para o primeiro 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`é<strong>não destrutivo</strong>. O processo está congelado tal como está, na memória. Você pode retomar imediatamente com`fg</code>. É um <em>pausa</em>, não um <em>parada</em>. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_ciclo_de_vida_completo_de_um_trabalho">O ciclo de vida completo de um trabalho</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 um job shell state "Inexistente" as none state "Primeiro plano\n(ocupa o terminal)" as foreground #LightCoral state "Suspenso ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title Ciclo de vida completo de um job shell state "Inexistente" as none state "Primeiro plano\n(ocupa o terminal)" as foreground #LightCoral state "Suspenso (Ctrl+Z / SIGTSTP)" as suspended #LightYellow state "plano de fundo (bg ou &)" as background #LightGreen state "Concluído (código de saída 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="_dicas_avançadas">Dicas avançadas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg_com_o_trabalho_mais_recente_e_a_alternância">fg com o trabalho mais recente e a alternância</h3> <div class="paragraph"> <p><code>fg`sem argumento traz o trabalho marcado</code>+<code>(o mais recente). Mas você também pode usar</code>%-`pour direcionar o trabalho 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_um_trabalho_corretamente">matar um trabalho corretamente</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_desanexar_do_shell">désown : desanexar do shell</h3> <div class="paragraph"> <p><code>disown`Remover um trabalho da tabela de trabalhos do shell. O processo continua em execução, mas não pode mais ser trazido de volta com`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_com_nohup_para_os_processos_longos">Combinar com nohup para os processos longos</h3> <div class="paragraph"> <p>Para que um processo sobreviva ao encerramento do 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 "Traga o trabalho\no mais recente (+)" as f1 card "Direcione um trabalho 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 "Traga o trabalho\no mais recente (+)" as f1 card "Direcione um trabalho específico: fg %n" as f2 card "Altere : fg %-" as f3 } rectangle "matar %n" as kill_ #LightCoral { card "SIGTERM (limpo)" as k1 card "SIGKILL -9 (forçar)" as k2 } rectangle "repudiar" as disown #Lavender { card "Desacoplado do shell (sobrevive à desconexão)" as d1 } rectangle "nohup + &" as nohup_ #LightGreen { card "Processo imunizado contra SIGHUP (sobrevive ao fechamento do 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="_armadilhas_e_erros_comuns">Armadilhas e erros comuns</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_confundir_ctrlz_e_ctrlc">Confundir Ctrl+Z e Ctrl+C</h3> <div class="paragraph"> <p>Este é o erro mais frequente.`Ctrl+C`mata o processo.`Ctrl+Z`o suspende. Se você pressiona em`Ctrl+C`por reflexo, todo o estado é perdido — arquivos abertos, sessões LLM, compilações em andamento.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/ctrlz-vs-ctrlc.svg" alt="ctrlz vs ctrlc" width="1203" height="129"> </div> </div> </div> <div class="sect2"> <h3 id="_os_trabalhos_são_locais_ao_shell">Os trabalhos são locais ao shell</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et `bg`funcionam apenas no shell que iniciou os processos. Se você abre um novo terminal, você não verá os trabalhos do outro.</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 os processos system-wide, utiliza`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="_os_jobs_não_sobrevivem_ao_fechamento_do_shell">Os jobs não sobrevivem ao fechamento do shell</h3> <div class="paragraph"> <p>Se você fechar o terminal, todos os trabalhos suspensos ou em segundo plano são destruídos. Para que um processo sobreviva, utilize`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="_os_processos_interativos_e_fg">Os processos interativos e fg</h3> <div class="paragraph"> <p>Alguns programas interativos não se portam bem depois de um`Ctrl+Z`+<code>fg</code>. É raro mas acontece :</p> </div> <div class="ulist"> <ul> <li> <p>Alguns programas que utilizam sinais (vim, htop, less lidam bem`Ctrl+Z`)</p> </li> <li> <p>Os programas de rede longos (ssh, opencode) geralmente recuperam corretamente</p> </li> <li> <p>Os programas que modificam o terminal (ncurses) podem, às vezes, deixar o terminal num estado inesperado</p> </li> </ul> </div> <div class="paragraph"> <p>Em caso de terminal corrompido depois de um`fg`, digite :</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_resumo">Diagrama resumo</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 — O tip que muda tudo" rectangle "**Problema**" as problem #LightCoral { card "Terminal bloqueado por um processo" as p1 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "fg — O tip que muda tudo" rectangle "**Problema**" as problem #LightCoral { card "Terminal bloqueado por um processo" as p1 card "Abrir um novo terminal = solução pesada" as p2 } rectangle "**Solução**" as solution #LightGreen { card "Ctrl+Z → suspender" as s1 card "fg → retoma" as s2 card "bg → em segundo plano" as s3 card "jobs → ver os suspensos" as s4 } rectangle "**Vantagens**" as advantages #SkyBlue { card "Sem perda de contexto" as a1 card "Sem reinicialização" as a2 card "Um único terminal basta" as a3 } problem -right-> solution : "A solução nativa Unix há 40 anos" 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_que_fg_é_subestimado">Por que fg é subestimado</h2> <div class="sectionbody"> <div class="paragraph"> <p>A maioria dos desenvolvedores modernos descobre`fg`tarde, ou mesmo nunca. Algumas razões:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Os IDEs escondem o terminal</strong>: VS Code oferece um terminal integrado, mas as abas múltiplas tornam`fg`menos necessário em aparência</p> </li> <li> <p><strong>As ferramentas gráficas substituem a CLI</strong>: os gerenciadores de arquivos, os monitores de sistema, os clientes Git gráficos</p> </li> <li> <p><strong>tmux e screen</strong>: esses multiplexadores resolvem o mesmo problema de maneira diferente, mas`fg`é mais simples e sempre disponível</p> </li> </ol> </div> <div class="paragraph"> <p>Contudo,`fg`é:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Universal</strong>: presente em todos os shells POSIX (bash, zsh, fish…​)</p> </li> <li> <p><strong>Sem dependência</strong>: não é necessário instalar o tmux ou o screen</p> </li> <li> <p><strong>Instantâneo</strong>: duas pancadas (<code>Ctrl+Z`então`fg</code>) para suspender e retomar</p> </li> <li> <p><strong>Preservador de contexto</strong>: o estado do processo está íntegro</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 skinparam defaultFontName sans-serif rectangle "Por que fg é subestimado?" as why #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "Por que fg é subestimado?" as why #LightCoral { card "IDE com terminal\nmulti-abas" as w1 card "Ferramentas gráficas que substituem a CLI" as w2 card "tmux/screen resolvem o problema de outra forma" as w3 } rectangle "Por que fg é superior ?" as superior #LightGreen { card "Universal : bash, zsh, fish, sh..." as s1 card "Sem dependência: sem instalação" as s2 card "Dois golpes :\nCtrl+Z depois fg" as s3 card "Contexto preservado : zero perda de estado" as s4 } why -right-> superior : "A simplicidade sempre vence" @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_memória_técnica_os_sinais">Memória técnica: os sinais</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para os curiosos, aqui estão os sinais envolvidos:</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">sinal</th> <th class="tableblock halign-left valign-top">Nome</th> <th class="tableblock halign-left valign-top">Enviado por</th> <th class="tableblock halign-left valign-top">efeito</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">Interrupção — termina o processo</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">Encerra com core dump</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">Interativo — suspende o processo</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">Continua — retoma um processo suspenso</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">terminação limpa</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">Terminação forçada (impossível de interceptar)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>O fluxo completo :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signal-flow.svg" alt="signal flow" width="431" height="525"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>`fg`não é uma dica obscura — é um mecanismo fundamental do shell Unix, disponível desde os anos 70. O fato de a maioria dos desenvolvedores ignorá-lo é um sintoma da nossa época: as IDEs e os multiplexadores nos afastaram das bases.</p> </div> <div class="paragraph"> <p>Mas quando você está em um servidor SSH, em um terminal mínimo ou simplesmente usando`opencode`e o LLM está em pleno trabalho —<code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, `jobs`são seus melhores amigos.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z suspende, fg retoma. É o pausa-play do terminal. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code>— seção JOB CONTROL</p> </li> <li> <p><code>man signal</code>— lista de sinais POSIX</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Manual de referência do Bash — Controle dos trabalhos</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 sinal — sinais Linux</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">Guia Avançado de Bash-Scripting — Controle de Trabalhos</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="#_visão_geral_do_percurso">Visão geral do percurso</a></li> <li><a href="#_o_porquê_vs_code_no_home">O Porquê : VS Code no Home</a> <ul class="sectlevel2"> <li><a href="#_o_problema_com_a_instalação_do_sistema">O problema com a instalação do sistema</a></li> <li><a href="#_a_solução_uma_instalação_local">A solução: uma instalação local</a></li> <li><a href="#_vantagens_concretas">Vantagens concretas</a></li> </ul> </li> <li><a href="#_customizar_a_fonte_do_menu_principal">Customizar a fonte do menu principal</a> <ul class="sectlevel2"> <li><a href="#_a_constatação">A constatação</a></li> <li><a href="#_a_técnica_patch_css_direto">A técnica: patch CSS direto</a></li> <li><a href="#_remover_o_aviso_de_integridade">Remover o aviso de integridade</a></li> </ul> </li> <li><a href="#_personalizar_a_fonte_do_painel_explorer_a_luta">Personalizar a fonte do painel Explorer — a luta</a> <ul class="sectlevel2"> <li><a href="#_tentativa_1_um_parâmetro_que_não_existe">Tentativa 1: um parâmetro que não existe</a></li> <li><a href="#_tentativa_2_a_extensão_custom_css_and_js_loader">Tentativa 2: a extensão Custom CSS and JS Loader</a></li> <li><a href="#_a_armadilha_é_preciso_ativar_a_extensão_a_cada_vez">A armadilha: é preciso ativar a extensão a cada vez</a></li> <li><a href="#_tentativa_3_as_linhas_se_sobrepõem">Tentativa 3: as linhas se sobrepõem</a></li> <li><a href="#_a_solução_zoom_no_contêiner_pai">A solução: <code>zoom</code> no contêiner pai</a></li> <li><a href="#_resumo_dos_seletores_e_do_que_funciona">Resumo dos seletores e do que funciona</a></li> </ul> </li> <li><a href="#_o_script_de_atualização_automática">O script de atualização automática</a> <ul class="sectlevel2"> <li><a href="#_o_problema">O problema</a></li> <li><a href="#_o_script_vscode_update_sh">O script `vscode-update.sh</a></li> </ul> </li> <li><a href="#_arquivos_envolvidos_visão_geral">Arquivos envolvidos — visão geral</a></li> <li><a href="#_lições_aprendidas">Lições aprendidas</a> <ul class="sectlevel2"> <li><a href="#_instalar_no_home_libera_tudo">Instalar no home libera tudo</a></li> <li><a href="#_zoom_font_size_para_os_componentes_de_lista">zoom` > <code>font-size</code> para os componentes de lista</a></li> <li><a href="#_a_extensão_custom_css_requer_uma_ativação_explícita">A extensão Custom CSS requer uma ativação explícita</a></li> <li><a href="#_um_script_de_atualização_é_indispensável">Um script de atualização é indispensável</a></li> </ul> </li> <li><a href="#_referências_rápidas">Referências rápidas</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo de leitura : 8 minutes</div> <p>Por que instalar o VS Code em`/opt`ou via`apt`quando a gente pode colocá-lo no seu home e transformar seu IDE num terreno de jogo sem digitar nunca`sudo`? Esta é a história de uma instalação local seguida de uma luta feroz para aumentar as fontes do menu e do explorador de arquivos.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_visão_geral_do_percurso">Visão geral do percurso</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 componentStyle rectangle actor Développeur as dev actor "opencode\n+ LLM" as agent package "Home Usuário (~)" #LightGreen { package "~/apps/" { component "VS Code ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur as dev actor "opencode\n+ LLM" as agent package "Home Usuário (~)" #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 (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="_o_porquê_vs_code_no_home">O Porquê : VS Code no Home</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_problema_com_a_instalação_do_sistema">O problema com a instalação do sistema</h3> <div class="paragraph"> <p>VS Code instalado via`apt`, <code>dnf`ou em</code>/opt`bloqueia os arquivos do aplicativo atrás dos privilégios de root. Qualquer modificação do CSS nativo, de`product.json`ou o diretório de instalação requer`sudo`.</p> </div> <div class="paragraph"> <p>Or, quando se usa<strong>opencode</strong>(ferramenta CLI para pilotar um LLM no seu código), o agente precisa poder :</p> </div> <div class="ulist"> <ul> <li> <p>Escrever nos ficheiros de configuração`~/.config/Code/User/settings.json`) — isso, já está no home</p> </li> <li> <p>Modificar os assets do IDE (CSS do workbench,<code>product.json</code>) para as customizações avançadas — isso, está bloqueado sem sudo</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_a_solução_uma_instalação_local">A solução: uma instalação local</h3> <div class="paragraph"> <p>Baixa o arquivo tarball oficial e o descompacta diretamente em`~/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>O binário então se encontra em`~/apps/VSCode-linux-x64/bin/code`. Nenhum`sudo`não é necessário para ler, modificar ou substituir qualquer arquivo sob`~/apps/VSCode-linux-x64/`.</p> </div> </div> <div class="sect2"> <h3 id="_vantagens_concretas">Vantagens concretas</h3> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-vs-system.svg" alt="vscode local vs system" width="1826" height="5676"> </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">Vantagem</th> <th class="tableblock halign-left valign-top">Detalhe</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sem sudo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Todos os arquivos do IDE pertencem ao usuário</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Modificação direta do CSS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Podemos aplicar patches`workbench.desktop.main.css`sem elevação de privilégios</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Script de atualização caseira</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Um simples script de shell baixa, substitui e repatch automaticamente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Isolação</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A instalação do sistema não está poluída; rollback = excluir a pasta</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_customizar_a_fonte_do_menu_principal">Customizar a fonte do menu principal</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_constatação">A constatação</h3> <div class="paragraph"> <p>A fonte padrão do menu principal (File, Edit, View…​) e dos menus suspensos é muito pequena. O VS Code não oferece nenhum parâmetro para modificá-la.</p> </div> </div> <div class="sect2"> <h3 id="_a_técnica_patch_css_direto">A técnica: patch CSS direto</h3> <div class="paragraph"> <p>Adicionamos CSS ao final do arquivo`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="_remover_o_aviso_de_integridade">Remover o aviso de integridade</h3> <div class="paragraph"> <p>VS Code detecta as modificações de seus arquivos e exibe um banner \"Your installation is corrupt\". Remove-se os 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>Após reinicialização, não há mais avisos e os menus finalmente são legíveis.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_personalizar_a_fonte_do_painel_explorer_a_luta">Personalizar a fonte do painel Explorer — a luta</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tentativa_1_um_parâmetro_que_não_existe">Tentativa 1: um parâmetro que não existe</h3> <div class="paragraph"> <p>Primeiro tenta o parâmetro nativo`workbench.tree.fontSize`em`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>nenhum efeito</strong>. Este parâmetro não existe no VS Code. A prova de que os parâmetros não reconhecidos são ignorados silenciosamente.</p> </div> </div> <div class="sect2"> <h3 id="_tentativa_2_a_extensão_custom_css_and_js_loader">Tentativa 2: a extensão Custom CSS and JS Loader</h3> <div class="paragraph"> <p>Instala-se a extensão`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>Cria-se um arquivo CSS em`~/.vscode-custom-css/custom.css`com seletores que visam os elementos do 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>E referenciamos este arquivo nas configurações:</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>as alterações não se aplicam</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_a_armadilha_é_preciso_ativar_a_extensão_a_cada_vez">A armadilha: é preciso ativar a extensão a cada vez</h3> <div class="paragraph"> <p>A documentação da extensão é discreta sobre este ponto crucial: após cada modificação do CSS personalizado, é necessário<strong>imperativamente</strong>executar o comando a partir da paleta :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>Ctrl+Shift+P</code>→ digitar<strong>Ativar CSS e JS personalizados</strong></p> </li> <li> <p>VS Code pede uma reinicialização → aceitar</p> </li> </ol> </div> <div class="paragraph"> <p>Sem esta etapa, o CSS nunca é injetado na IDE.</p> </div> </div> <div class="sect2"> <h3 id="_tentativa_3_as_linhas_se_sobrepõem">Tentativa 3: as linhas se sobrepõem</h3> <div class="paragraph"> <p>Mesmo com`font-size: 22px` et <code>line-height: 36px</code>, as letras com haste (g, p, f, b) transbordam para as linhas vizinhas. Tentamos acrescentar</p> </div> <div class="paragraph"> <p></think></p> </div> <div class="paragraph"> <p>, as letras com haste (g, p, f, b) transbordam para as linhas vizinhas. Tentamos acrescentar`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>nenhuma mudança</strong>. VS Code calcula as alturas das linhas em JavaScript e sobrescreve os valores CSS</p> </div> </div> <div class="sect2"> <h3 id="_a_solução_zoom_no_contêiner_pai">A solução: <code>zoom</code> no contêiner pai</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE rectangle "Tentativa 1 Parâmetro inexistente" #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "Tentativa 1 Parâmetro inexistente" #LightCoral { card "workbench.tree.fontSize" as t1 { [VS Code ignore le paramètre] } } rectangle "Tentativa 2 Custom CSS + font-size" #LightYellow { card ".monaco-list-row { font-size: 22px }" as t2 { [Texte plus grand\nmais lignes superposées] } } rectangle "Tentativa 3\nfont-size + line-height + height" #LightYellow { card "height: 36px !important" as t3 { [VS Code override\npar JavaScript] [Aucun effet] } } rectangle "Solution\nzoom sur conteneur parent" #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>Em vez de lutar contra o layout JavaScript, usa-se a propriedade`zoom`sobre o contêiner das linhas :</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`Aumenta uniformemente a renderização do contêiner — texto e espaçamento — sem quebrar o layout calculado pelo motor JavaScript do VS Code. O fator 1.25 corresponde aproximadamente a um aumento de 13 px para 16 px.</p> </div> <div class="paragraph"> <p>Resultado :<strong>os nomes de arquivos são finalmente legíveis, as linhas corretamente espaçadas</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_resumo_dos_seletores_e_do_que_funciona">Resumo dos seletores e do 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">abordagem</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 maior mas linhas sobrepostas</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">Nenhum efeito (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">Sucesso — texto + espaçamento proporcional</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_o_script_de_atualização_automática">O script de atualização automática</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE autonumber actor "Desenvolvedor ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE autonumber actor "Desenvolvedor ou cron" as dev participant "vscode-update.sh" as script participant "vscode tarball (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 : "Já está atualizado!" 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 : "Atualização concluída 1.xx.yy → 1.zz.ww" end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_o_problema">O problema</h3> <div class="paragraph"> <p>Quando o VS Code se atualiza, ele substitui a pasta de instalação e<strong>Apaga todos os patches de CSS</strong>. É preciso reaplicar as modificações manualmente a cada vez.</p> </div> </div> <div class="sect2"> <h3 id="_o_script_vscode_update_sh">O script `vscode-update.sh</h3> <div class="paragraph"> <p>Criamos`~/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>O script :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Baixa a última versão estável</p> </li> <li> <p>Verifique se a versão difere da atual</p> </li> <li> <p>Salva a instalação atual (timestamp) em`~/apps/vscode-backup/`</p> </li> <li> <p>Substitua a pasta de instalação</p> </li> <li> <p><strong>Reaplica</strong>o patch CSS do menu principal</p> </li> <li> <p><strong>Apague os checksums</strong> de `product.json`para evitar o aviso de integridade</p> </li> </ol> </div> <div class="paragraph"> <p>NOTA: As personalizações do painel Explorer via a extensão Custom CSS e o arquivo`~/.vscode-custom-css/custom.css`sobrevivem às atualizações porque vivem fora da pasta de instalação.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquivos_envolvidos_visão_geral">Arquivos envolvidos — visão geral</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 "Instalação VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Instalação VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { component "workbench.desktop\n.main.css" as css #LightCoral component "product.json" as product #LightCoral component "binário bin/code" as binary #LightCoral } rectangle "Configuração do utilizador (~/.config/Code/)" #LightGreen { component "settings.json" as settings #LightGreen component "extensões/" as extensions #LightGreen } rectangle "Personalização persistente (~/.vscode-custom-css/)" #SkyBlue { component "custom.css (zoom: 1.25)" as customcss #SkyBlue } rectangle "Automatização (~/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">Caminho</th> <th class="tableblock halign-left valign-top">Papel</th> <th class="tableblock halign-left valign-top">Sobrevive às atualizações ?</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">Instalação do IDE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não (substituída)</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 do workbench (menu, dropdowns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não (re-patchado pelo 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">Somas de verificação de integridade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não (re-limpo pelo 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 atualização automática</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sim</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">Configurações do usuário (fontSize, CSS personalizado)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sim</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 o Explorer (zoom)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sim</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lições_aprendidas">Lições 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 "Instalação local no home" as install #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 rectangle "Instalação local no home" as install #LightGreen { card "Sem sudo para modificar CSS/config" as i1 card "opencode+LLM pode\n modificar tudo" as i2 card "Rollback = restaurar\n o backup horodatado" as i3 } rectangle "Personalização CSS zoom vs font-size" as css #LightYellow { card "zoom > font-size para lista de componentes" as c1 card "Sobrescrever layout JS altura/altura-da-linha" as c2 card "Extension Custom CSS requer ativação manual (Ctrl+Shift+P)" as c3 } rectangle "Automação script de atualização" as auto #LightCoral { card "Reaplicar patch CSS após\n cada atualização" as a1 card "Remover checksums\n product.json" as a2 card "Backup horodatado antes da substituição" 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_no_home_libera_tudo">Instalar no home libera tudo</h3> <div class="paragraph"> <p>Uma instalação local em`~/apps`dá um controle total sobre o VS Code:</p> </div> <div class="ulist"> <ul> <li> <p>Sem`sudo`para modificar o CSS ou a configuração</p> </li> <li> <p>O agente opencode+LLM pode escrever nos arquivos de config e os ativos da IDE</p> </li> <li> <p>Rollback trivial: restaurar o backup horodatado</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_zoom_font_size_para_os_componentes_de_lista">zoom` > <code>font-size</code> para os componentes de lista</h3> <div class="paragraph"> <p>VS Code controla a altura das linhas via JavaScript. Modificar`font-size`sem poder tocar na altura alocada pelo motor de layout resulta em textos que transbordam. A propriedade`zoom`No contêiner pai amplia tudo proporcionalmente e contorna esse problema.</p> </div> </div> <div class="sect2"> <h3 id="_a_extensão_custom_css_requer_uma_ativação_explícita">A extensão Custom CSS requer uma ativação explícita</h3> <div class="paragraph"> <p>Não é um parâmetro "set and forget". Cada modificação do arquivo CSS personalizado requer reexecutar "Enable Custom CSS and JS" a partir da paleta de comandos`Ctrl+Shift+P`).</p> </div> </div> <div class="sect2"> <h3 id="_um_script_de_atualização_é_indispensável">Um script de atualização é indispensável</h3> <div class="paragraph"> <p>Sem script, cada atualização do VS Code apaga os patches CSS do workbench. O script`vscode-update.sh`Automatiza o download, a substituição, o re-patch e a limpeza dos checksums.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_referências_rápidas">Referências rápidas</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Download VS Code: <a href="https://code.visualstudio.com/Download" class="bare">https://code.visualstudio.com/Download</a></p> </li> <li> <p>Extensão Personalizada de CSS e JS Loader :`be5invis.vscode-custom-css`</p> </li> <li> <p>Problema VS Code pedindo um parâmetro nativo para a fonte do Explorerhttps://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_e_objetivo">Contexto e objetivo</a> <ul class="sectlevel2"> <li><a href="#_o_ponto_de_partida">O ponto de partida</a></li> <li><a href="#_o_objetivo">O objetivo</a></li> </ul> </li> <li><a href="#_o_primeiro_obstáculo_ruby_gems">O primeiro obstáculo: `ruby { gems() }</a> <ul class="sectlevel2"> <li><a href="#_o_que_o_açúcar_sintático_do_groovy_esconde">O que o açúcar sintático do Groovy esconde</a></li> <li><a href="#_decomposição_do_mecanismo">Decomposição do mecanismo</a></li> </ul> </li> <li><a href="#_a_solução_em_três_partes">A solução em três partes</a> <ul class="sectlevel2"> <li><a href="#_parte_1_o_repositório_ivy_para_rubygems">Parte 1: o repositório Ivy para rubygems</a></li> <li><a href="#_parte_2_a_dependência_asciidoctorgems">Parte 2 : a dependência asciidoctorGems</a></li> <li><a href="#_parte_3_settings_gradle_kts">Parte 3 : settings.gradle.kts</a></li> </ul> </li> <li><a href="#_introspecção_da_api_por_bytecodes">Introspecção da API por bytecodes</a> <ul class="sectlevel2"> <li><a href="#_por_que_javap">Por que <code>javap</code>?</a></li> <li><a href="#_hierarquia_da_tarefa">Hierarquia da tarefa</a></li> <li><a href="#_descoberta_de_forkoptions">Descoberta de `forkOptions</a></li> <li><a href="#_a_api_de_javaforkoptions_grolifant">A API de JavaForkOptions (grolifant)</a></li> <li><a href="#_extensão_revealjs">Extensão RevealJS</a></li> </ul> </li> <li><a href="#_configuração_do_toolchain_java">Configuração do toolchain Java</a> <ul class="sectlevel2"> <li><a href="#_o_problema_de_javatoolchainservice">O problema de JavaToolchainService</a></li> </ul> </li> <li><a href="#_detecção_automática_docker">Detecção automática Docker</a> <ul class="sectlevel2"> <li><a href="#_contexto">Contexto</a></li> <li><a href="#_estratégia">Estratégia</a></li> </ul> </li> <li><a href="#_resultado_final">Resultado final</a> <ul class="sectlevel2"> <li><a href="#_o_buildscript_consumidor">O buildscript consumidor</a></li> <li><a href="#_settings_gradle_kts">settings.gradle.kts</a></li> </ul> </li> <li><a href="#_resumo_das_armadilhas_e_soluções">Resumo das armadilhas e soluções</a></li> <li><a href="#_método_de_investigação_ler_uma_api_desconhecida_com_javap">Método de investigação : ler uma API desconhecida com javap</a> <ul class="sectlevel2"> <li><a href="#_princípio">Princípio</a></li> <li><a href="#_passo_1_localizar_o_jar_no_cache_do_gradle">Passo 1: localizar o jar no cache do Gradle</a></li> <li><a href="#_etapa_2_listar_as_classes_do_jar">Etapa 2 : listar as classes do jar</a></li> <li><a href="#_etapa_3_inspecionar_uma_classe">Etapa 3: inspecionar uma classe</a></li> <li><a href="#_passo_4_subir_na_hierarquia">Passo 4: subir na hierarquia</a></li> <li><a href="#_passo_5_seguir_os_tipos_desconhecidos">Passo 5: seguir os tipos desconhecidos</a></li> <li><a href="#_etapa_6_verificar_as_extensões_do_projeto">Etapa 6 : verificar as extensões do projeto</a></li> <li><a href="#_resumo_do_método">Resumo do método</a></li> </ul> </li> <li><a href="#_próxima_etapa">próxima etapa</a></li> </ul> </div> <div class="sect1"> <h2 id="_contexto_e_objetivo">Contexto e objetivo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_ponto_de_partida">O ponto de partida</h3> <div class="paragraph"> <p>O projeto`slider-gradle`gera apresentações Reveal.js a partir de arquivos AsciiDoc via o plugin Gradle`org.asciidoctor.jvm.revealjs`. A configuração da tarefa principal`asciidoctorRevealJs`vivia diretamente no script de construção raiz`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="_o_objetivo">O objetivo</h3> <div class="paragraph"> <p>Mover toda essa configuração para`buildSrc/src/main/kotlin/slides/SlidesPlugin.kt`para que o buildscript do consumidor se reduza à:</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>O plugin deve ser totalmente autônomo: ele aplica por si mesmo as dependências de plugins, configura seus repositórios, e gerencia suas gems Ruby.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_o_primeiro_obstáculo_ruby_gems">O primeiro obstáculo: `ruby { gems() }</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_que_o_açúcar_sintático_do_groovy_esconde">O que o açúcar sintático do Groovy esconde</h3> <div class="paragraph"> <p>A linha`repositories { ruby { gems() } }`é uma extensão DSL Groovy disponível apenas no contexto de execução do buildscript. Ela não existe como uma API Kotlin estática acessível a partir de buildSrc.</p> </div> <div class="paragraph"> <p>Ao tentar chamá-lo desde`SlidesPlugin.kt`, a compilação falha imediatamente.</p> </div> </div> <div class="sect2"> <h3 id="_decomposição_do_mecanismo">Decomposição do mecanismo</h3> <div class="paragraph"> <p>Após análise do cache Gradle (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), descobre-se no arquivo`ivy-3.1.0.xml`:</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() }`efetuava na realidade<strong>três operações distintas</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Salvar um repositório Ivy apontando para`https://rubygems.org/gems/`</p> </li> <li> <p>Excluir o grupo`rubygems`repositórios Maven para evitar conflitos</p> </li> <li> <p>Salvar a gema na configuração`asciidoctorGems`para que o JRuby a carregue em tempo de execução</p> </li> </ol> </div> <div class="paragraph"> <p>Essas três responsabilidades devem ser reproduzidas separadamente em Kotlin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_em_três_partes">A solução em três partes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_parte_1_o_repositório_ivy_para_rubygems">Parte 1: o repositório 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>A extensão`.gem`deve estar hardcodada`[ext]<code>resolve por padrão em</code>.jar`, que causa um erro`Resource missing`.</td> </tr> </table> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> O repo Ivy é declarado diretamente em`project.repositories`e não em um bloco`repositories { }`porque o receiver deste bloco não é o`RepositoryHandler`padrão do Gradle mas uma API grolifant incompatível com a extensão`ivy`Kotlin DSL. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_parte_2_a_dependência_asciidoctorgems">Parte 2 : a dependência asciidoctorGems</h3> <div class="paragraph"> <p>O plugin`org.asciidoctor.jvm.gems`deve ser aplicado primeiro — ele cria a configuração`asciidoctorGems`e a tarefa`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>A ordem de aplicação é importante:`gems`antes`revealjs`. <2> O qualificador`@gem`força a extensão correta na dependência.</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`em`settings.gradle.kts`deve permitir que os projetos declarem seus próprios repositórios:</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>Sem essa linha, o Gradle ignora os repositórios declarados no plugin e a resolução das gems falha.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_introspecção_da_api_por_bytecodes">Introspecção da API por bytecodes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_por_que_javap">Por que <code>javap</code>?</h3> <div class="paragraph"> <p>O plugin`asciidoctor-gradle-jvm-slides`está em versão`4.0.0-alpha.1`. Sua documentação é inexistente ou incompleta. A única fonte confiável é a inspeção direta das classes compiladas.</p> </div> </div> <div class="sect2"> <h3 id="_hierarquia_da_tarefa">Hierarquia da tarefa</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="_descoberta_de_forkoptions">Descoberta de `forkOptions</h3> <div class="paragraph"> <p>Ao inspecionar`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>Encontra-se:</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="_a_api_de_javaforkoptions_grolifant">A API de JavaForkOptions (grolifant)</h3> <div class="paragraph"> <p>`javaLauncher`não existe nesta tarefa. A API real de`org.ysb33r.grolifant.api.v4.JavaForkOptions`exposição :</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>O método`executable(Object)`substitui a atribuição`executable = …​`que não compila (`val`não pode ser reatribuído).</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_extensão_revealjs">Extensão RevealJS</h3> <div class="paragraph"> <p>`revealjs { }`não é um método da tarefa mas uma<strong>extensão de projeto</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>É acessada via :</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="_configuração_do_toolchain_java">Configuração do toolchain Java</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_problema_de_javatoolchainservice">O problema de JavaToolchainService</h3> <div class="paragraph"> <p>`JavaToolchainService`não é uma extensão de projeto. A chamada seguinte falha :</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>A boa API é`serviceOf`(There is no text to translate, so output is empty.)</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="_detecção_automática_docker">Detecção automática Docker</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto">Contexto</h3> <div class="paragraph"> <p>O plugin Asciidoctor/JRuby requer Java 17. Kotlin 2.0.x em buildSrc não suporta o Java 25 (o analisador de versão falha em`"25.0.2"`). O daemon Gradle deve portanto rodar no Java 17 ou o Docker deve ser usado.</p> </div> </div> <div class="sect2"> <h3 id="_estratégia">Estratégia</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Docker disponível → execução via contêiner`eclipse-temurin:17`(comportamento padrão)</p> </li> <li> <p>Docker ausente + Java 17 → execução local</p> </li> <li> <p>Docker ausente + Java > 17 → erro 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="_o_buildscript_consumidor">O 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>Isso é tudo. O plugin assume toda a responsabilidade.</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="_resumo_das_armadilhas_e_soluções">Resumo das armadilhas e soluções</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">Solução</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`ruby { gems() }`não disponível em Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensão DSL Groovy apenas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Três mecanismos separados: repositório Ivy + exclusão Maven +<code>asciidoctorGems</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle procura um`.jar`em vez de um`.gem`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`[ext]`resolve em`jar`por padrão</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Hardcoder`.gem`no padrão Ivy + qualificador`@gem`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ivy { }`não compila em`repositories { }</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Receiver grolifant incompatível com o DSL Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chamada direta`project.repositories.ivy { }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`javaLauncher`não resolvido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Propriedade inexistente em`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 = …​`não compila</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">propriedade`val`dentro`JavaForkOptions`elefante grande</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Método`executable(Object)`no lugar de</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>JavaToolchainService`não encontrado via`extensions</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Este é um serviço Gradle, não uma extensão</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 { }`não resolvido na tarefa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extensão do projeto, não método de tarefa</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">Build falha com o Java 25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin 2.0.x não analisa as versões Java de dois dígitos</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detecção Docker automática + fallback Java 17</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_método_de_investigação_ler_uma_api_desconhecida_com_javap">Método de investigação : ler uma API desconhecida com javap</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_princípio">Princípio</h3> <div class="paragraph"> <p>Quando a documentação está ausente ou incompleta, os bytecodes são a fonte da verdade. <code>javap`é a ferramenta padrão do JDK que descompila os arquivos</code>.class`em assinaturas Java legíveis, sem precisar do código-fonte</p> </div> </div> <div class="sect2"> <h3 id="_passo_1_localizar_o_jar_no_cache_do_gradle">Passo 1: localizar o jar no cache do Gradle</h3> <div class="paragraph"> <p>Gradle baixa todas as suas dependências em`~/.gradle/caches/modules-2/files-2.1/`. A primeira etapa é encontrar o JAR que contém a classe a ser inspecionada :</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="_etapa_2_listar_as_classes_do_jar">Etapa 2 : listar as classes do jar</h3> <div class="paragraph"> <p>Antes de inspecionar uma classe, verifica-se que ela realmente existe no 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>Isso revela todas as classes disponíveis: <code>AsciidoctorJRevealJSTask</code>, <code>RevealJSExtension</code>, <code>RevealJSOptions</code>, etc.</p> </div> </div> <div class="sect2"> <h3 id="_etapa_3_inspecionar_uma_classe">Etapa 3: inspecionar uma classe</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>A opção`-p`mostra todos os membros, inclusive os privados. O resultado mostra imediatamente a linha chave :</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="_passo_4_subir_na_hierarquia">Passo 4: subir na hierarquia</h3> <div class="paragraph"> <p>A tarefa estende`AbstractAsciidoctorTask`. Inspeciona-se à sua vez localizando primeiro o seu 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>É aí que se descobre`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="_passo_5_seguir_os_tipos_desconhecidos">Passo 5: seguir os tipos desconhecidos</h3> <div class="paragraph"> <p>`JavaForkOptions`est é uma classe grolifant desconhecida. Localizamos o seu 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>Então, inspeciona-se:</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>Lá se encontra`executable(java.lang.Object)<code>— o método correto a ser chamado, ao contrário de`executable = …​`que não compila porque é uma propriedade`val</code>.</p> </div> </div> <div class="sect2"> <h3 id="_etapa_6_verificar_as_extensões_do_projeto">Etapa 6 : verificar as extensões do projeto</h3> <div class="paragraph"> <p>para`revealjs { }`, a pergunta era : é um método da tarefa ou uma extensão de projeto? A inspeção de`AsciidoctorJRevealJSTask` não mostra nenhum método`revealjs`. Inspeciona-se então`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>A presença de`NAME`confirma que é uma extensão registrada no projeto, acessível via`project.extensions.getByType<RevealJSExtension>()`.</p> </div> </div> <div class="sect2"> <h3 id="_resumo_do_método">Resumo do 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">Ação</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 o 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>— verificar que a classe 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>— inspecionar a classe</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`e subir na hierarquia</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 os tipos desconhecidos nos seus próprios jars</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">Procurar`NAME`para identificar uma extensão de projeto</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Este método aplica-se a qualquer plugin Gradle cuja API não está documentada ou cuja versão alfa não corresponde mais à documentação existente.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_próxima_etapa">próxima etapa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este plugin buildSrc será extraído para um projeto independente publicado no Gradle Plugin Portal ou no Maven Local. O buildscript do consumidor passará a ser:</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`será reduzido ao seu mínimo estrito sem referência a`foojay-resolver-convention</code>, o provisionamento do JDK sendo gerenciado pelo próprio plugin ou documentado como pré-requisito.</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="#_visão_arquitetural">Visão arquitetural</a> <ul class="sectlevel2"> <li><a href="#_princípio_orientador">Princípio orientador</a></li> <li><a href="#_escolha_estratégica_asciidoc_para_o_portfólio">Escolha estratégica : AsciiDoc para o portfólio</a></li> <li><a href="#_modelo_de_dados">modelo de dados</a></li> </ul> </li> <li><a href="#_casos_de_uso_detalhados">Casos de Uso Detalhados</a> <ul class="sectlevel2"> <li><a href="#_uc1_adicionar_um_elemento_ao_portfólio">UC1 : Adicionar um elemento ao portfólio</a> <ul class="sectlevel3"> <li><a href="#_fluxo_nominal">Fluxo nominal</a></li> <li><a href="#_modelo_do_arquivo_a_ser_criado">modelo do arquivo a ser criado</a></li> <li><a href="#_pontos_de_validação">Pontos de validação</a></li> </ul> </li> <li><a href="#_uc2_remover_um_item_do_portfólio">UC2: Remover um item do portfólio</a> <ul class="sectlevel3"> <li><a href="#_fluxo_nominal_2">fluxo nominal</a></li> <li><a href="#_estratégia_alternativa_arquivamento">Estratégia alternativa : arquivamento</a></li> <li><a href="#_limpeza_de_recursos">Limpeza de recursos</a></li> </ul> </li> <li><a href="#_uc3_definir_como_não_publicado_rascunho">UC3 : Definir como não publicado (rascunho)</a> <ul class="sectlevel3"> <li><a href="#_fluxo_nominal_3">Fluxo nominal</a></li> <li><a href="#_estados_possíveis">Estados possíveis</a></li> <li><a href="#_casos_de_uso_típicos">Casos de uso típicos</a></li> </ul> </li> </ul> </li> <li><a href="#_arquitetura_de_templating">Arquitetura de Templating</a> <ul class="sectlevel2"> <li><a href="#_estratégia_de_templates_reutilizáveis">Estratégia de templates reutilizáveis</a></li> <li><a href="#_padrão_de_extração_de_dados">Padrão de extração de dados</a></li> <li><a href="#_convenções_de_nomenclatura">Convenções de nomenclatura</a></li> </ul> </li> <li><a href="#_fluxo_de_publicação">Fluxo de Publicação</a> <ul class="sectlevel2"> <li><a href="#_pipeline_de_desenvolvimento">Pipeline de desenvolvimento</a></li> <li><a href="#_ambientes">Ambientes</a></li> </ul> </li> <li><a href="#_extensibilidade">extensibilidade</a> <ul class="sectlevel2"> <li><a href="#_adição_de_novos_atributos">Adição de novos atributos</a></li> <li><a href="#_categorização_avançada">Categorização avançada</a></li> </ul> </li> <li><a href="#_boas_práticas">Boas Práticas</a> <ul class="sectlevel2"> <li><a href="#_organização_dos_arquivos">Organização dos arquivos</a></li> <li><a href="#_gestão_de_conteúdo">Gestão de conteúdo</a></li> <li><a href="#_desempenho">Desempenho</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div class="sect1"> <h2 id="_visão_arquitetural">Visão arquitetural</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_princípio_orientador">Princípio orientador</h3> <div class="paragraph"> <p>A arquitetura baseia-se no princípio de <strong>separação de preocupações</strong>:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Conteúdo</strong> : ficheiros AsciiDoc estruturados com metadados ricos</p> </li> <li> <p>Apresentação : templates Thymeleaf reutilizáveis</p> </li> <li> <p><strong>Dados</strong> : modelo extraído automaticamente pelo JBake a partir dos atributos AsciiDoc</p> </li> <li> <p><strong>Style</strong> : Bootstrap 5 para consistência visual</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_escolha_estratégica_asciidoc_para_o_portfólio">Escolha estratégica : AsciiDoc para o portfólio</h3> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Por que AsciiDoc ?</caption> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Critério</th> <th class="tableblock halign-left valign-top">vantagem</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coerência</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mesmo formato que os artigos de blog</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metadados</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Atributos estruturados e extensíveis (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Manutenabilidade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Edição simples em texto, versionável Git</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Flexibilidade</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pode conter conteúdo rico (tabelas, código, imagens)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelagem</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake extrai automaticamente os atributos para o Thymeleaf</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_modelo_de_dados">modelo de dados</h3> <div class="paragraph"> <p>Cada projeto de portfólio é um documento AsciiDoc com:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Metadados de cabeçalho</strong> : informações estruturadas (cliente, duração, tecnologias, etc.)</p> </li> <li> <p><strong>Corpo do documento</strong>: descrição narrativa, desafios, soluções, resultados</p> </li> <li> <p><strong>Atributos personalizados</strong> : prefixados`project-*`para extração automática</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-c4f40eb68af74c037ff02a1abed1ac32.png" alt="Diagram" width="386" height="811"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casos_de_uso_detalhados">Casos de Uso Detalhados</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_adicionar_um_elemento_ao_portfólio">UC1 : Adicionar um elemento ao portfólio</h3> <div class="sect3"> <h4 id="_fluxo_nominal">Fluxo 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 Text" as editor participant "Arquivo\nAsciiDoc" as file participant "JBake\nEngine" as jbake participant "Site Estático" 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="_modelo_do_arquivo_a_ser_criado">modelo do arquivo a ser criado</h4> <div class="paragraph"> <p>O desenvolvedor cria`content/portfolio/nom-projet.adoc`com uma estrutura padronizada:</p> </div> <div class="ulist"> <ul> <li> <p>Cabeçalho com todos os atributos necessários</p> </li> <li> <p>Seções normalizadas (Contexto, Desafios, Soluções, Resultados)</p> </li> <li> <p>Nomenclatura coerente das imagens</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_pontos_de_validação">Pontos de validação</h4> <div class="ulist"> <ul> <li> <p>Os atributos obrigatórios estão presentes (<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>As imagens referenciadas existem em`assets/img/portfolio/`</p> </li> <li> <p>O build JBake é bem-sucedido sem erro</p> </li> <li> <p>O projeto aparece na página do portfólio</p> </li> <li> <p>A página individual do projeto aparece corretamente</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_remover_um_item_do_portfólio">UC2: Remover um item do portfólio</h3> <div class="sect3"> <h4 id="_fluxo_nominal_2">fluxo 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\nArquivos" as fs participant "JBake ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Sistema\nArquivos" as fs participant "JBake Motor" as jbake participant "Site\nestático" as site database "Cache\nJBake" 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="_estratégia_alternativa_arquivamento">Estratégia alternativa : arquivamento</h4> <div class="paragraph"> <p>Em vez de excluir definitivamente, possibilidade de criar uma pasta`content/portfolio/archive/` :</p> </div> <div class="ulist"> <ul> <li> <p>Mover o arquivo em vez de excluí-lo</p> </li> <li> <p>Permite restaurar facilmente</p> </li> <li> <p>Mantenha o histórico do Git mais claro</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_limpeza_de_recursos">Limpeza de recursos</h4> <div class="ulist"> <ul> <li> <p>Verificar imagens órfãs em`assets/img/portfolio/`</p> </li> <li> <p>Remover as imagens não referenciadas por outros projetos</p> </li> <li> <p>Limpar o cache JBake para evitar referências fantasma</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_definir_como_não_publicado_rascunho">UC3 : Definir como não publicado (rascunho)</h3> <div class="sect3"> <h4 id="_fluxo_nominal_3">Fluxo nominal</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-ea5a4f20ac88987652487688528eada9.png" alt="Diagram" width="783" height="594"> </div> </div> </div> <div class="sect3"> <h4 id="_estados_possíveis">Estados possíveis</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>Projeto em fase de redação</strong> : criar como rascunho, publicar quando pronto</p> </li> <li> <p><strong>Projeto confidencial temporariamente</strong> : passar para draft durante o acordo do cliente</p> </li> <li> <p><strong>Atualização principal</strong> : mudar para rascunho, editar, republicar</p> </li> <li> <p><strong>A/B testing</strong> : duplicar em rascunho, testar, publicar a melhor versão</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_de_templating">Arquitetura de Templating</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estratégia_de_templates_reutilizáveis">Estratégia de templates reutilizáveis</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-126dbf148ebd98a966dcd20d639eaaec.png" alt="Diagram" width="881" height="350"> </div> </div> </div> <div class="sect2"> <h3 id="_padrão_de_extração_de_dados">Padrão de extração de dados</h3> <div class="paragraph"> <p>JBake transforma automaticamente os atributos AsciiDoc em propriedades acessíveis no Thymeleaf :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-8cd09abdf9a8787f0fca59cd6a661fdf.png" alt="Diagram" width="891" height="347"> </div> </div> </div> <div class="sect2"> <h3 id="_convenções_de_nomenclatura">Convenções de nomenclatura</h3> <div class="ulist"> <ul> <li> <p><strong>Atributos do projeto</strong> : prefixo`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>Ficheiros</strong>: kebab-case (ex:`ecommerce-platform.adoc`)</p> </li> <li> <p><strong>Imagens</strong> : prefixo nome-projeto (ex:`ecommerce-platform-thumb.jpg`)</p> </li> <li> <p><strong>modelos</strong> : nome funcional (ex:`project-card.html`, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fluxo_de_publicação">Fluxo de Publicação</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pipeline_de_desenvolvimento">Pipeline de desenvolvimento</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-9b8b335bedc9baf971f28bc1f2776687.png" alt="Diagram" width="386" height="811"> </div> </div> </div> <div class="sect2"> <h3 id="_ambientes">Ambientes</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">Ambiente</th> <th class="tableblock halign-left valign-top">uso</th> <th class="tableblock halign-left valign-top">Status aceito</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">Desenvolvimento e pré-visualização</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">rascunho, publicado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Encenação</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validação pré-produção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">publicado apenas</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">produção</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Site público</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">publicado apenas</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_extensibilidade">extensibilidade</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adição_de_novos_atributos">Adição de novos atributos</h3> <div class="paragraph"> <p>Para enriquecer o modelo de dados, simplesmente adicionar novos atributos prefixados`project-*`:</p> </div> <div class="ulist"> <ul> <li> <p><code>project-awards</code>: Prêmios e reconhecimentos</p> </li> <li> <p><code>project-testimonial</code>: Citação do cliente</p> </li> <li> <p><code>project-team-size</code>: Tamanho da equipe</p> </li> <li> <p>`project-budget-range`faixa orçamentária</p> </li> </ul> </div> <div class="paragraph"> <p>Estes atributos ficam automaticamente disponíveis nos templates sem modificação no motor JBake.</p> </div> </div> <div class="sect2"> <h3 id="_categorização_avançada">Categorização avançada</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b98c4bec6882f5ef3e74ce4f202dd934.png" alt="Diagram" width="561" height="259"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_boas_práticas">Boas Práticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_organização_dos_arquivos">Organização dos arquivos</h3> <div class="ulist"> <ul> <li> <p><strong>Um arquivo = um projeto</strong> : evitar misturar vários projetos</p> </li> <li> <p><strong>Imagens na pasta dedicada</strong> :`assets/img/portfolio/nom-projet/`</p> </li> <li> <p><strong>Nomenclatura consistente</strong> : facilita pesquisa e manutenção</p> </li> <li> <p><strong>Versioning Git</strong> : rastreamento completo das modificações</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_gestão_de_conteúdo">Gestão de conteúdo</h3> <div class="ulist"> <ul> <li> <p><strong>Status de rascunho padrão</strong> : publicar somente quando pronto</p> </li> <li> <p><strong>Revisão pré-publicação</strong> : validação de qualidade e confidencialidade</p> </li> <li> <p>Metadados completos : preencher todos os campos pertinentes</p> </li> <li> <p><strong>Conteúdo narrativo rico</strong> : não se limitar aos metadados</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_desempenho">Desempenho</h3> <div class="ulist"> <ul> <li> <p><strong>Otimizar imagens</strong> : compressão antes do commit</p> </li> <li> <p><strong>Pagination se necessário</strong> : se >20 projetos</p> </li> <li> <p><strong>Lazy loading</strong> : imagens das galerias carregadas sob demanda</p> </li> <li> <p><strong>Cache do navegador</strong> : cabeçalhos apropriados para assets</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta arquitetura permite :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Simplicidade de uso</strong> : adicionar um projeto = criar um arquivo de texto</p> </li> <li> <p><strong>Flexibilidade</strong> : extensível via novos atributos</p> </li> <li> <p><strong>Manutenabilidade</strong> : separação conteúdo/apresentação</p> </li> <li> <p><strong>Rastreabilidade</strong> : versionamento Git completo</p> </li> <li> <p><strong>Automação</strong> : build e implantação contínua possível</p> </li> </ul> </div> <div class="paragraph"> <p>A escolha do AsciiDoc garante a coerência com o resto do site, oferecendo ao mesmo tempo a riqueza dos metadados necessários a um portfólio profissional.</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">tempo de leitura : 12 minutes</div> <p>Em vez de escolher entre a simplicidade do Supabase e a potência do Spring Boot, por que não combinar os dois? Descubra uma arquitetura híbrida que aproveite o melhor de cada tecnologia.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>(Note: No characters)</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_falso_dilema_da_arquitetura_moderna">O Falso Dilema da Arquitetura Moderna</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando se constrói uma aplicação moderna com um frontend estático, muitas vezes nos deparamos com uma escolha binária:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Apostar tudo numa solução Backend-as-a-Service</strong>(Supabase, Firebase) - simples mas limitada</p> </li> <li> <p><strong>Construir um backend completo</strong>(Spring Boot, Node.js) - poderoso mas complexo</p> </li> </ul> </div> <div class="paragraph"> <p>Esta escolha é um falso dilema. A arquitetura híbrida propõe um terceiro caminho: <strong>usar cada tecnologia onde ela se destaca</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_visão_arquitetural">Visão arquitetural</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_arquitetura_tradicional_monolítica">A Arquitetura Tradicional: Monolítica</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1738" height="5652"> </div> </div> <div class="paragraph"> <p>Nessa abordagem, mesmo as operações mais simples (leitura de um artigo, criação de um comentário) devem passar pelo seu backend. Você paga o custo da complexidade desde o primeiro dia.</p> </div> </div> <div class="sect2"> <h3 id="_a_arquitetura_baas_todo_delegado">A Arquitetura 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>Do outro lado, delegar tudo a um BaaS é sedutor no início, mas mostra rapidamente seus limites assim que a lógica de negócio se complexifica.</p> </div> </div> <div class="sect2"> <h3 id="_a_arquitetura_híbrida_separação_das_responsabilidades">A Arquitetura Híbrida : Separação das Responsabilidades</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1747" height="5760"> </div> </div> <div class="paragraph"> <p>A arquitetura híbrida separa claramente as responsabilidades de acordo com a complexidade e a natureza das operações.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_princípios_de_design">Princípios de Design</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_princípio_1_começar_simples_evoluir_inteligentemente">Princípio 1 : Começar Simples, Evoluir Inteligentemente</h3> <div class="imageblock"> <div class="content"> <img src="evolution-phases.svg" alt="evolution phases" width="458" height="392"> </div> </div> <div class="paragraph"> <p><strong>Não construa o Spring Boot se você não precisar dele.</strong>Comece com o Supabase, adicione o Spring Boot quando a complexidade o justificar.</p> </div> </div> <div class="sect2"> <h3 id="_princípio_2_separação_por_natureza_da_operação">Princípio 2: Separação por natureza da operação</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="_princípio_3_uma_única_fonte_de_verdade">Princípio 3: Uma Única Fonte de Verdade</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1752" height="5700"> </div> </div> <div class="paragraph"> <p>Ao compartilhar a mesma instância PostgreSQL, Supabase e Spring Boot trabalham nos mesmos dados sem sincronização complexa.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orquestração_dos_fluxos">Orquestração dos Fluxos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flux_1_autenticação_centralizada">Flux 1 : Autenticação Centralizada</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1078" height="950"> </div> </div> <div class="paragraph"> <p><strong>Ponto-chave</strong>Um único processo de autenticação, um único JWT, utilizável em qualquer lugar.</p> </div> </div> <div class="sect2"> <h3 id="_fluxo_2_orquestração_de_um_processo_de_negócio_complexo">Fluxo 2 : Orquestração de um Processo de Negócio Complexo</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1197" height="990"> </div> </div> <div class="paragraph"> <p><strong>O que o Spring Boot traz</strong>Orquestração fiável de processos complexos envolvendo vários sistemas com garantia transacional.</p> </div> </div> <div class="sect2"> <h3 id="_flux_3_jobs_agendados_e_sincronizações">Flux 3 : Jobs Agendados e Sincronizações</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE participant "Escalonador ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE participant "Escalonador (Spring Boot)" as scheduler participant "Serviço de relatório" as report participant "PostgreSQL" as db participant "API externa" as api participant "Serviço de e-mail" 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>O que o Spring Boot traz</strong>: Trabalhos agendados confiáveis com gerenciamento de estado, nova tentativa automática e execução garantida</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matriz_de_decisão">Matriz de Decisão</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_quando_usar_supabase">Quando 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="_quando_usar_o_spring_boot">Quando usar o 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="_exemplos_de_arquitetura_por_tipo_de_projeto">Exemplos de Arquitetura por Tipo de Projeto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portfólio">Blog / Portfólio</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 amplamente.</p> </div> </div> <div class="sect2"> <h3 id="_aplicação_saas">Aplicação SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1773" height="5748"> </div> </div> <div class="paragraph"> <p><strong>veredicto</strong>: Arquitetura híbrida necessária. Supabase para o essencial, Spring Boot para a parte crítica (pagamentos, faturamento).</p> </div> </div> <div class="sect2"> <h3 id="_e_comércio">e-comércio</h3> <div class="imageblock"> <div class="content"> <img src="ecommerce-architecture.svg" alt="ecommerce architecture" width="1747" height="5748"> </div> </div> <div class="paragraph"> <p><strong>veredicto</strong>: Spring Boot indispensável. Supabase apenas para auth e catálogo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estratégia_de_migração_progressiva">Estratégia de Migração Progressiva</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="_custos_e_considerações_operacionais">Custos e Considerações Operacionais</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrutura_dos_custos">Estrutura dos custos</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 13) ] @startuml skinparam backgroundColor #FEFEFE package "Custos Mensais Estimados" { rectangle "Fase MVP\n(0-1000 utilizadores)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase Crescimento ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE package "Custos Mensais Estimados" { rectangle "Fase MVP\n(0-1000 utilizadores)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase Crescimento (1k-10k usuários)" #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 Escala (10k-100k utilizadores)" #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 Escala (10k-100k utilizadores)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilidades_operacionais">Responsabilidades Operacionais</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1787" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_equilíbrio_perfeito">Conclusão : O Equilíbrio Perfeito</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida Supabase + Spring Boot não é um compromisso, é uma<strong>sinergia</strong>.</p> </div> <div class="sect2"> <h3 id="_os_princípios_a_reter">Os Princípios a Reter</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="_quando_escolher_esta_arquitetura">Quando escolher esta arquitetura?</h3> <div class="paragraph"> <p><strong>�✅ Esta arquitetura é ideal se:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Você quer começar rapidamente (MVP em dias, não em meses)</p> </li> <li> <p>Você antecipa um aumento da complexidade do negócio</p> </li> <li> <p>Você quer minimizar os custos iniciais</p> </li> <li> <p>Você gosta do PostgreSQL e quer uma fonte de verdade única</p> </li> <li> <p>Você aprecia Kotlin e as coroutines para o código de negócios</p> </li> <li> <p>Você quer evitar o vendor lock-in total</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Esta arquitetura NÃO é adequada se :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Seu projeto é simples e permanecerá simples (blog pessoal → 100% Supabase basta)</p> </li> <li> <p>Você já tem uma stack de backend estabelecida que você domina</p> </li> <li> <p>Você prefere um monolito tradicional</p> </li> <li> <p>Você precisa de .NET, Python ou outra linguagem de backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_visão_geral_final">Visão Geral 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 "Arquitetura Híbrida Completa" { actor "Usuários" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend Simples (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negócio (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 "Arquitetura Híbrida Completa" { actor "Usuários" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend Simples (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de negócio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL Fonte única de verdade" 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="_o_melhor_dos_dois_mundos">O Melhor dos Dois Mundos</h3> <div class="paragraph"> <p>Esta arquitetura lhe dá :</p> </div> <div class="paragraph"> <p><strong>🚀 A Velocidade do Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Início em horas, não em semanas</p> </li> <li> <p>Autenticação OAuth2 em poucos cliques</p> </li> <li> <p>APIs REST geradas automaticamente</p> </li> <li> <p>Configuração zero do servidor</p> </li> </ul> </div> <div class="paragraph"> <p><strong>A Potência do Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin e Corrotinas para código assíncrono elegante</p> </li> <li> <p>Orquestração de processos de negócios complexos</p> </li> <li> <p>Trabalhos agendados fiáveis</p> </li> <li> <p>Transações ACID garantidas</p> </li> <li> <p>Ecossistema Spring completo</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💰 A economia progressiva</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ para iniciar e validar</p> </li> <li> <p>Custos que acompanham o crescimento</p> </li> <li> <p>Sem sobreengenharia prematura</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�🎯 Flexibilidade Arquitetural</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migração progressiva sem reestruturação</p> </li> <li> <p>Adição do Spring Boot apenas se necessário</p> </li> <li> <p>Sem vendor lock-in total</p> </li> <li> <p>Arquitetura evolutiva</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_mais_longe">Para Ir Mais Longe</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recursos_técnicos">Recursos Técnicos</h3> <div class="paragraph"> <p><strong>Documentação Supabase:</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guia de Autenticação</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Segurança em nível de linha</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">APIs geradas automaticamente</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentação Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot com Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">Corrotinas e 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>Artigos Complementares:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Segurança das APIs com JWT</p> </li> <li> <p>Otimização do desempenho do PostgreSQL</p> </li> <li> <p>Padrões de migração progressiva</p> </li> <li> <p>Gestão de erros em arquitetura distribuída</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_casos_de_uso_reais">Casos de uso reais</h3> <div class="paragraph"> <p>Esta arquitetura híbrida é utilizada com sucesso em:</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong>: Autenticação Supabase, faturação Spring Boot</p> </li> <li> <p><strong>Mercados</strong>: Catálogo Supabase, transações Spring Boot</p> </li> <li> <p><strong>Plataformas de conteúdo</strong>: Artigos Supabase, analytics Spring Boot</p> </li> <li> <p><strong>Ferramentas internas</strong>: CRUD Supabase, fluxos de trabalho Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_checklist_de_inicialização">Checklist de inicialização</h3> <div class="paragraph"> <p><strong>Fase 1 - Fundações (Semana 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Criar conta Supabase - [ ] Configurar projeto PostgreSQL - [ ] Ativar Auth (Google, GitHub) - [ ] Definir esquema inicial - [ ] Configurar Row Level Security Testar APIs desde o 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 principais - [ ] Integrar autenticação OAuth2 - [ ] Criar formulários CRUD - [ ] Configurar armazenamento para arquivos - [ ] Implantar no GitHub Pages - [ ] Testar em condições reais</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fase 3 - Evolução (Conforme necessidades)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identificar necessidades de lógica complexa - [ ] Criar projeto Spring Boot se necessário - [ ] Configurar validação JWT Supabase - [ ] Conectar ao PostgreSQL Supabase - [ ] Migrar funcionalidades complexas - [ ] Implementar trabalhos programados - [ ] Implantar Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_anti_padrões_a_evitar">Anti-padrões a evitar</h3> <div class="paragraph"> <p><strong>�❌ Não fazer :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Duplicar os dados entre Supabase e Spring Boot</p> </li> <li> <p>Criar duas bases PostgreSQL separadas</p> </li> <li> <p>Codificar a autenticação você mesmo</p> </li> <li> <p>Usar o Spring Boot para um CRUD simples</p> </li> <li> <p>Exagerar na arquitetura desde o início</p> </li> <li> <p>Ignorar o Row Level Security do Supabase</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�✅ Fazer melhor:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Compartilhar uma única base PostgreSQL</p> </li> <li> <p>Deixar o Supabase gerenciar a autenticação</p> </li> <li> <p>Usar Spring Boot apenas para a complexidade</p> </li> <li> <p>Começar simples, evoluir progressivamente</p> </li> <li> <p>Explorar as forças de cada tecnologia</p> </li> <li> <p>Proteger com RLS no nível da base de dados</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_de_evolução">Perspectivas de Evolução</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adição_de_novas_capacidades">Adição de Novas Capacidades</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1806" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_escala_horizontal">escala horizontal</h3> <div class="paragraph"> <p>Quando seu aplicativo cresce, a arquitetura híbrida escala naturalmente :</p> </div> <div class="paragraph"> <p><strong>Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Escala automaticamente até milhões de operações</p> </li> <li> <p>Réplicas de leitura para desempenho de leitura</p> </li> <li> <p>Recuperação em um ponto no tempo para segurança</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Múltiplas instâncias atrás do balanceador de carga</p> </li> <li> <p>Design sem estado facilita o escalonamento horizontal</p> </li> <li> <p>Kubernetes para orquestração, se necessário</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Particionamento para tabelas voluminosas</p> </li> <li> <p>Pooling de conexões (PgBouncer)</p> </li> <li> <p>Sharding realmente necessário (raro)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_testemunhos_arquitetônicos">Testemunhos Arquitetônicos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_usuários">Startup SaaS (50k usuários)</h3> <div class="paragraph"> <p><em><em>_ Começamos com 100% Supabase. Com 5k usuários, adicionamos o Spring Boot apenas para a faturação Stripe e os relatórios mensais. Um ano depois, 80% das nossas operações ainda passam pelo Supabase. O Spring Boot gerencia apenas a parte crítica. Esta separação nos permitiu escalar sem refatoração. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_plataforma_e_learning_10k_utilizadores">Plataforma E-learning (10k utilizadores)</h3> <div class="paragraph"> <p><em><em>_ A autenticação OAuth2 do Supabase nos fez economizar 3 semanas de desenvolvimento. As APIs auto-geradas gerenciam todo o nosso catálogo de cursos. O Spring Boot serve apenas para os certificados PDF e os e-mails de progresso. Arquitetura simples, manutenível e escalável. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_marketplace_b2b_3k_utilizadores">Marketplace B2B (3k utilizadores)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot gerencia as transações entre compradores e vendedores (crítico). Supabase cuida de tudo o resto: perfis, mensagens em tempo real, documentos. O fato de eles compartilharem a mesma base PostgreSQL nos evita qualquer sincronização complexa. Melhor escolha arquitetural que já fizemos. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntese_um_paradigma_arquitetural_moderno">Síntese: Um paradigma arquitetural moderno</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida Supabase + Spring Boot representa um novo paradigma:<strong>a especialização arquitetô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 Antigo" #LightCoral { card "Tudo no Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Novo Paradigma" #LightGreen { card "Supabase ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "Paradigma Antigo" #LightCoral { card "Tudo no Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Novo Paradigma" #LightGreen { card "Supabase (Conveniência)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (Diferenciação)" { [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>O princípio fondamental :</strong>Não construa o que já existe na forma de serviço. Concentre-se no que diferencia sua aplicação.</p> </div> <div class="sect2"> <h3 id="_a_regra_dos_8020">A Regra dos 80/20</h3> <div class="paragraph"> <p>Na maioria das aplicações :</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% das operações</strong>São CRUD padrão → Supabase</p> </li> <li> <p><strong>20 % das operações</strong>requerem lógica de negócio → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>Esta regra natural justifica a arquitetura 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="_conclusão_final">Conclusão Final</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida não é um compromisso técnico, é uma<strong>decisão estratégica</strong>.</p> </div> <div class="paragraph"> <p><strong>Ela permite que você :</strong></p> </div> <div class="ulist"> <ul> <li> <p>�✅ Começar rapidamente com um MVP funcional</p> </li> <li> <p>�✅ Validar seu mercado sem investimento pesado</p> </li> <li> <p>Evoluir gradualmente quando a complexidade o exige</p> </li> <li> <p>�✅ Domine seus custos em cada etapa</p> </li> <li> <p>�✅ Aproveitar o melhor de cada tecnologia</p> </li> <li> <p>Evitar o over-engineering prematuro</p> </li> <li> <p>✅ Manter a flexibilidade para o futuro</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Ela representa :</strong></p> </div> <div class="ulist"> <ul> <li> <p>�🎯<strong>pragmatismo</strong>: Cada tecnologia onde ela se destaca</p> </li> <li> <p>🚀<strong>Velocidade</strong>: Tempo de lançamento mínimo</p> </li> <li> <p>�💰<strong>economia</strong>: Custos alinhados ao valor</p> </li> <li> <p>�🔮<strong>Escalabilidade</strong>: Arquitetura que cresce com você</p> </li> <li> <p>🛡️<strong>robustez</strong>: Serviços comprovados e confiáveis</p> </li> </ul> </div> <div class="sect2"> <h3 id="_seu_próximo_passo">Seu Próximo Passo</h3> <div class="paragraph"> <p>Se esta arquitetura fala com você, aqui está por onde começar :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Crie uma conta Supabase</strong>(gratuito)</p> </li> <li> <p><strong>Defina seu esquema de dados mínimo</strong></p> </li> <li> <p><strong>Configure a autenticação OAuth2</strong></p> </li> <li> <p><strong>Crie sua primeira página JBake que consome a API</strong></p> </li> <li> <p><strong>Implante no GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Você terá um MVP funcional em<strong>alguns dias</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot virá naturalmente quando você precisar. Não antes.</p> </div> <hr> <div class="paragraph"> <p><strong>A arquitetura híbrida é a arte de construir exatamente o que é preciso, quando preciso.</strong></p> </div> <div class="paragraph"> <p><em>Bom desenvolvimento! 🚀</em></p> </div> <hr> <div class="paragraph"> <p><em>Compartilhe este artigo se você pensar que pode ajudar outros desenvolvedores a fazer as boas escolhas arquitetônicas.</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">tempo de leitura : 12 minutes</div> <p>Em vez de escolher entre a simplicidade do Supabase e a potência do Spring Boot, por que não combinar os dois? Descubra uma arquitetura híbrida que aproveita o melhor de cada tecnologia.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_o_falso_dilema_da_arquitetura_moderna">O Falso Dilema da Arquitetura Moderna</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ao construir uma aplicação moderna com um frontend estático, frequentemente nos deparamos com uma escolha binária:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Apostar tudo numa solução Backend-as-a-Service</strong>(Supabase, Firebase) - simples mas limitada</p> </li> <li> <p><strong>Construir um backend completo</strong>(Spring Boot, Node.js) - poderoso mas complexo</p> </li> </ul> </div> <div class="paragraph"> <p>Esta escolha é um falso dilema. A arquitetura híbrida propõe um terceiro caminho: <strong>utilizar cada tecnologia onde ela se destaca</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_visão_arquitetônica">Visão Arquitetônica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_arquitetura_tradicional_monolítica">A Arquitetura Tradicional : Monolítica</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1746" height="5652"> </div> </div> <div class="paragraph"> <p>Nessa abordagem, até mesmo as operações mais simples (leitura de um artigo, criação de um comentário) precisam passar pelo seu backend. Você paga o custo da complexidade desde o primeiro dia.</p> </div> </div> <div class="sect2"> <h3 id="_a_arquitetura_baas_todo_delegado">A Arquitetura 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>Do contrário, delegar tudo a um BaaS é sedutor no início, mas mostra rapidamente seus limites assim que a lógica de negócios se complexifica.</p> </div> </div> <div class="sect2"> <h3 id="_a_arquitetura_híbrida_separação_das_responsabilidades">A Arquitetura Híbrida : Separação das Responsabilidades</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1742" height="5760"> </div> </div> <div class="paragraph"> <p>A arquitetura híbrida separa claramente as responsabilidades de acordo com a complexidade e a natureza das operações.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_princípios_de_design">Princípios de Design</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_princípio_1_começar_simples_evoluir_inteligentemente">Princípio 1 : Começar Simples, Evoluir Inteligentemente</h3> <div class="imageblock"> <div class="content"> <img src="evolution-phases.svg" alt="evolution phases" width="458" height="392"> </div> </div> <div class="paragraph"> <p><strong>Não construa o Spring Boot se você não precisar.</strong>Comece com o Supabase, adicione o Spring Boot quando a complexidade justificar.</p> </div> </div> <div class="sect2"> <h3 id="_princípio_2_separação_por_natureza_da_operação">Princípio 2: Separação por natureza da operação</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="_princípio_3_uma_única_fonte_de_verdade">Princípio 3 : Uma Única Fonte de Verdade</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1769" height="5700"> </div> </div> <div class="paragraph"> <p>Ao compartilhar a mesma instância PostgreSQL, o Supabase e o Spring Boot trabalham nos mesmos dados sem sincronização complexa.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orquestração_dos_fluxos">Orquestração dos Fluxos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flux_1_autenticação_centralizada">Flux 1 : Autenticação Centralizada</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1085" height="950"> </div> </div> <div class="paragraph"> <p><strong>ponto-chave</strong>: Um único processo de autenticação, um único JWT, utilizável em qualquer lugar.</p> </div> </div> <div class="sect2"> <h3 id="_flux_2_orquestração_de_um_processo_de_negócio_complexo">Flux 2 : Orquestração de um Processo de Negócio Complexo</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1151" height="990"> </div> </div> <div class="paragraph"> <p><strong>O que o Spring Boot traz</strong>Orquestração fiável de processos complexos envolvendo vários sistemas com garantia transacional.</p> </div> </div> <div class="sect2"> <h3 id="_flux_3_trabalhos_agendados_e_sincronizações">Flux 3 : Trabalhos Agendados e Sincronizações</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE participant "Agendador ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE participant "Agendador (Spring Boot)" as scheduler participant "Serviço de Relatório" as report participant "PostgreSQL" as db participant "API externa" as api participant "Serviço de e‑mail" 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>O que o Spring Boot traz</strong>: Trabalhos agendados confiáveis com gerenciamento de estado, retry automático e execução garantida.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matriz_de_decisão">Matriz de Decisão</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_quando_usar_supabase">Quando 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="_quando_usar_o_spring_boot">Quando usar o 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="_exemplos_de_arquitetura_por_tipo_de_projeto">Exemplos de Arquitetura por Tipo de Projeto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portfólio">Blog / Portfólio</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 é mais que suficiente.</p> </div> </div> <div class="sect2"> <h3 id="_aplicação_saas">Aplicação SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1763" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Veredito</strong>: Arquitetura híbrida necessária. Supabase para o essencial, Spring Boot para a parte crítica (pagamentos, faturamento).</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="1751" height="5748"> </div> </div> <div class="paragraph"> <p><strong>veredicto</strong>: Spring Boot indispensável. Supabase para autenticação e catálogo apenas.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estratégia_de_migração_progressiva">Estratégia de Migração Progressiva</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="_custos_e_considerações_operacionais">Custos e Considerações Operacionais</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrutura_dos_custos">Estrutura dos Custos</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE package "Custos Mensais Estimados" { rectangle "Fase MVP (0-1000 usuários)" #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE package "Custos Mensais Estimados" { rectangle "Fase MVP (0-1000 usuários)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase de Crescimento\n(1k-10k utilizadores)" #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 da Fase (10k-100k usuários)" #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 da Fase (10k-100k usuários)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilidades_operacionais">Responsabilidades Operacionais</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1746" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_o_equilíbrio_perfeito">Conclusão: O Equilíbrio Perfeito</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida Supabase + Spring Boot não é um compromisso, é uma<strong>sinergia</strong>.</p> </div> <div class="sect2"> <h3 id="_os_princípios_a_reter">Os princípios a reter</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="_quando_escolher_esta_arquitetura">Quando escolher esta arquitetura?</h3> <div class="paragraph"> <p><strong>✅ Esta arquitetura é ideal se :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Você quer começar rapidamente (MVP em dias, não em meses)</p> </li> <li> <p>Você antecipa um crescimento da complexidade de negócio</p> </li> <li> <p>Você deseja minimizar os custos iniciais</p> </li> <li> <p>Você gosta de PostgreSQL e quer uma fonte de verdade única</p> </li> <li> <p>Você aprecia Kotlin e as Coroutines para o código de negócio</p> </li> <li> <p>Você quer evitar o vendor lock-in total</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Esta arquitetura NÃO é adequada se:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Seu projeto é simples e permanecerá assim (blog pessoal → 100% Supabase basta)</p> </li> <li> <p>Você já tem uma stack de backend estabelecida que você domina.</p> </li> <li> <p>Você prefere um monolito tradicional</p> </li> <li> <p>Você precisa de .NET, Python, ou outra linguagem do lado do backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_visão_geral_final">Visão Geral 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 "Arquitetura Híbrida Completa" { actor "Usuários" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend Simples (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de Negócio (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 "Arquitetura Híbrida Completa" { actor "Usuários" as users rectangle "Frontend (Estático)" #SkyBlue { [JBake / GitHub Pages] note right: Gratuit, CDN global } rectangle "Backend Simples (Supabase)" #LightGreen { [Auth OAuth2] [CRUD APIs] [Storage] [Realtime] note right Gratuit jusqu'à 50k users Zéro configuration serveur end note } rectangle "Backend de Negócio (Spring Boot)" #Coral { [Orchestration] [Jobs Planifiés] [Intégrations] [Transactions] note right Activé uniquement si nécessaire end note } database "PostgreSQL Fonte Única da Verdade" 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="_o_melhor_dos_dois_mundos">O Melhor dos Dois Mundos</h3> <div class="paragraph"> <p>Esta arquitetura lhe dá:</p> </div> <div class="paragraph"> <p><strong>🚀 A Velocidade do Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Início em horas, não em semanas</p> </li> <li> <p>Autenticação OAuth2 em poucos cliques</p> </li> <li> <p>APIs REST geradas automaticamente</p> </li> <li> <p>Zero configuração de servidor</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💪 O Poder do Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin e Coroutines para código assíncrono elegante</p> </li> <li> <p>Orquestração de processos de negócio complexos</p> </li> <li> <p>Jobs agendados confiáveis</p> </li> <li> <p>Transações ACID garantidas</p> </li> <li> <p>Ecossistema Spring completo</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 A Economia Progressiva</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ para iniciar e validar</p> </li> <li> <p>Custos que acompanham o crescimento</p> </li> <li> <p>Não há sobre-engenharia prematura</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�🎯 A Flexibilidade Arquitetônica</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migração progressiva sem reformulação</p> </li> <li> <p>Adicionar Spring Boot apenas se necessário</p> </li> <li> <p>Sem bloqueio total de fornecedor</p> </li> <li> <p>arquitetura evolutiva</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_mais_longe">Para Ir Mais Longe</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recursos_técnicos">Recursos Técnicos</h3> <div class="paragraph"> <p><strong>Documentação Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guia de Autenticação</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Segurança em nível de linha</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">APIs gerados automaticamente</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentação Spring Boot:</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot com Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">corrotinas e 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>Artigos Complementares:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Proteção das APIs com JWT</p> </li> <li> <p>Otimização de desempenho PostgreSQL</p> </li> <li> <p>Padrões de migração progressiva</p> </li> <li> <p>Gestão de erros em arquitetura distribuída</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_casos_de_uso_reais">Casos de Uso Reais</h3> <div class="paragraph"> <p>Esta arquitetura híbrida é utilizada com sucesso em :</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong>: Autenticação Supabase, faturamento Spring Boot</p> </li> <li> <p><strong>Mercados</strong>: Catálogo Supabase, transações Spring Boot</p> </li> <li> <p><strong>Plataformas de conteúdo</strong>: Artigos Supabase, analítica Spring Boot</p> </li> <li> <p><strong>Ferramentas internas</strong>: CRUD Supabase, fluxos de trabalho Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_checklist_de_partida">Checklist de partida</h3> <div class="paragraph"> <p><strong>Fase 1 - Fundações (Semana 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Criar conta Supabase - [ ] Configurar projeto PostgreSQL - [ ] Ativar Auth (Google, GitHub) - [ ] Definir esquema inicial - [ ] Configurar Row Level Security - [ ] Testar 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 principais - [ ] Integrar autenticação OAuth2 - [ ] Criar formulários CRUD - [ ] Configurar Storage para arquivos - [ ] Implantar no GitHub Pages - [ ] Testar em condições reais</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fase 3 - Evolução (Conforme as necessidades)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identificar necessidades de lógica complexa - [ ] Criar projeto Spring Boot se necessário - [ ] Configurar validação JWT Supabase - [ ] Conectar ao PostgreSQL Supabase - [ ] Migrar funcionalidades complexas - [ ] Implementar trabalhos agendados - [ ] Implementar Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_anti_padrões_a_evitar">Anti-Padrões a Evitar</h3> <div class="paragraph"> <p><strong>�❌ Não fazer:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Duplicar os dados entre Supabase e Spring Boot</p> </li> <li> <p>Criar duas bases PostgreSQL separadas</p> </li> <li> <p>Codifique a autenticação você mesmo</p> </li> <li> <p>Utilizar Spring Boot para CRUD simples</p> </li> <li> <p>Sobre-arquitetar desde o início</p> </li> <li> <p>Ignorar a Segurança de Nível de Linha do Supabase</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fazer de preferência :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Compartilhar um único banco de dados PostgreSQL</p> </li> <li> <p>Deixe o Supabase gerenciar a autenticação</p> </li> <li> <p>Usar o Spring Boot apenas pela complexidade</p> </li> <li> <p>Começar simples, evoluir gradualmente</p> </li> <li> <p>Aproveitar as forças de cada tecnologia</p> </li> <li> <p>Proteger com RLS no nível da base de dados</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perspectivas_de_evolução">Perspectivas de Evolução</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adição_de_novas_capacidades">Adição de Novas Capacidades</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1773" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_escalonamento_horizontal">Escalonamento Horizontal</h3> <div class="paragraph"> <p>Quando seu aplicativo cresce, a arquitetura híbrida escala naturalmente:</p> </div> <div class="paragraph"> <p><strong>Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Escala automaticamente até milhões de operações</p> </li> <li> <p>Réplicas de leitura para desempenho de leitura</p> </li> <li> <p>Point-in-time recovery para segurança</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Múltiplas instâncias atrás do load balancer</p> </li> <li> <p>O design stateless facilita o escalonamento horizontal</p> </li> <li> <p>Kubernetes para orquestração se necessário</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Particionamento para tabelas volumosas</p> </li> <li> <p>Pooling de conexões (PgBouncer)</p> </li> <li> <p>Sharding é realmente necessário (raro)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_testemunhos_arquitetônicos">Testemunhos Arquitetônicos</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_utilizadores">Startup SaaS (50k utilizadores)</h3> <div class="paragraph"> <p><em><em>_ Começamos 100% Supabase. Aos 5k usuários, adicionamos Spring Boot apenas para a cobrança Stripe e os relatórios mensais. Um ano depois, 80% das nossas operações ainda passam pelo Supabase. Spring Boot cuida apenas da parte crítica. Essa separação nos permitiu escalar sem reformulação. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_plataforma_e_learning_10k_usuários">Plataforma E-learning (10k usuários)</h3> <div class="paragraph"> <p><em><em>_ A autenticação OAuth2 da Supabase nos fez ganhar 3 semanas de desenvolvimento. As APIs auto-geradas gerenciam todo o nosso catálogo de cursos. Spring Boot serve apenas para os certificados PDF e os e-mails de progresso. Arquitetura simples, manutenível, escalável. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_marketplace_b2b_3k_utilizadores">Marketplace B2B (3k utilizadores)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot gere as transações entre compradores e vendedores (crítico). Supabase gere o resto: perfis, mensagens em tempo real, documentos. O fato de compartilharem o mesmo banco de dados PostgreSQL nos evita qualquer sincronização complexa. Melhor escolha arquitetônica que já fizemos. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_síntese_um_paradigma_arquitetônico_moderno">Síntese: Um Paradigma Arquitetônico Moderno</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida Supabase + Spring Boot representa um novo paradigma:<strong>especialização arquitetô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 Antigo" #LightCoral { card "Tudo no Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Novo Paradigma" #LightGreen { card "Supabase ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "Paradigma Antigo" #LightCoral { card "Tudo no Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Novo Paradigma" #LightGreen { card "Supabase (Conveniência)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (Diferenciação)" { [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>O princípio fundamental:</strong>Não construa o que já existe como serviço. Concentre-se no que diferencia sua aplicação.</p> </div> <div class="sect2"> <h3 id="_a_regra_dos_8020">A Regra dos 80/20</h3> <div class="paragraph"> <p>Na maioria das aplicações :</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% das operações</strong>são CRUD padrão → Supabase</p> </li> <li> <p><strong>20% das operações</strong>necessitam de lógica de negócio → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>Esta regra natural justifica a arquitetura híbrida.</p> </div> <div class="imageblock"> <div class="content"> <img src="8020-rule.svg" alt="8020 rule" width="1826" height="5652"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_final">Conclusão Final</h2> <div class="sectionbody"> <div class="paragraph"> <p>A arquitetura híbrida não é um compromisso técnico, é uma<strong>decisão estratégica</strong>.</p> </div> <div class="paragraph"> <p><strong>Ela permite que você:</strong></p> </div> <div class="ulist"> <ul> <li> <p>�✅ Comece rapidamente com um MVP funcional</p> </li> <li> <p>�✅ Validar seu mercado sem investimento pesado</p> </li> <li> <p>✅ Evoluir gradualmente quando a complexidade o exige</p> </li> <li> <p>Domine seus custos em cada etapa</p> </li> <li> <p>✅ Explorar o melhor de cada tecnologia</p> </li> <li> <p>�✅ Evitar a sobreengenharia prematura</p> </li> <li> <p>✅ Manter a flexibilidade para o futuro</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Ela representa :</strong></p> </div> <div class="ulist"> <ul> <li> <p>�🎯<strong>Pragmatismo</strong>: Cada tecnologia onde ela se destaca</p> </li> <li> <p>�🚀<strong>velocidade</strong>: Tempo de lançamento mínimo</p> </li> <li> <p>�💰<strong>Economia</strong>Custos alinhados ao valor</p> </li> <li> <p>�🔮<strong>Escalabilidade</strong>: Arquitetura que cresce com você</p> </li> <li> <p>�🛡️<strong>Robustez</strong>: Serviços testados e confiáveis</p> </li> </ul> </div> <div class="sect2"> <h3 id="_seu_próximo_passo">Seu Próximo Passo</h3> <div class="paragraph"> <p>Se essa arquitetura fala com você, aqui está por onde começar:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Crie uma conta Supabase</strong>(gratuito)</p> </li> <li> <p><strong>Defina seu esquema de dados mínimo</strong></p> </li> <li> <p><strong>Configure a autenticação OAuth2</strong></p> </li> <li> <p><strong>Crie sua primeira página JBake que consome a API</strong></p> </li> <li> <p><strong>Implante no GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Você terá um MVP funcional em<strong>alguns dias</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot virá naturalmente quando você precisar. Não antes.</p> </div> <hr> <div class="paragraph"> <p><strong>A arquitetura híbrida é a arte de construir exatamente o que é necessário, quando é necessário.</strong></p> </div> <div class="paragraph"> <p>Bom desenvolvimento! 🚀</p> </div> <hr> <div class="paragraph"> <p><em>Compartilhe este artigo se você pensar que pode ajudar outros desenvolvedores a fazer as boas escolhas arquitetônicas.</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="#_resumo">resumo</a></li> <li><a href="#_o_problema_essa_maldita_piscagem_do_tema">O Problema: Essa Maldita Piscagem do Tema</a> <ul class="sectlevel2"> <li><a href="#_um_pesadelo_para_a_experiência_do_usuário">Um pesadelo para a experiência do usuário</a></li> <li><a href="#_o_fouc_um_problema_antigo_da_web">O FOUC: Um problema antigo da web</a></li> <li><a href="#_impacto_na_percepção_de_qualidade">Impacto na Percepção de Qualidade</a></li> <li><a href="#_análise_técnica_do_problema">Análise Técnica do Problema</a></li> </ul> </li> <li><a href="#_por_que_um_script_clássico_não_é_suficiente">Por que um script clássico não é suficiente?</a> <ul class="sectlevel2"> <li><a href="#_a_abordagem_intuitiva_mas_ineficaz">A Abordagem Intuitiva mas Ineficaz</a></li> <li><a href="#_entender_o_evento_domcontentloaded">Entender o evento DOMContentLoaded</a></li> <li><a href="#_o_problema_do_render_blocking">O Problema do Render Blocking</a></li> <li><a href="#_visualização_do_problema">Visualização do Problema</a></li> <li><a href="#_as_tentativas_de_solução_ineficazes">As tentativas de solução ineficazes</a></li> <li><a href="#_a_verdadeira_solução_agir_mais_cedo">A Verdadeira Solução: Agir Mais Cedo</a></li> </ul> </li> <li><a href="#_a_solução_o_carregamento_précoce_early_loading">A Solução: O Carregamento Précoce (Early Loading)</a> <ul class="sectlevel2"> <li><a href="#_o_princípio_fundamental">O Princípio Fundamental</a></li> <li><a href="#_por_que_o_head_é_o_local_ideal">Por que o <code><head></code> é o Local Ideal</a></li> <li><a href="#_arquitetura_da_solução_em_três_camadas">Arquitetura da Solução em Três Camadas</a></li> </ul> </li> <li><a href="#_etapa_1_salvar_a_escolha_do_usuário">Etapa 1 : Salvar a Escolha do Usuário</a> <ul class="sectlevel2"> <li><a href="#_o_localstorage_sua_memória_persistente">O localStorage: Sua Memória Persistente</a></li> <li><a href="#_implementação_da_cópia_de_segurança_do_tema">Implementação da Cópia de Segurança do Tema</a></li> <li><a href="#_gerenciamento_dos_casos_de_erro">Gerenciamento dos Casos de Erro</a></li> <li><a href="#_estratégias_avançadas_de_persistência">Estratégias Avançadas de Persistência</a></li> </ul> </li> <li><a href="#_etapa_2_o_script_de_pré_carregamento_no_head">Etapa 2: O Script de Pré-carregamento no `<head></a> <ul class="sectlevel2"> <li><a href="#_o_coração_da_solução">O Coração da Solução</a></li> <li><a href="#_anatomia_do_script_cada_linha_conta">Anatomia do Script: Cada Linha Conta</a></li> <li><a href="#_detecção_da_preferência_do_sistema_bônus">Detecção da Preferência do Sistema (Bônus)</a></li> <li><a href="#_desempenho_por_que_este_script_é_rápido">Desempenho: Por que este script é rápido</a></li> <li><a href="#_colocação_óptima_no_head">Colocação Óptima no `<head></a></li> </ul> </li> <li><a href="#_passo_3_o_poder_dos_seletores_de_atributos_css">Passo 3 : O Poder dos Seletores de Atributos CSS</a> <ul class="sectlevel2"> <li><a href="#_o_sistema_de_tema_do_bootstrap_5">O sistema de tema do Bootstrap 5</a></li> <li><a href="#_estrutura_css_para_um_sistema_de_tema">Estrutura CSS para um Sistema de Tema</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_resumo">resumo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Neste artigo técnico aprofundado, exploramos como implementar um seletor de tema (light/dark) sem o incômodo efeito de piscar que ocorre durante o carregamento da página. Analisamos em detalhe o ciclo de renderização do navegador, as causas profundas do FOUC (Flash of Unstyled Content) e propomos uma solução robusta baseada na pré-carregamento síncrono no`<head>`. Esta técnica garante uma experiência de usuário fluida e profissional.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_essa_maldita_piscagem_do_tema">O Problema: Essa Maldita Piscagem do Tema</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_um_pesadelo_para_a_experiência_do_usuário">Um pesadelo para a experiência do usuário</h3> <div class="paragraph"> <p>Imagine a cena: você passou horas projetando um belo tema escuro para o seu aplicativo web. As cores estão perfeitamente equilibradas, o contraste é ótimo e seus usuários adoram essa opção. Mas há um problema constrangedor: a cada recarregamento da página, durante uma fração de segundo, o tema claro padrão aparece antes que o tema escuro assuma o controle.</p> </div> <div class="paragraph"> <p>Esse 'flash' visual, embora breve (às vezes menos de 100ms), é imediatamente perceptível pelo olho humano e cria uma experiência desagradável. Para os usuários que escolheram o tema escuro por razões de conforto visual ou de acessibilidade, esse piscar pode até ser doloroso, especialmente em um ambiente pouco iluminado.</p> </div> </div> <div class="sect2"> <h3 id="_o_fouc_um_problema_antigo_da_web">O FOUC: Um problema antigo da web</h3> <div class="paragraph"> <p>Esse fenômeno é uma variante do que se chama "Flash of Unstyled Content" (FOUC), um problema clássico do desenvolvimento web que remonta aos primeiros dias do CSS. O FOUC ocorre quando o navegador exibe temporariamente conteúdo HTML sem os estilos CSS aplicados, criando um flash de conteúdo não estilizado.</p> </div> <div class="paragraph"> <p>No nosso caso específico, não estamos a falar de um conteúdo completamente não estilizado, mas sim de um<strong>Flash do Tema Errado</strong>(FOWT) - o conteúdo está estilizado, mas com o tema errado. Isso é particularmente frustrante porque isso mostra que nosso aplicativo "esquece" a preferência do usuário a cada carregamento de página.</p> </div> </div> <div class="sect2"> <h3 id="_impacto_na_percepção_de_qualidade">Impacto na Percepção de Qualidade</h3> <div class="paragraph"> <p>Este problema, embora técnico, tem repercussões importantes na percepção da qualidade do seu aplicativo:</p> </div> <div class="paragraph"> <p><strong>Falta de polish</strong>: O piscar dá a impressão de uma aplicação inacabada ou mal otimizada. Os utilizadores associam frequentemente estes pequenos defeitos visuais a uma falta geral de profissionalismo.</p> </div> <div class="paragraph"> <p><strong>Ruptura de coerência</strong>: O aplicativo parece 'esquecer' as preferências do usuário, criando uma sensação de desincronização entre a interface e as expectativas.</p> </div> <div class="paragraph"> <p><strong>Fadiga visual</strong>Para os usuários sensíveis à luz ou que sofrem de enxaqueca, esse flash luminoso pode ser mais do que um simples incômodo estético.</p> </div> <div class="paragraph"> <p><strong>Desempenho percebido</strong>Ironicamente, mesmo que seu site carrega rapidamente, essa piscada pode dar a impressão de uma aplicação lenta ou pouco responsiva.</p> </div> </div> <div class="sect2"> <h3 id="_análise_técnica_do_problema">Análise Técnica do Problema</h3> <div class="paragraph"> <p>Para entender como resolver esse problema, é preciso primeiro entender por que ele ocorre. O piscar ocorre devido a um atraso temporal entre três eventos críticos no ciclo de vida de uma página web:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>O parsing inicial do HTML</strong>: O navegador lê e analisa a estrutura da sua página</p> </li> <li> <p><strong>A aplicação dos estilos CSS</strong>: O navegador aplica as regras CSS e calcula a renderização visual</p> </li> <li> <p><strong>A execução do JavaScript</strong>: Seu código que altera o tema está sendo executado</p> </li> </ol> </div> <div class="paragraph"> <p>O problema ocorre quando o evento nº3 (execução do JavaScript) chega depois que o navegador já começou ou terminou o evento nº2 (aplicação dos estilos). Nesse momento, o navegador já tomou uma decisão sobre qual tema exibir, e seu código chega tarde demais para influenciá-lo antes da primeira renderização.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_um_script_clássico_não_é_suficiente">Por que um script clássico não é suficiente?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_abordagem_intuitiva_mas_ineficaz">A Abordagem Intuitiva mas Ineficaz</h3> <div class="paragraph"> <p>A abordagem mais natural para um desenvolvedor seria colocar um script ao final do nosso`<body>`que verifica o tema preferido do usuário e o aplica. Essa abordagem segue as melhores práticas tradicionais da web que recomendam carregar os scripts no final da página para não bloquear a renderização.</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>Esta abordagem parece lógica à primeira vista. Esperamos que o DOM esteja pronto, depois aplicamos o tema. Simples, não? Infelizmente, essa simplicidade esconde um defeito fundamental relacionado ao timing do ciclo de renderização do navegador.</p> </div> </div> <div class="sect2"> <h3 id="_entender_o_evento_domcontentloaded">Entender o evento DOMContentLoaded</h3> <div class="paragraph"> <p>O evento`DOMContentLoaded`é acionado quando o documento HTML inicial foi completamente carregado e analisado pelo navegador,<strong>sem esperar</strong>o fim do carregamento das folhas de estilo, das imagens e dos sub-quadros. É um ponto importante a entender.</p> </div> <div class="paragraph"> <p>Aqui está a sequência típica dos eventos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>O navegador começa a baixar o HTML</p> </li> <li> <p>Ele analisa o HTML conforme ele é recebido</p> </li> <li> <p>Ele descobre as tags`<link>`para as CSS e começa a baixá-las</p> </li> <li> <p>Ele descobre as tags`<script>`e os executa (conforme seu tipo e atributos)</p> </li> <li> <p>Ele constrói o DOM (Document Object Model)</p> </li> <li> <p><strong>O evento <code>DOMContentLoaded</code> é disparado</strong></p> </li> <li> <p>Ele continua a aplicar os estilos e a fazer o layout</p> </li> <li> <p>O primeiro paint (exibição) ocorre</p> </li> <li> <p>O evento`load`se dispara quando todos os recursos são carregados</p> </li> </ol> </div> <div class="paragraph"> <p>O problema? Entre a etapa 6 (DOMContentLoaded) e a etapa 8 (primeiro paint), o navegador já tomou decisões sobre como exibir a página. Se o seu script de alteração de tema for executado na etapa 6, já é tarde demais para evitar uma primeira exibição com os estilos padrão.</p> </div> </div> <div class="sect2"> <h3 id="_o_problema_do_render_blocking">O Problema do Render Blocking</h3> <div class="paragraph"> <p>Na verdade, o timing é ainda mais complexo. Os navegadores modernos utilizam técnicas de otimização sofisticadas para melhorar a performance percebida. Eles tentam fazer o primeiro paint (First Contentful Paint) o mais rápido possível para que o usuário veja algo na tela.</p> </div> <div class="paragraph"> <p>Os CSS são "render-blocking" por padrão, o que significa que o navegador espera ter baixado e analisado as folhas de estilo antes de fazer o primeiro paint. É lógico: não queremos exibir conteúdo não estilizado.</p> </div> <div class="paragraph"> <p>Mas aqui está a armadilha: quando o navegador aplica esses estilos CSS pela primeira vez, ele o faz com base no estado atual do DOM. Se o atributo`data-bs-theme`ainda não está definido na tag`<html>`, o navegador aplicará os estilos padrão (geralmente o tema claro).</p> </div> <div class="paragraph"> <p>Então, quando seu script é executado e altera esse atributo, o navegador deve :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Recalcular todos os estilos afetados por essa mudança</p> </li> <li> <p>Refazer o layout, se necessário</p> </li> <li> <p>Repintar os elementos afetados</p> </li> </ol> </div> <div class="paragraph"> <p>Este processo de recálculo e de repintura é o que causa o piscar visível.</p> </div> </div> <div class="sect2"> <h3 id="_visualização_do_problema">Visualização do Problema</h3> <div class="paragraph"> <p>Para melhor compreender esta sequência problemática, vamos examinar um diagrama de sequência detalhado:</p> </div> <div id="diag-flux-incorrect" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 27) ] @startuml actor Utilisateur participant Navigateur participant "Analisador HTML" as Parser participant "Modelo de Objeto CSS" as CSS participant "Script.js (fim do body)" as Script participant "Motor de renderização" 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=""nota direita: Tema padrão (claro) Render -> Navegador: Primeira pintura (Tema Claro) nota direita: O usuário vê o tema claro ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Utilisateur participant Navigateur participant "Analisador HTML" as Parser participant "Modelo de Objeto CSS" as CSS participant "Script.js (fim do body)" as Script participant "Motor de renderização" 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=""nota direita: Tema padrão (claro) Render -> Navegador: Primeira pintura (Tema Claro) nota direita: O usuário vê o tema claro desativar Render Navegador -> Script: Executa o script ativar Script Script -> Script: Lê localStorage Script -> Navegador: setAttribute('data-bs-theme', 'dark') desativar Script ativar Render Render -> Render: Recalcular os estilos com 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 o problema : a primeira pintura ocorre antes que nosso script tenha tido a oportunidade de definir o tema correto. A repintura subsequente cria a intermitência visível.</p> </div> </div> <div class="sect2"> <h3 id="_as_tentativas_de_solução_ineficazes">As tentativas de solução ineficazes</h3> <div class="paragraph"> <p>Várias abordagens foram tentadas para resolver esse problema, mas a maioria tem seus próprios inconvenientes:</p> </div> <div class="paragraph"> <p><strong>Abordagem 1 : Ocultar o conteúdo até o carregamento</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>Esta abordagem esconde todo o conteúdo até que o JavaScript defina o tema correto. O problema? Isso atrasa artificialmente a exibição do conteúdo, dando a impressão de um site mais lento. Além disso, se o JavaScript estiver desativado, o usuário não vê nada de todo!</p> </div> <div class="paragraph"> <p><strong>Abordagem 2: Usar um loader/spinner</strong></p> </div> <div class="paragraph"> <p>Semelhante à abordagem 1, mas com um spinner de carregamento. Isso mascara o problema, mas não melhora o desempenho real e adiciona um atraso percebido desnecessário.</p> </div> <div class="paragraph"> <p><strong>Abordagem 3: Padrão para tema escuro</strong></p> </div> <div class="paragraph"> <p>Alguns desenvolvedores definem o tema escuro como padrão no CSS. Isso evita o piscar para os usuários do tema escuro, mas cria o problema inverso para os usuários do tema claro!</p> </div> <div class="paragraph"> <p>Nenhuma dessas abordagens é satisfatória porque elas tratam o sintoma em vez da causa raiz do problema.</p> </div> </div> <div class="sect2"> <h3 id="_a_verdadeira_solução_agir_mais_cedo">A Verdadeira Solução: Agir Mais Cedo</h3> <div class="paragraph"> <p>A chave para resolver este problema é perceber que devemos definir o atributo`data-bs-theme` <strong>antes</strong>que o navegador não começa a aplicar os estilos CSS. Isso significa que nosso script deve ser executado mais cedo no ciclo de vida da página, e isso é exatamente o que vamos explorar na seção seguinte.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_o_carregamento_précoce_early_loading">A Solução: O Carregamento Précoce (Early Loading)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_princípio_fundamental">O Princípio Fundamental</h3> <div class="paragraph"> <p>A solução elegante para o nosso problema de piscar baseia-se num princípio simples mas poderoso :<strong>sincronizar o estado da aplicação com o processo de renderização do navegador</strong>. Em vez de esperar que a página seja carregada para definir o tema, devemos defini-lo<strong>durante</strong>o carregamento, mesmo antes de os estilos CSS serem aplicados.</p> </div> <div class="paragraph"> <p>Esta abordagem chama-se 'Early Loading' ou 'Synchronous Preloading' no jargão do desenvolvimento web. A ideia é executar nossa lógica de detecção de tema o mais cedo possível no ciclo de vida da página, idealmente na tag`<head>`, mesmo antes de o navegador começar a baixar os arquivos CSS.</p> </div> </div> <div class="sect2"> <h3 id="_por_que_o_head_é_o_local_ideal">Por que o <code><head></code> é o Local Ideal</h3> <div class="paragraph"> <p>Le `<head>`Um documento HTML é processado sequencialmente pelo navegador, de cima para baixo. Cada elemento é processado na ordem em que aparece. Essa característica é crucial para nossa solução.</p> </div> <div class="paragraph"> <p>Quando o navegador encontra uma tag`<script>`no`<head>`sem os atributos`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Interrompe o parsing do HTML</strong></p> </li> <li> <p><strong>Baixe o script</strong>(se externo) ou a cama (se inline)</p> </li> <li> <p><strong>Executa imediatamente o script</strong></p> </li> <li> <p><strong>retoma o parsing do HTML</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Este comportamento, frequentemente considerado um problema de desempenho (daí a recomendação habitual de colocar os scripts no final da página), torna-se nosso aliado neste caso específico. Ao posicionar nosso script de detecção de tema no início do`<head>`, nós garantimos que ele execute antes que o navegador encontre as etiquetas`<link>`das nossas folhas de estilo.</p> </div> </div> <div class="sect2"> <h3 id="_arquitetura_da_solução_em_três_camadas">Arquitetura da Solução em Três Camadas</h3> <div class="paragraph"> <p>Nossa solução completa é composta por três camadas interdependentes, cada uma desempenhando um papel específico:</p> </div> <div class="paragraph"> <p><strong>Camada 1 : Persistência (localStorage)</strong> Esta camada é responsável pela cópia de segurança e recuperação da escolha do utilizador entre as sessões.</p> </div> <div class="paragraph"> <p><strong>Camada 2 : Sincronização Precoce (Script embutido em <code><head></code>)</strong> Esta camada sincroniza o estado da aplicação com o DOM antes da renderização inicial.</p> </div> <div class="paragraph"> <p><strong>Camada 3 : Estilos Responsivos (CSS com seletores de atributos)</strong> Esta camada define os estilos visuais baseados no estado definido pela camada 2.</p> </div> <div class="paragraph"> <p>Exploramos agora cada camada em detalhe.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_1_salvar_a_escolha_do_usuário">Etapa 1 : Salvar a Escolha do Usuário</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_localstorage_sua_memória_persistente">O localStorage: Sua Memória Persistente</h3> <div class="paragraph"> <p>Le <code>localStorage`é uma API Web Storage que permite armazenar pares chave-valor no navegador de forma persistente. Diferente dos cookies, os dados do`localStorage</code>:</p> </div> <div class="ulist"> <ul> <li> <p>Nunca são enviadas automaticamente para o servidor</p> </li> <li> <p>Têm uma capacidade de armazenamento maior (geralmente 5-10 MB)</p> </li> <li> <p>Não têm data de expiração (persistente até exclusão explícita)</p> </li> <li> <p>São limitadas ao protocolo e ao domínio (Same-Origin Policy)</p> </li> </ul> </div> <div class="paragraph"> <p>Para o nosso caso de uso, o`localStorage`Está perfeito porque :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Não precisamos compartilhar esta informação com o servidor</p> </li> <li> <p>Queremos que a preferência persista indefinidamente</p> </li> <li> <p>O tamanho de armazenamento necessário é mínimo (alguns bytes)</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_implementação_da_cópia_de_segurança_do_tema">Implementação da Cópia de Segurança do Tema</h3> <div class="paragraph"> <p>Como salvamos a escolha do usuário quando ele muda 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="_gerenciamento_dos_casos_de_erro">Gerenciamento dos Casos de Erro</h3> <div class="paragraph"> <p>É crucial gerir os casos em que o`localStorage`não está disponível ou acessível. Vários cenários podem impedir o acesso ao`localStorage`: (Note: The actual output should be exactly a space, colon, and a space, with no additional characters or commentary.)</p> </div> <div class="paragraph"> <p><strong>Navegação privada estrita</strong>Safari em modo de navegação privada lança uma exceção`QuotaExceededError`durante tentativas de escrita no`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Configurações de privacidade</strong>Alguns navegadores ou extensões de privacidade podem bloquear o acesso ao`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Limitações de domínio</strong> : Le `localStorage`não é acessível no protocolo`file://`em alguns navegadores.</p> </div> <div class="paragraph"> <p><strong>Espaço de armazenamento saturado</strong>Embora raro, o espaço de armazenamento pode estar completamente preenchido.</p> </div> <div class="paragraph"> <p>É por isso que nosso código usa um bloco`try…​catch`para lidar com esses casos com elegância, continuando a oferecer a funcionalidade de alteração de tema mesmo que a persistência não esteja disponível</p> </div> </div> <div class="sect2"> <h3 id="_estratégias_avançadas_de_persistência">Estratégias Avançadas de Persistência</h3> <div class="paragraph"> <p>Para aplicações mais sofisticadas, você pode considerar estratégias adicionais:</p> </div> <div class="paragraph"> <p><strong>Sincronização do 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>Esta abordagem permite sincronizar as preferências entre dispositivos para os utilizadores ligados, mantendo a capacidade de resposta local imediata.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_2_o_script_de_pré_carregamento_no_head">Etapa 2: O Script de Pré-carregamento no `<head></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_coração_da_solução">O Coração da Solução</h3> <div class="paragraph"> <p>É aqui que a magia opera realmente. Vamos colocar um pequeno script<strong>em linha</strong>diretamente no nosso`<head>`, antes de todas as nossas tags`<link>`de folhas de estilo. Este script é voluntariamente minimalista, autônomo, e concebido para ser executado o mais rápido possível.</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="_anatomia_do_script_cada_linha_conta">Anatomia do Script: Cada Linha Conta</h3> <div class="paragraph"> <p>Vamos analisar este script linha por linha para entender cada decisão de design:</p> </div> <div class="paragraph"> <p><strong>A IIFE (expressão de função imediatamente 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 estrutura cria uma função que é executada imediatamente. Por quê? Para isolar nossas variáveis em um escopo local e evitar poluir o escopo global. Mesmo que usemos apenas`const`(que tem um escopo de bloco), a IIFE é uma boa prática que deixa nossas intenções claras e protege contra possíveis conflitos de nomes.</p> </div> <div class="paragraph"> <p><strong>O Modo Estrito</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 diretiva ativa o modo estrito do JavaScript, que : - Proíbe o uso de variáveis não declaradas - Gera erros para as operações perigosas - Melhora o desempenho em alguns motores JavaScript</p> </div> <div class="paragraph"> <p>Para um script crítico como este, queremos a máxima segurança.</p> </div> <div class="paragraph"> <p><strong>O bloco 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 bloco é absolutamente crucial. Garante que se algo correr mal (localStorage bloqueado, erro de sintaxe improvável, etc.), o nosso script não bloqueará o carregamento de toda a página. A utilização de`console.warn`em vez de`console.error`indica que é um problema não crítico</p> </div> <div class="paragraph"> <p><strong>A Leitura do 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 linha pode lançar uma exceção em alguns contextos (navegação privada rígida do Safari). Por isso, ela está em um bloco try…​catch.</p> </div> <div class="paragraph"> <p><strong>A Aplicação 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 o tema apenas se encontrarmos um salvo. Caso contrário, deixamos o CSS usar seu tema padrão. Essa abordagem é mais robusta do que um valor padrão fixo no JavaScript.</p> </div> </div> <div class="sect2"> <h3 id="_detecção_da_preferência_do_sistema_bônus">Detecção da Preferência do Sistema (Bônus)</h3> <div class="paragraph"> <p>Uma melhoria opcional, mas elegante, consiste em detectar a preferência de tema do sistema operacional do usuário se ele ainda não fez uma escolha explícita em seu aplicativo:</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 funcionalidade utiliza a Media Query`prefers-color-scheme`para consultar o sistema. No macOS, Windows 10+, iOS, e Android moderno, esta consulta retorna a preferência do sistema do usuário.</p> </div> <div class="paragraph"> <p><strong>Vantagens :</strong> - Experiência personalizada desde a primeira visita - Coerência com o ambiente do sistema do usuário - Nenhum armazenamento necessário para a primeira visita</p> </div> <div class="paragraph"> <p><strong>Considerações :</strong> - Nem todos os navegadores suportam esta funcionalidade (mas o suporte é excelente desde 2020) - A verificação`window.matchMedia`garante a compatibilidade - O utilizador pode sempre sobrescrever esta escolha</p> </div> </div> <div class="sect2"> <h3 id="_desempenho_por_que_este_script_é_rápido">Desempenho: Por que este script é rápido</h3> <div class="paragraph"> <p>Nosso script de pré-carregamento foi projetado para ser extremamente rápido:</p> </div> <div class="paragraph"> <p><strong>tamanho mínimo</strong>Cerca de 300 bytes não minificados, 200 bytes minificados. É insignificante comparado a qualquer imagem ou biblioteca JavaScript.</p> </div> <div class="paragraph"> <p><strong>Em linha</strong>: Sem requisição HTTP adicional. O script está no HTML, portanto está imediatamente disponível.</p> </div> <div class="paragraph"> <p><strong>Operações síncronas simples</strong>: Leitura de uma chave no localStorage (operação ultra-rápida) e modificação de um atributo DOM (operação nativa do navegador).</p> </div> <div class="paragraph"> <p><strong>Nenhuma dependência</strong>: Sem framework, sem biblioteca, apenas JavaScript puro. Sem tempo de inicialização, sem análise de dependências.</p> </div> <div class="paragraph"> <p><strong>Execução única</strong>: Este script é executado uma única vez no carregamento. Sem listeners de eventos, sem loops, sem cálculos complexos.</p> </div> <div class="paragraph"> <p>Na prática, em hardware moderno, esse script é executado em menos de 1 milissegundo, um tempo imperceptível que não tem impacto no desempenho de carregamento da página.</p> </div> </div> <div class="sect2"> <h3 id="_colocação_óptima_no_head">Colocação Óptima no `<head></h3> <div class="paragraph"> <p>A ordem dos elementos no`<head>`É importante. Eis a ordem recomendada:</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 ordem garante que :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>O charset é definido antes de qualquer processamento de texto</p> </li> <li> <p>Nosso script é executado antes do carregamento dos CSS</p> </li> <li> <p>Os CSS são carregados depois e aplicam diretamente o tema correto</p> </li> <li> <p>Os outros recursos não críticos são carregados por último</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_3_o_poder_dos_seletores_de_atributos_css">Passo 3 : O Poder dos Seletores de Atributos CSS</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_sistema_de_tema_do_bootstrap_5">O sistema de tema do Bootstrap 5</h3> <div class="paragraph"> <p>Bootstrap 5 introduziu um sistema elegante de gerenciamento de temas baseado nas propriedades personalizadas CSS (variáveis CSS) e nos seletores de atributos. Este sistema usa o atributo`data-bs-theme`no elemento`<html>`para determinar qual conjunto de variáveis de cor aplicar.</p> </div> <div class="paragraph"> <p>A beleza deste sistema reside na sua simplicidade: em vez de carregar diferentes folhas de estilo ou de alternar as classes em milhares de elementos, alteramos simplesmente um atributo em um único elemento, e o CSS faz o resto graças à cascata.</p> </div> </div> <div class="sect2"> <h3 id="_estrutura_css_para_um_sistema_de_tema">Estrutura CSS para um Sistema de Tema</h3> <div class="paragraph"> <p>Aqui está uma estrutura CSS completa para implementar um 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="#_introdução">Introdução</a></li> <li><a href="#_o_problema_dependência_ao_gradlerunner">O Problema : Dependência ao GradleRunner</a> <ul class="sectlevel2"> <li><a href="#_contexto_do_desenvolvimento_de_plugin">Contexto do Desenvolvimento de Plugin</a></li> <li><a href="#_o_dilema_do_logging">O Dilema do Logging</a></li> <li><a href="#_as_falsas_boas_ideias">As falsas boas ideias</a></li> </ul> </li> <li><a href="#_a_solução_logger_independente">A Solução: Logger Independente</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_recomendada">Arquitetura Recomendada</a></li> <li><a href="#_fluxo_de_execução">Fluxo de Execução</a></li> </ul> </li> <li><a href="#_implementação_completa">Implementação Completa</a> <ul class="sectlevel2"> <li><a href="#_dependências_gradle">Dependências Gradle</a></li> <li><a href="#_configuração_logback">Configuração Logback</a></li> <li><a href="#_classe_de_teste_completa">Classe de teste completa</a></li> </ul> </li> <li><a href="#_esquema_de_logging_multi_nível">Esquema de Logging Multi-Nível</a></li> <li><a href="#_boas_práticas">Boas Práticas</a> <ul class="sectlevel2"> <li><a href="#_estrutura_de_logging_recomendada">Estrutura de Logging Recomendada</a></li> <li><a href="#_símbolos_visuais_para_a_legibilidade">Símbolos Visuais para a Legibilidade</a></li> <li><a href="#_extração_de_informações_da_saída">Extração de Informações da Saída</a></li> </ul> </li> <li><a href="#_comparação_antesdepois">Comparação Antes/Depois</a> <ul class="sectlevel2"> <li><a href="#_antes_abordagem_problemática">Antes : Abordagem Problemática</a></li> <li><a href="#_depois_abordagem_robusta">Depois: Abordagem Robusta</a></li> </ul> </li> <li><a href="#_diagrama_resumo">Diagrama Resumo</a></li> <li><a href="#_armadilhas_a_evitar">armadilhas a evitar</a> <ul class="sectlevel2"> <li><a href="#_armadilha_nº1_esquecer_forwardoutput">Armadilha nº1 : Esquecer `.forwardOutput()</a></li> <li><a href="#_armadilha_n2_logger_não_inicializado">❌ Armadilha n°2: Logger Não Inicializado</a></li> <li><a href="#_armadilha_nº_3_log_excessivo">Armadilha nº 3 : Log excessivo</a></li> </ul> </li> <li><a href="#_resultados_e_métricas">Resultados e Métricas</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_recursos">Recursos</a></li> <li><a href="#_ir_mais_longe">Ir mais longe</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante o desenvolvimento de um plugin Gradle, os testes funcionais são essenciais para validar o comportamento do plugin em um ambiente Gradle real. No entanto, uma questão crucial se coloca rapidamente:<strong>como configurar um sistema de logs eficaz sem criar dependências problemáticas com o <code>GradleRunner</code>?</strong></p> </div> <div class="paragraph"> <p>Neste artigo, vamos explorar :</p> </div> <div class="ulist"> <ul> <li> <p>A problemática de logging nos testes funcionais do Gradle</p> </li> <li> <p>A arquitetura de uma solução robusta com SLF4J e Logback</p> </li> <li> <p>A implementação completa com exemplos concretos</p> </li> <li> <p>As boas práticas e armadilhas a evitar</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_dependência_ao_gradlerunner">O Problema : Dependência ao GradleRunner</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto_do_desenvolvimento_de_plugin">Contexto do Desenvolvimento de Plugin</h3> <div class="paragraph"> <p>Ao desenvolver um plugin Gradle, geralmente usamos o`GradleRunner`do <em>Gradle TestKit</em> para executar dos builds de teste:</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="_o_dilema_do_logging">O Dilema do Logging</h3> <div class="paragraph"> <p>O problema principal é o seguinte:<strong>O logging não deve depender de um objeto do qual não se tem certeza da inicialização.</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-0c5781202c395a4b87cd761f90af9413.png" alt="Diagram" width="442" height="262"> </div> </div> </div> <div class="sect2"> <h3 id="_as_falsas_boas_ideias">As falsas boas ideias</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>Não façam isso:</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="_a_solução_logger_independente">A Solução: Logger Independente</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitetura_recomendada">Arquitetura Recomendada</h3> <div class="paragraph"> <p>A solução consiste em usar um logger<strong>totalmente independente</strong> du <code>GradleRunner</code>, inicializado no nível da classe de teste.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-09f9be2507b1dd768e2766422b70c50e.png" alt="Diagram" width="601" height="448"> </div> </div> </div> <div class="sect2"> <h3 id="_fluxo_de_execução">Fluxo de Execução</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-a52adcce9939984a9c8e8a4fc1953e2d.png" alt="Diagram" width="786" height="686"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implementação_completa">Implementação Completa</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dependências_gradle">Dependências Gradle</h3> <div class="paragraph"> <p>Adicione as dependências necessárias no seu`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="_configuração_logback">Configuração Logback</h3> <div class="paragraph"> <p>Crie o arquivo`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="_classe_de_teste_completa">Classe de teste 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_logging_multi_nível">Esquema de Logging Multi-Nível</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-341e65e1225cc2d3c65be818c3f39e2e.png" alt="Diagram" width="314" height="911"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_boas_práticas">Boas Práticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrutura_de_logging_recomendada">Estrutura 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_visuais_para_a_legibilidade">Símbolos Visuais para a Legibilidade</h3> <div class="paragraph"> <p>Use símbolos Unicode para melhorar a legibilidade dos logs:</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="_extração_de_informações_da_saída">Extração de Informações da Saída</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="_comparação_antesdepois">Comparação Antes/Depois</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_antes_abordagem_problemática">Antes : Abordagem Problemática</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="_depois_abordagem_robusta">Depois: Abordagem Robusta</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_resumo">Diagrama Resumo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml ... ... ( skipping 129 lines ) ... } skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam backgroundColor #FEFEFE title Fluxo Completo de Logging nos Testes Funcionais actor "desenvolvedor" as dev participant "JUnit" as junit participant "ClasseTeste" as test participant "Logger ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml !theme plain skinparam backgroundColor #FEFEFE title Fluxo Completo de Logging nos Testes Funcionais actor "desenvolvedor" as dev participant "JUnit" as junit participant "ClasseTeste" as test participant "Logger (SLF4J)" as logger participant "Logback" as logback participant "GradleRunner" as runner participant "Console/fichier" as output dev -> junit : lance les tests activate junit junit -> test : charge la classe activate test test -> logger : initialize (companion) activate logger logger -> logback : configure activate logback logback --> logger : ready deactivate logback logger --> test : ✓ deactivate logger == Phase de Setup == junit -> test : @BeforeAll test -> logger : info("Inicialização") logger -> output : [INFO] Initialisation junit -> test : @BeforeEach test -> logger : debug("Configurar teste") logger -> output : [DEBUG] Setup test == Phase de Test == junit -> test : @Test test -> logger : info("TEST: Iniciando") logger -> output : [INFO] TEST: Starting test -> runner : create() activate runner test -> runner : .forwardOutput() test -> runner : .build() runner -> runner : execute Gradle runner --> test : BuildResult + output text deactivate runner test -> logger : debug("Analisando saída") logger -> output : [DEBUG] Analyzing output test -> test : assertions test -> logger : info("�✓ Teste aprovado") logger -> output : [INFO] ✓ Test passed == Phase de Cleanup == junit -> test : @AfterEach test -> logger : debug("Limpeza") logger -> output : [DEBUG] Cleanup junit -> test : @AfterAll test -> logger : info("Fim dos testes") logger -> output : [INFO] Fin des tests test --> junit : ✓ all tests passed deactivate test deactivate junit dev <-- junit : rapport de tests @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_armadilhas_a_evitar">armadilhas a evitar</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_armadilha_nº1_esquecer_forwardoutput">Armadilha nº1 : Esquecer `.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="_armadilha_n2_logger_não_inicializado">❌ Armadilha n°2: Logger Não 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="_armadilha_nº_3_log_excessivo">Armadilha nº 3 : Log excessivo</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_e_métricas">Resultados e Métricas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Com essa abordagem, você obtém :</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">depois</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Linhas de código</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50 linhas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~80 linhas (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tempo de depuração</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">aproximadamente 30 min</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">Erros 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">detalhado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Manutenção</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">Simples</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Independência</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">Independente</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>A implementação de um sistema de registro robusto nos testes funcionais de plugins Gradle baseia-se em um princípio simples:<strong>independência</strong>.</p> </div> <div class="paragraph"> <p>Pontos-chave a reter:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Logger independente</strong>: Inicializado em um`companion object`</p> </li> <li> <p><strong>SLF4J + Logback</strong>: Stack testada e configurável</p> </li> <li> <p><strong>.forwardOutput()</strong>: Captura da saída do Gradle</p> </li> <li> <p><strong>Logging estruturado</strong>INFO para as etapas, DEBUG para os detalhes</p> </li> <li> <p><strong>Análise de saída</strong>: Extração de informações desde`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>Esta abordagem garante testes<strong>mantível</strong>, <strong>depuráveis</strong> et <strong>robustos</strong>, respeitando os princípios de design 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">Documentação do Gradle TestKit</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 Configuration</a></p> </li> <li> <p><a href="https://github.com/gradle/gradle/tree/master/subprojects/test-kit">Código Fonte do Gradle TestKit</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_ir_mais_longe">Ir mais longe</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em um próximo artigo, vamos explorar :</p> </div> <div class="ulist"> <ul> <li> <p>Integração contínua com logging estruturado</p> </li> <li> <p>Os relatórios HTML de testes com logs integrados</p> </li> <li> <p>Depuração avançada com JVM attach</p> </li> <li> <p>O desempenho e as otimizações de logging</p> </li> </ul> </div> <div class="paragraph"> <p><em>Este artigo faz parte da série "Desenvolvimento de Plugins Gradle" no meu 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="#_introdução">Introdução</a></li> <li><a href="#_a_problemática">A problemática</a> <ul class="sectlevel2"> <li><a href="#_contexto_de_uso">Contexto de uso</a></li> <li><a href="#_as_abordagens_possíveis">As abordagens possíveis</a> <ul class="sectlevel3"> <li><a href="#_opção_1_caracteres_unicode">Opção 1: Caracteres Unicode</a></li> <li><a href="#_opção_2_imagens_externas">Opção 2: Imagens externas</a></li> <li><a href="#_opção_3_papéis_css_personalizados">Opção 3 : Papéis CSS personalizados</a></li> <li><a href="#_opção_4_injeção_html_solução_retenida">Opção 4: Injeção HTML (solução retenida)</a></li> </ul> </li> </ul> </li> <li><a href="#_a_solução_injeção_de_html_com">A solução : Injeção de HTML com </a> <ul class="sectlevel2"> <li><a href="#_princípio_de_funcionamento">Princípio de funcionamento</a></li> <li><a href="#_implementação">Implementação</a> <ul class="sectlevel3"> <li><a href="#_explicação_das_propriedades_css">Explicação das propriedades CSS</a></li> </ul> </li> <li><a href="#_exemplo_completo">Exemplo completo</a></li> </ul> </li> <li><a href="#_optimizações_e_boas_práticas">Optimizações e boas práticas</a> <ul class="sectlevel2"> <li><a href="#_gerir_as_cores_claras">Gerir as cores claras</a></li> <li><a href="#_ajustar_o_tamanho_dos_quadrados">Ajustar o tamanho dos quadrados</a></li> <li><a href="#_criar_variantes">Criar variantes</a> <ul class="sectlevel3"> <li><a href="#_círculo_colorido">Círculo colorido</a></li> <li><a href="#_quadrado_com_borda_colorida">Quadrado com borda colorida</a></li> </ul> </li> </ul> </li> <li><a href="#_arquitetura_da_solução">Arquitetura da solução</a></li> <li><a href="#_vantagens_e_limitações">Vantagens e limitações</a> <ul class="sectlevel2"> <li><a href="#_vantagens">Vantagens</a></li> <li><a href="#_limitações">Limitações</a></li> <li><a href="#_melhoria_da_acessibilidade">Melhoria da acessibilidade</a></li> </ul> </li> <li><a href="#_exemplo_concreto_documentação_de_temas">Exemplo concreto: Documentação de temas</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ao redigir documentação técnica, especialmente para guias de estilo ou especificações de interface do usuário, é comum precisar exibir paletas de cores. AsciiDoc, embora muito poderoso para documentação, não oferece sintaxe nativa para exibir amostras de cor. Este artigo explora o problema e propõe uma solução elegante baseada na injeção HTML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_problemática">A problemática</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexto_de_uso">Contexto de uso</h3> <div class="paragraph"> <p>Imagine que você está documentando as variáveis CSS de um tema de aplicação web. Você precisa de :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Listar os códigos de cores hexadecimais</p> </li> <li> <p>Mostrar um exemplo visual de cada cor</p> </li> <li> <p>Manter a legibilidade do documento fonte</p> </li> <li> <p>Garantir a compatibilidade com os geradores de sites 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="1744" height="5616"> </div> </div> </div> <div class="sect2"> <h3 id="_as_abordagens_possíveis">As abordagens possíveis</h3> <div class="paragraph"> <p>Várias soluções podem ser consideradas para exibir cores em um documento AsciiDoc :</p> </div> <div class="imageblock"> <div class="content"> <img src="component-diagram.svg" alt="component diagram" width="1742" height="5688"> </div> </div> <div class="sect3"> <h4 id="_opção_1_caracteres_unicode">Opção 1: Caracteres Unicode</h4> <div class="paragraph"> <p>O uso de caracteres Unicode como`■`(■) é simples, mas 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>Limitações</strong> : Sem controle sobre a cor, depende da fonte do sistema.</p> </div> </div> <div class="sect3"> <h4 id="_opção_2_imagens_externas">Opção 2: Imagens externas</h4> <div class="paragraph"> <p>Criar imagens PNG ou SVG para cada cor:</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><strong>Limitations</strong> : Manutenção pesada, multiplicação dos arquivos, não há sincronização automática.</p> </div> </div> <div class="sect3"> <h4 id="_opção_3_papéis_css_personalizados">Opção 3 : Papéis CSS personalizados</h4> <div class="paragraph"> <p>Definir classes CSS e aplicá-las por meio de papéis 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>Limitações</strong> : Necessita de uma folha de estilo externa, definição prévia de todas as cores possíveis.</p> </div> </div> <div class="sect3"> <h4 id="_opção_4_injeção_html_solução_retenida">Opção 4: Injeção HTML (solução retenida)</h4> <div class="paragraph"> <p>Utilizar a macro``para injetar HTML com estilos em linha :</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="_a_solução_injeção_de_html_com">A solução : Injeção de HTML com </h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_princípio_de_funcionamento">Princípio de funcionamento</h3> <div class="paragraph"> <p>A macro``O AsciiDoc permite inserir conteúdo bruto que não será interpretado pelo processador AsciiDoc. Isso nos permite injetar diretamente HTML com estilos CSS inline.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml participant "Document\nAsciiDoc" as doc participant "Processador\nAsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "Document\nAsciiDoc" as doc participant "Processador\nAsciiDoc" 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="_implementação">Implementação</h3> <div class="paragraph"> <p>Aqui está a estrutura HTML para injetar:</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="_explicação_das_propriedades_css">Explicação das propriedades 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">Propriedade</th> <th class="tableblock halign-left valign-top">Função</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 width/height permanecendo no fluxo inline</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">Tamanho do quadrado relativo ao tamanho da fonte (responsivo)</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">A cor a ser exibida (variável de acordo com suas necessidades)</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">Alinhe o quadrado com o texto adjacente</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">Espaçamento entre o quadrado e o texto</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_exemplo_completo">Exemplo completo</h3> <div class="paragraph"> <p>Este é um exemplo documentando uma 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>Quem produz a seguinte saída:</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`(branco quebrado)</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`(preto muito escuro)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --cor-de-destaque:`#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 mais escuro)</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`(branco)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_optimizações_e_boas_práticas">Optimizações e boas práticas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_gerir_as_cores_claras">Gerir as cores claras</h3> <div class="paragraph"> <p>Para cores muito claras (branco, cinza muito claro), adicione uma borda para torná-las visíveis em fundo branco :</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>A borda cinza (<code>border:1px solid #ccc</code>) permite delimitar o quadrado branco sobre um fundo branco.</p> </div> </div> <div class="sect2"> <h3 id="_ajustar_o_tamanho_dos_quadrados">Ajustar o tamanho dos quadrados</h3> <div class="paragraph"> <p>Você pode ajustar o tamanho dos quadrados de acordo com suas necessidades:</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>O uso da unidade`em`garante que os quadrados se adaptem ao tamanho da fonte.</p> </div> </div> <div class="sect2"> <h3 id="_criar_variantes">Criar variantes</h3> <div class="paragraph"> <p>Para necessidades específicas, você pode criar diferentes formas:</p> </div> <div class="sect3"> <h4 id="_círculo_colorido">Círculo colorido</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="_quadrado_com_borda_colorida">Quadrado com borda colorida</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="_arquitetura_da_solução">Arquitetura da solução</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="architecture-diagram.svg" alt="architecture diagram" width="1761" height="5432"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_vantagens_e_limitações">Vantagens e limitações</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_vantagens">Vantagens</h3> <div class="ulist"> <ul> <li> <p>✓ <strong>Autonomia</strong> : Não há dependência de arquivos externos</p> </li> <li> <p>�✓ <strong>Portabilidade</strong> : Funciona com todos os processadores AsciiDoc</p> </li> <li> <p>✓ <strong>Sincronização</strong> : O código de cores está diretamente no HTML</p> </li> <li> <p>✓ <strong>Flexibilidade</strong> : Personalização completa do estilo</p> </li> <li> <p>✓ <strong>Manutenção</strong> : Modificação simples do código hexadecimal</p> </li> <li> <p>✓ <strong>Compatibilidade JBake</strong> : Funciona perfeitamente com os geradores de sites estáticos</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_limitações">Limitações</h3> <div class="ulist"> <ul> <li> <p>✗ <strong>Verbosité</strong> : Código HTML repetitivo no código-fonte AsciiDoc</p> </li> <li> <p>�✗ <strong>Legibilidade da fonte</strong> : O documento fonte é menos limpo</p> </li> <li> <p>✗ <strong>Acessibilidade</strong> : Sem texto alternativo nativo (a ser adicionado manualmente)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_melhoria_da_acessibilidade">Melhoria da acessibilidade</h3> <div class="paragraph"> <p>Para tornar os quadrados acessíveis aos leitores de tela:</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>Os atributos`role="img"` et `aria-label`Permitem que as tecnologias assistivas compreendam e descrevam o conteúdo visual.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_exemplo_concreto_documentação_de_temas">Exemplo concreto: Documentação de temas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está um exemplo completo documentando vários 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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>A injeção HTML via a macro``O AsciiDoc oferece uma solução elegante e pragmática para exibir amostras de cor na documentação técnica. Embora seja ligeiramente verbosa, essa abordagem garante uma portabilidade máxima e uma manutenção simplificada.</p> </div> <div class="paragraph"> <p>Esta técnica não requer nenhuma configuração externa, nenhuma folha de estilo adicional, e funciona imediatamente com JBake e todos os processadores AsciiDoc padrões.</p> </div> <div class="paragraph"> <p>Depois de você ter criado seu primeiro quadrado colorido, basta copiar e colar o código HTML e alterar o código hexadecimal para criar rapidamente uma paleta completa.</p> </div> <div class="paragraph"> <p>Esta técnica pode ser estendida a outros casos de uso que necessitam de renderização visual personalizada: ícones, badges, gráficos simples, ou todo elemento visual que necessita de um controle preciso do 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">Documentação AsciiDoc : pass macro</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake Documentação</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value" target="_blank" rel="noopener">MDN : Valores de cor CSS</a></p> </li> </ul> </div> <div class="paragraph"> <p><em>Artigo publicado em 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="#_introdução">Introdução</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_caso_de_uso_use_case">Diagrama de caso de uso (Use Case)</a></li> </ul> </li> <li><a href="#_arquitetura_da_internacionalização">Arquitetura da internacionalização</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_estrutura_organização_dos_arquivos">Diagrama de estrutura (Organização dos arquivos)</a></li> <li><a href="#_por_que_essa_abordagem">Por que essa abordagem?</a></li> <li><a href="#_diagrama_de_componentes">Diagrama de componentes</a></li> </ul> </li> <li><a href="#_i18n_do_templating_com_thymeleaf">I18n do templating com Thymeleaf</a> <ul class="sectlevel2"> <li><a href="#_estrutura_dos_arquivos_de_mensagens">Estrutura dos arquivos de mensagens</a></li> <li><a href="#_conteúdo_dos_arquivos_de_mensagens">Conteúdo dos arquivos de mensagens</a></li> <li><a href="#_utilização_nos_templates">Utilização nos templates</a></li> <li><a href="#_diagrama_de_sequência_resolução_i18n">Diagrama de sequência - Resolução i18n</a></li> <li><a href="#_configuração_da_localidade_no_jbake">Configuração da localidade no JBake</a></li> </ul> </li> <li><a href="#_i18n_dos_artigos_organização_por_pastas">I18n dos artigos: organização por pastas</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_fluxo_fluxo_geração">Diagrama de fluxo (Fluxo) - Geração</a></li> <li><a href="#_estrutura_das_pastas">Estrutura das pastas</a></li> <li><a href="#_vantagens_desta_abordagem">Vantagens desta abordagem</a></li> <li><a href="#_metadados_dos_artigos">Metadados dos artigos</a></li> <li><a href="#_configuração_das_urls">Configuração das URLs</a></li> </ul> </li> <li><a href="#_modelos_para_a_exibição_multilíngue">Modelos para a exibição multilíngue</a> <ul class="sectlevel2"> <li><a href="#_template_de_artigo_com_seletor_de_idioma">Template de artigo com seletor de idioma</a></li> <li><a href="#_índice_filtrado_por_idioma">Índice filtrado por idioma</a></li> </ul> </li> <li><a href="#_navegação_entre_idiomas">Navegação entre idiomas</a> <ul class="sectlevel2"> <li><a href="#_seletor_de_idioma_global">Seletor de idioma global</a></li> <li><a href="#_diagrama_de_fluxo_leitura_do_usuário">Diagrama de fluxo - Leitura do usuário</a></li> <li><a href="#_estilo_css_para_o_seletor">Estilo CSS para o seletor</a></li> </ul> </li> <li><a href="#_feed_rss_por_idioma">Feed RSS por idioma</a></li> <li><a href="#_boas_práticas_e_dicas">Boas práticas e dicas</a> <ul class="sectlevel2"> <li><a href="#_1_coerência_dos_identificadores_de_artigo">1. Coerência dos identificadores de artigo</a></li> <li><a href="#_2_datas_coerentes">2. Datas coerentes</a></li> <li><a href="#_3_tags_multilíngues">3. Tags multilíngues</a></li> <li><a href="#_4_gerenciamento_dos_artigos_não_traduzidos">4. Gerenciamento dos artigos não traduzidos</a></li> <li><a href="#_5_mapa_do_site_multilíngue">5. Mapa do site multilíngue</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_implantação">Diagrama de implantação</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>A internacionalização (i18n) de um site estático pode parecer complexa à primeira vista, mas o JBake combinado com o Thymeleaf oferece soluções elegantes para criar um site multilíngue. Neste artigo, vou mostrar como implementei o i18n no meu blog, cobrindo tanto o templating quanto a gestão dos artigos em vários idiomas.</p> </div> <div class="sect2"> <h3 id="_diagrama_de_caso_de_uso_use_case">Diagrama de caso de uso (Use Case)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-89e91fc926dae6c5891c8e4a1e4301d9.png" alt="Diagram" width="643" height="452"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_da_internacionalização">Arquitetura da internacionalização</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nossa abordagem baseia-se em dois pilares :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>O i18n do templating</strong>: utilização dos arquivos de mensagens Thymeleaf para os elementos da interface</p> </li> <li> <p><strong>O i18n do conteúdo</strong>: organização dos artigos por língua em uma estrutura de pastas dedicada</p> </li> </ol> </div> <div class="sect2"> <h3 id="_diagrama_de_estrutura_organização_dos_arquivos">Diagrama de estrutura (Organização dos arquivos)</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_que_essa_abordagem">Por que essa abordagem?</h3> <div class="paragraph"> <p>Esta separação permite:</p> </div> <div class="ulist"> <ul> <li> <p>Manter a consistência na interface, independentemente do idioma.</p> </li> <li> <p>Gerir independentemente o conteúdo e as traduções de artigos</p> </li> <li> <p>Facilitar a adição de novas línguas sem refatoração maior</p> </li> <li> <p>Permitir artigos disponíveis apenas em certas línguas</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-c4f46c86d4d34e9b58b816b38348f050.png" alt="Diagram" width="1771" height="477"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i18n_do_templating_com_thymeleaf">I18n do templating com Thymeleaf</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrutura_dos_arquivos_de_mensagens">Estrutura dos arquivos de mensagens</h3> <div class="paragraph"> <p>O primeiro passo consiste em criar os arquivos de propriedades para cada idioma suportado :</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="_conteúdo_dos_arquivos_de_mensagens">Conteúdo dos arquivos de mensagens</h3> <div class="paragraph"> <p>Aqui está um exemplo de arquivo`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>E seu equivalente em 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="_utilização_nos_templates">Utilização nos templates</h3> <div class="paragraph"> <p>Nos seus templates Thymeleaf, utilize a sintaxe`#{}`para acessar as mensagens :</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_sequência_resolução_i18n">Diagrama de sequência - Resolução 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\nAnalisador" as parser participant "Thymeleaf ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Auteur participant JBake participant "AsciiDoc\nAnalisador" as parser participant "Thymeleaf Motor" as thymeleaf participant "I18n\nResolver" 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: "Início" i18n --> thymeleaf: "Início" 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: "Início" i18n --> thymeleaf: "Início" 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="_configuração_da_localidade_no_jbake">Configuração da localidade no JBake</h3> <div class="paragraph"> <p>No seu arquivo`jbake.properties`, defina a localidade padrão :</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_dos_artigos_organização_por_pastas">I18n dos artigos: organização por pastas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_fluxo_fluxo_geração">Diagrama de fluxo (Fluxo) - Geração</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c91cb37b7790833828a90d2610465f57.png" alt="Diagram" width="285" height="1034"> </div> </div> </div> <div class="sect2"> <h3 id="_estrutura_das_pastas">Estrutura das pastas</h3> <div class="paragraph"> <p>Em vez de usar sufixos nos nomes de arquivos, optei por uma organização por pastas que oferece mais clareza e manutenibilidade :</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="_vantagens_desta_abordagem">Vantagens desta abordagem</h3> <div class="paragraph"> <p>Esta estrutura apresenta várias vantagens:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Separação clara</strong>: cada língua tem seu próprio espaço</p> </li> <li> <p><strong>Nomenclatura flexível</strong>: os arquivos podem ter nomes diferentes dependendo do idioma</p> </li> <li> <p><strong>Escalabilidade</strong>fácil de adicionar um novo idioma</p> </li> <li> <p><strong>Organização natural</strong>segue a lógica temporal de JBake</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_metadados_dos_artigos">Metadados dos artigos</h3> <div class="paragraph"> <p>Cada artigo deve conter metadados para permitir a ligação entre traduções. Aqui está um exemplo:</p> </div> <div class="paragraph"> <p><strong>Versão 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>Versão 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: O atributo`:jbake-article-id:`é crucial: ele permite ligar as diferentes traduções do mesmo artigo.</p> </div> </div> <div class="sect2"> <h3 id="_configuração_das_urls">Configuração das URLs</h3> <div class="paragraph"> <p>Dentro`jbake.properties`, configure o padrão de URL para incluir o 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>Isso gerará URLs do 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="_modelos_para_a_exibição_multilíngue">Modelos para a exibição multilíngue</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_template_de_artigo_com_seletor_de_idioma">Template de artigo com seletor de idioma</h3> <div class="paragraph"> <p>Crie um modelo`post.html`exibe as traduções disponíveis :</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>Crie modelos de índice para cada idioma :</p> </div> <div class="paragraph"> <p><strong>index.html</strong>(índice français) :</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 anglais) :</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="_navegação_entre_idiomas">Navegação entre idiomas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_seletor_de_idioma_global">Seletor de idioma global</h3> </div> <div class="sect2"> <h3 id="_diagrama_de_fluxo_leitura_do_usuário">Diagrama de fluxo - Leitura do usuário</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>Adicione um seletor de idioma no seu template 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_o_seletor">Estilo CSS para o seletor</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="_feed_rss_por_idioma">Feed RSS por idioma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para ter feeds RSS separados por idioma, crie modelos distintos:</p> </div> <div class="paragraph"> <p><strong>feed.xml</strong>(fluxo 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="_boas_práticas_e_dicas">Boas práticas e dicas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_coerência_dos_identificadores_de_artigo">1. Coerência dos identificadores de artigo</h3> <div class="paragraph"> <p>Certifique-se de que`:jbake-article-id:`é idêntico para todas as traduções de um mesmo artigo. Utilize um formato consistente:</p> </div> <div class="ulist"> <ul> <li> <p>Prefira os identificadores em inglês para universalidade.</p> </li> <li> <p>Use hífens para separar as palavras</p> </li> <li> <p>Evite os caracteres especiais</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_datas_coerentes">2. Datas coerentes</h3> <div class="paragraph"> <p>Todas as traduções de um artigo devem ter a mesma data de publicação (<code>:jbake-date:</code>) Isso facilita a classificação e a exibição cronológica.</p> </div> </div> <div class="sect2"> <h3 id="_3_tags_multilíngues">3. Tags multilíngues</h3> <div class="paragraph"> <p>Para as tags, você tem duas opções:</p> </div> <div class="paragraph"> <p><strong>Opção 1: Tags universais em 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>Opção 2 : Tags traduzidas com mapeamento</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_gerenciamento_dos_artigos_não_traduzidos">4. Gerenciamento dos artigos não traduzidos</h3> <div class="paragraph"> <p>Não é obrigatório traduzir todos os artigos. Se um artigo existir apenas em uma língua, ele simplesmente não aparecerá nas listas da outra língua.</p> </div> </div> <div class="sect2"> <h3 id="_5_mapa_do_site_multilíngue">5. Mapa do site multilíngue</h3> <div class="paragraph"> <p>Gere um sitemap que inclua todas as línguas :</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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>A internacionalização de um site JBake com Thymeleaf é uma abordagem robusta e manutenível. Separando o i18n do templating (via os arquivos de mensagens) e o i18n do conteúdo (via a organização em pastas), você obtém um sistema flexível que pode evoluir facilmente.</p> </div> <div class="paragraph"> <p>Os pontos-chave a reter :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Arquivos de mensagens Thymeleaf</strong>para a interface do usuário</p> </li> <li> <p><strong>Organização por pastas</strong>(ano/idioma) para os artigos</p> </li> <li> <p><strong>Identificadores do artigo</strong>para vincular as traduções</p> </li> <li> <p><strong>Modelos dedicados</strong>para cada língua</p> </li> <li> <p><strong>URLs explícitas</strong>incluindo o código de idioma</p> </li> </ul> </div> <div class="sect2"> <h3 id="_diagrama_de_implantação">Diagrama de implantação</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 14) ] @startuml node "Máquina de desenvolvimento" { artifact "Fontes" { folder "contenu/" folder "modelos/" folder "ativos/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Servidor de build ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml node "Máquina de desenvolvimento" { artifact "Fontes" { folder "contenu/" folder "modelos/" folder "ativos/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Servidor de build (CI/CD)" { component "GitHub Actions ou GitLab CI" as ci jbake --> ci : push } cloud "CDN / Hospedagem" { node "Servidor Web Estático" { artifact "Site gerado" { folder "/pt/blog/" folder "/en/blog/" folder "/assets/" } } } ci --> "Site gerado" : déploiement actor "Leitores" as users users --> "Servidor Web Estático" : HTTPS @enduml</pre> </div> </div> <div class="paragraph"> <p>Esta arquitetura permite que você comece simplesmente com dois idiomas e adicione outros sem grandes refatorações. Tudo permanece totalmente estático e performante, fiel à filosofia do JBake.</p> </div> <div class="paragraph"> <p>Bom desenvolvimento multilíngue! 🌍</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="#_introdução">Introdução</a></li> <li><a href="#_download_do_tor_e_da_sua_assinatura">Download do Tor e da sua assinatura</a></li> <li><a href="#_verificação_criptográfica_da_assinatura">Verificação criptográfica da assinatura</a> <ul class="sectlevel2"> <li><a href="#_importar_a_chave_pública_do_tor_project">Importar a chave pública do Tor Project</a></li> <li><a href="#_2_verificar_a_assinatura">2. Verificar a assinatura</a></li> <li><a href="#_exemplo_prático_assinatura_válida_mas_chave_não_certificada">Exemplo prático: Assinatura válida mas chave não certificada</a></li> </ul> </li> <li><a href="#_por_que_verificar_a_assinatura">Por que verificar a assinatura?</a></li> <li><a href="#_extração_e_lançamento_de_tor_browser">Extração e lançamento de Tor Browser</a></li> <li><a href="#_integração_à_área_de_trabalho_ubuntu">Integração à área de trabalho Ubuntu</a></li> <li><a href="#_explorar_recursos_educativos_com_tor">Explorar recursos educativos com Tor</a></li> <li><a href="#_atualização_do_tor_browser">Atualização do Tor Browser</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_referências">Referências</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Num mundo onde a privacidade digital está cada vez mais ameaçada, <strong>Tor Browser</strong> continua a ser uma ferramenta essencial para preservar o anonimato e a liberdade de informação. No entanto, é crucial nunca executar um software baixado sem ter<strong>verificado sua autenticidade</strong>. Este artigo apresenta um método completo para:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Baixar <strong>Tor Browser</strong> e sua assinatura`.asc`</p> </li> <li> <p>Verificar a validade do arquivo baixado</p> </li> <li> <p>Instalar e executar <strong>Tor Browser</strong> no Ubuntu</p> </li> <li> <p>Adicioná-lo aos menus da área de trabalho para uso diário</p> </li> <li> <p>Explorar recursos educativos e OSINT éticos via Tor</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_download_do_tor_e_da_sua_assinatura">Download do Tor e da sua assinatura</h2> <div class="sectionbody"> <div class="paragraph"> <p>Crie uma pasta dedicada para o 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>Em seguida, baixe o arquivo do navegador Tor e sua assinatura:</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="_verificação_criptográfica_da_assinatura">Verificação criptográfica da assinatura</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta etapa é<strong>indispensável</strong>para garantir que o arquivo baixado realmente venha do <strong>Tor Project</strong> e não foi modificado.</p> </div> <div class="sect2"> <h3 id="_importar_a_chave_pública_do_tor_project">Importar a chave pública do Tor Project</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 a chave está bem 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_a_assinatura">2. Verificar a assinatura</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>Se tudo estiver correto, a mensagem seguinte será exibida :</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>Em caso de aviso de chave não certificada, isso significa simplesmente que você ainda não assinou a chave confiável do Projeto Tor, mas a assinatura permanece válida.</p> </div> </div> <div class="sect2"> <h3 id="_exemplo_prático_assinatura_válida_mas_chave_não_certificada">Exemplo prático: Assinatura válida mas chave não certificada</h3> <div class="paragraph"> <p>É comum encontrar uma mensagem como esta durante a verificação:</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>Esta mensagem indica que a assinatura é tecnicamente "boa" (o arquivo não foi alterado), mas que seu sistema GPG não pode <strong>certificar a confiança</strong> na chave em si. Para dissipar esta dúvida, é imperativo comparar a impressão digital da chave principal (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) com a que foi publicada no site oficial do Tor Project.</p> </div> <div class="paragraph"> <p>Segundo o site oficial, a pegada esperada é:`EF6E286DDA85EA2A4BA7DE684E2C6E8793298290`.</p> </div> <div class="paragraph"> <p>Como a pegada exibida por`gpg`corresponde <strong>exatamente</strong> àquela do site oficial, você pode ter certeza de que a chave é legítima e que o arquivo está seguro. O aviso de "chave não certificada" é então uma informação sobre sua configuração GPG local, e não sobre a validade da assinatura ou a autenticidade do arquivo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_por_que_verificar_a_assinatura">Por que verificar a assinatura?</h2> <div class="sectionbody"> <div class="paragraph"> <p>A verificação das assinaturas GPG é um ato fundamental de segurança digital. Ela permite:</p> </div> <div class="ulist"> <ul> <li> <p>Garantir<strong>a autenticidade</strong>do software baixado</p> </li> <li> <p>Impedir a instalação de um arquivo comprometido por um ator malicioso</p> </li> <li> <p>Participar à<strong>soberania digital</strong>individual</p> </li> <li> <p>Promover uma cultura digital responsável e ética</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="usecase-tor-verification.svg" alt="usecase tor verification" width="408" height="268"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_extração_e_lançamento_de_tor_browser">Extração e lançamento de Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Extraia o arquivo baixado:</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>Inicie então o 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>Na primeira inicialização, uma janela de configuração será aberta para estabelecer a conexão à rede Tor.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integração_à_área_de_trabalho_ubuntu">Integração à área de trabalho Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para adicionar <strong>Tor Browser</strong> no menu de aplicativos :</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>Você pode então:</p> </div> <div class="ulist"> <ul> <li> <p>Lançar <strong>Tor Browser</strong> a partir do menu de aplicativos</p> </li> <li> <p>Adicioná-lo aos favoritos do dock</p> </li> <li> <p>Criar um atalho de teclado se desejado</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_com_tor">Explorar recursos educativos com Tor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor não é apenas uma ferramenta de anonimato. É um portal de acesso a recursos educacionais e de pesquisa, principalmente nas áreas de :</p> </div> <div class="ulist"> <ul> <li> <p><strong>OSINT (Inteligência de Fontes Abertas)</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>Compartilhamento educativo e open source</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(acesso via Tor para mais confidencialidade)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(acessível via Tor)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(acesso à literatura científica livre)</p> </li> <li> <p><strong>Transmissão de conhecimento e compreensão do ser humano na sociedade digital</strong></p> </li> <li> <p>Recursos sobre a cultura digital, a liberdade de expressão e o acesso ao conhecimento</p> </li> <li> <p>Documentação livre sobre cibersegurança e ética das tecnologias</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_atualização_do_tor_browser">Atualização do Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para garantir uma segurança ideal, é crucial manter <strong>Tor Browser</strong> atualizado. O navegador possui um mecanismo de atualização automática que pode ser acionado via linha de comando.</p> </div> <div class="paragraph"> <p>A partir do diretório de instalação do Tor Browser, basta reiniciar o script de inicialização :</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>Ao iniciar, <strong>Tor Browser</strong> verificará automaticamente se existe uma nova versão. Se for o caso, ele a baixará e a instalará para você.</p> </div> <div class="paragraph"> <p>Este método simples garante que você sempre tem os últimos patches de segurança e as melhorias mais recentes, o que é essencial para uma navegação segura.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Verificar os downloads é um reflexo essencial para qualquer pessoa que deseja evoluir em um ambiente digital seguro. Instalar o Tor de forma verificada, é<strong>proteger a sua integridade digital</strong>, <strong>preservar a confiança no software livre</strong>, et <strong>reforçar a sua autonomia informacional</strong>.</p> </div> <div class="paragraph"> <p><strong>A segurança digital é um ato de consciência, não de paranoia.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="summary-diagram.svg" alt="summary diagram" width="522" height="203"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_referências">Referências</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Site oficial do Projeto 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>Documentação de verificação das assinaturas :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>Documentação do Ubuntu:https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>Arquivo 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 artigo faz parte da série <strong>Segurança e Consciência Digital</strong>, visando promover práticas responsáveis e pedagógicas em torno das ferramentas livres</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="#_introdução">Introdução</a></li> <li><a href="#_1_o_catálogo_de_versões_libs_versions_toml_um_lembrete">1. O Catálogo de Versões (<code>libs.versions.toml</code>) : Um lembrete</a></li> <li><a href="#_2_o_problema_um_build_composto_e_dois_mundos_separados">2. O Problema: um Build composto e dois mundos separados</a></li> <li><a href="#_3_a_solução_compartilhar_a_resolução_de_dependências">3. A Solução: Compartilhar a Resolução de Dependências</a></li> <li><a href="#_4_conclusão_a_potência_dos_builds_compostos_bem_gerenciados">4. Conclusão: A Potência dos Builds Compostos Bem Gerenciados</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público-alvo: Desenvolvedores do Gradle lidando com o gerenciamento de dependências em projetos multi-build.</div> <p>Em nossa busca para criar o plugin`site-baker`, tentamos manter uma base de código limpa e centralizada. Uma das melhores práticas no ecossistema Gradle moderno é o uso do<strong>catálogo de versões</strong>(U+200B(U+200B`translate`)(<code>fr</code>)<code>libs.versions.toml</code>) para gerenciar as dependências. Mas o que acontece quando seu projeto se torna mais complexo, como um<strong>construir composto</strong>Onde um build independente (nosso plugin) deve ser incluído em outro?</p> </div> <div class="paragraph"> <p>Foi ali que nossa aventura tomou um rumo inesperado. Nós queríamos que nosso plugin`site-baker`, que é ele próprio um projeto Gradle, utiliza o mesmo catálogo de versões do nosso projeto principal. Este artigo, o quinto da nossa série, conta como resolvemos esse desafio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_o_catálogo_de_versões_libs_versions_toml_um_lembrete">1. O Catálogo de Versões (<code>libs.versions.toml</code>) : Um lembrete</h2> <div class="sectionbody"> <div class="paragraph"> <p>O arquivo`gradle/libs.versions.toml`é uma funcionalidade do Gradle que permite centralizar as versões e as coordenadas das dependências do seu projeto. É geralmente estruturado em quatro seções:</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: Define alias para os números de versão (ex:`kotlin = "1.9.20"`).</p> </li> <li> <p><code>[libraries]</code>: Define alias para as dependências completas, usando as versões definidas acima (ex:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }`).</p> </li> <li> <p><code>[bundles]</code>: Agrupa várias bibliotecas sob um único alias (ex:`jackson = ["jackson-core", "jackson-databind"]`)</p> </li> <li> <p><code>[plugins]</code>: Define aliases para os plugins Gradle.</p> </li> </ul> </div> <div class="paragraph"> <p>Uma vez definido, o Gradle gera automaticamente acessores tipados, o que deixa seu`build.gradle.kts`muito mais legível :</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="460" height="252"> </div> <div class="title">Figure 1. Fluxo de dados do catálogo de versões</div> </div> </div> </div> <div class="sect1"> <h2 id="_2_o_problema_um_build_composto_e_dois_mundos_separados">2. O Problema: um Build composto e dois mundos separados</h2> <div class="sectionbody"> <div class="paragraph"> <p>A nossa estrutura de projeto é um<strong>construir composto</strong>. O projeto principal (<code>thymeleaf.cheroliv.com</code>) inclui o projeto do plugin (<code>site-baker</code>) via o comando`includeBuild("site-baker")<code>no arquivo`settings.gradle.kts</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="composite-build.svg" alt="composite build" width="604" height="246"> </div> <div class="title">Figure 2. Estrutura do build composto</div> </div> <div class="paragraph"> <p>O problema é que, por padrão, um build incluído é um<strong>mundo separado</strong>. Ele tem sua própria configuração, seu próprio ciclo de vida e ele não vê o arquivo`libs.versions.toml`do build principal. Nosso`plugin/build.gradle.kts`tentava usar`libs.plugins.kotlin.jvm`, mas o objeto`libs`não estava sendo gerado a partir do arquivo TOML correto, provocando erros de build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_a_solução_compartilhar_a_resolução_de_dependências">3. A Solução: Compartilhar a Resolução de Dependências</h2> <div class="sectionbody"> <div class="paragraph"> <p>Após várias pesquisas, a solução se revelou ser uma funcionalidade do Gradle projetada precisamente para este caso:`dependencyResolutionManagement`.</p> </div> <div class="paragraph"> <p>No arquivo`settings.gradle.kts` du <strong>construir incluido</strong>(<code>site-baker/settings.gradle.kts</code>), podemos dizer ao Gradle onde encontrar o catálogo de versões a ser usado.</p> </div> <div class="paragraph"> <p>Aqui está a configuração que adicionamos a`site-baker/settings.gradle.kts`(No output, as the input text to translate is empty.)</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>Analisemos a 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 um catálogo de versões que será acessível através do alias`libs`.</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))</code>: É a mágia. Dizemos ao Gradle que a fonte deste catálogo é o arquivo TOML localizado no diretório`gradle` du <strong>projeto pai</strong>(<code>../</code>).</p> </li> </ul> </div> <div class="paragraph"> <p>Com esta configuração, o build`site-baker`sabe agora que ele deve usar o catálogo de versões do projeto principal. O objeto`libs`é gerado corretamente, e as dependências são resolvidas como previsto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_conclusão_a_potência_dos_builds_compostos_bem_gerenciados">4. Conclusão: A Potência dos Builds Compostos Bem Gerenciados</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta experiência foi rica em lições. O catálogo de versões é uma ferramenta fantástica para a manutenibilidade, mas o seu comportamento em cenários de compilações compostas nem sempre é intuitivo.</p> </div> <div class="paragraph"> <p>A chave é lembrar que um build incluído continua sendo um build independente. Para compartilhar configurações como o catálogo de versões, é necessário usar os mecanismos explícitos fornecidos pelo Gradle, como o bloco`dependencyResolutionManagement`dentro de`settings.gradle.kts`.</p> </div> <div class="paragraph"> <p>Ao resolver esse problema, não apenas deixamos nosso build mais limpo, mas também reforçamos a consistência de nosso projeto, garantindo que o plugin e o projeto principal compartilhem uma única fonte de verdade para suas dependências.</p> </div> <div class="paragraph"> <p>No próximo artigo, continuaremos a enriquecer nosso plugin adicionando tarefas mais complexas, agora que nossa gestão de dependências é sólida e 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="#_introdução">Introdução</a></li> <li><a href="#_o_sintoma_builds_fantasma">O Sintoma: Builds Fantasma</a></li> <li><a href="#_a_investigação_o_que_é_o_cache_de_configuração">A Investigação: O que é o Cache de Configuração?</a></li> <li><a href="#_a_causa_do_problema_um_plugin_não_conforme">A Causa do Problema: Um Plugin Não Conforme</a></li> <li><a href="#_a_solução_temporária_desativar_o_cache">A Solução Temporária: Desativar o Cache</a></li> <li><a href="#_a_verdadeira_solução_tornar_o_plugin_compatível">A Verdadeira Solução : Tornar o Plugin Compatível</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><em>Tempo de leitura :</em> 11 minutos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público-alvo: desenvolvedores Gradle que já tenham encontrado comportamentos de build 'mágicos' ou inesperados.</div> <p>Na nossa aventura de criação do plugin`site-baker`, seguimos uma abordagem TDD rigorosa. Cada funcionalidade era testada, validada, e avançávamos com confiança. E então, um dia, o imprevisto chegou. As builds começaram a se comportar de maneira errática. Modificações na lógica do plugin ou nos arquivos de configuração pareciam ser ignoradas, e nossos testes funcionais, antes confiáveis, falhavam sem razão aparente.</p> </div> <div class="paragraph"> <p>Este tipo de problema pode ser incrivelmente frustrante. Ele põe em causa a fiabilidade da ferramenta e a validade do nosso código. Depois de uma sessão de depuração intensa, o culpado foi identificado: o<strong>cache de configuração do Gradle</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_sintoma_builds_fantasma">O Sintoma: Builds Fantasma</h2> <div class="sectionbody"> <div class="paragraph"> <p>O problema se manifestava de várias maneiras :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Eu estava modificando uma cadeia de caracteres em uma tarefa`println`, mas a antiga cadeia continuava a ser exibida em tempo de execução.</p> </li> <li> <p>Eu estava alterando um valor no meu arquivo`managed-jbake-context.yml`, mas o plugin agia como se o arquivo não tivesse sido modificado.</p> </li> <li> <p>Os testes funcionais, que criam projetos de teste on the fly, falhavam porque o plugin não parecia detectar os arquivos de configuração recém-criados.</p> </li> </ol> </div> <div class="paragraph"> <p>Tudo estava acontecendo como se o Gradle estivesse executando uma \"versão fantasma\" do nosso build, ignorando nossas alterações mais recentes.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_investigação_o_que_é_o_cache_de_configuração">A Investigação: O que é o Cache de Configuração?</h2> <div class="sectionbody"> <div class="paragraph"> <p>O cache de configuração é uma funcionalidade relativamente moderna e extremamente poderosa do Gradle, ativada por padrão nas novas versões. Seu objetivo é tornar os builds mais rápidos.</p> </div> <div class="olist arabic"> <div class="title">O princípio é simples:</div> <ol class="arabic"> <li> <p>Na primeira execução, o Gradle executa a fase de<strong>Configuração</strong>(leitura dos`build.gradle.kts`, criação das tarefas, resolução das dependências) e constrói um grafo de tarefas.</p> </li> <li> <p>No final desta fase, Gradle<strong>Serializar este grafo de tarefas</strong>e o coloca em cache.</p> </li> <li> <p>Nas execuções seguintes, se nada tiver mudado (scripts de compilação,<code>gradle.properties</code>, etc.), Gradle<strong>pula completamente a fase de configuração</strong>e reutiliza o grafo de tarefas em cache</p> </li> </ol> </div> <div class="paragraph"> <p>O ganho de tempo é espectacular nos projetos grandes. No entanto, esse desempenho tem um custo: impõe regras rígidas sobre a forma como os plugins devem ser escritos.</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. O ciclo de vida do cache de configuração</div> </div> </div> </div> <div class="sect1"> <h2 id="_a_causa_do_problema_um_plugin_não_conforme">A Causa do Problema: Um Plugin Não Conforme</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nosso plugin`site-baker`violou, sem saber, várias regras do cache de configuração. Para que um grafo de tarefas seja serializável, as tarefas não devem conter referências a objetos complexos como o objeto`Project`ou ler arquivos de forma arbitrária durante a fase de execução.</p> </div> <div class="paragraph"> <p>Nossa principal falha era ler o conteúdo do arquivo YAML diretamente dentro da lógica de execução da tarefa, usando uma referência ao caminho armazenado na nossa extensão. Essa abordagem é incompatível com o cache porque o Gradle não consegue saber se o conteúdo do arquivo mudou se essa leitura não for modelada como uma<strong>entrada de tarefa</strong>(Task Input)</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_temporária_desativar_o_cache">A Solução Temporária: Desativar o Cache</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para nos desbloquear e retomar um comportamento de compilação previsível, a solução mais rápida foi desativar o cache de configuração. Basta adicionar a linha seguinte ao arquivo`gradle.properties`do projeto que usa o plugin (ou, no nosso caso, o projeto de teste)<code>site-baker</code>).</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>Instantaneamente, os builds recuperaram seu comportamento normal. Cada execução reiniciava a fase de configuração e nossas alterações foram levadas em conta.</p> </div> <div class="paragraph"> <p>No entanto, essa é uma solução de contorno, não uma solução duradoura. Ela sacrifica o desempenho e não resolve o problema de fundo do nosso plugin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_verdadeira_solução_tornar_o_plugin_compatível">A Verdadeira Solução : Tornar o Plugin Compatível</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que um plugin seja um bom cidadão do ecossistema Gradle moderno, ele deve ser compatível com o cache de configuração. Isso implica repensar a forma como os dados fluem para nossas tarefas.</p> </div> <div class="paragraph"> <p>A chave é usar as<strong>APIs do provedor</strong>do Gradle. Em vez de passar valores diretos (como um`String` ou un <code>File</code>) às nossas tarefas, devemos passar de`Property<T>`ou alguns`Provider<T>`.</p> </div> <div class="olist arabic"> <div class="title">Aqui está o plano de refatoramento:</div> <ol class="arabic"> <li> <p><strong>Declarar as entradas de tarefas :</strong>A tarefa que analisa o arquivo YAML deve declarar esse arquivo como uma entrada. Usa-se para isso a anotação`@InputFile`.</p> </li> <li> <p><strong>Utilizar as <code>Property</code> e <code>Provider</code> :</strong>O valor de`configFile`será conectada à propriedade`configPath`da nossa extensão DSL. O Gradle assim pode rastrear a origem do dado.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin] (Blank) // No plugin tasks.register<MyTask>("myTask") { configFile.set(extension.configPath.flatMap { project.layout.projectDirectory.file(it) }) } [empty hljs" data-lang="kotlin] (Blank) // No plugin tasks.register<MyTask>("myTask") { configFile.set(extension.configPath.flatMap { project.layout.projectDirectory.file(it) }) } [empty"></code></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="#_introdução">Introdução</a></li> <li><a href="#_o_contexto_nosso_plugin_site_baker">O Contexto: Nosso Plugin `site-baker</a></li> <li><a href="#_2_modelagem_da_configuração_em_kotlin">2. Modelagem da Configuração em Kotlin</a></li> <li><a href="#_3_integração_de_jackson_no_build_gradle_kts">3. Integração de Jackson no `build.gradle.kts</a></li> <li><a href="#_4_a_abordagem_tdd_testando_o_parsing_yaml">4. A Abordagem TDD: Testando o parsing YAML</a> <ul class="sectlevel2"> <li><a href="#_4_1_teste_unitário_mapear_o_yaml_para_objeto_kotlin">4.1. Teste Unitário: Mapear o YAML para Objeto Kotlin</a></li> <li><a href="#_4_2_teste_funcional_validar_a_leitura_do_arquivo_de_configuração">4.2. Teste Funcional: Validar a Leitura do Arquivo de Configuração</a></li> </ul> </li> <li><a href="#_5_visualização_do_fluxo_de_parsing">5. Visualização do Fluxo de Parsing</a></li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público-alvo : Desenvolvedores Gradle intermediários que desejam gerenciar configurações complexas.</div> <p>No desenvolvimento de plugins Gradle, a gestão de configurações complexas é uma tarefa comum. Em vez de sobrecarregar o DSL com centenas de propriedades, costuma ser mais limpo e manutenível definir a configuração em um arquivo externo, como o YAML. Este artigo guia você através da integração da poderosa biblioteca Jackson para analisar arquivos YAML em objetos Kotlin, adotando uma abordagem TDD rigorosa para garantir a robustez do nosso plugin.<code>site-baker</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_contexto_nosso_plugin_site_baker">O Contexto: Nosso Plugin `site-baker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nosso plugin`site-baker`é projetado para automatizar a geração e a implantação de um site estático. Ele precisa ler um arquivo de configuração YAML(<code>managed-jbake-context.yml</code>) para obter informações como os caminhos das fontes, os destinos de implantação e os identificadores Git.</p> </div> <div class="paragraph"> <p>A configuração YAML que queremos analisar é assim:</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_modelagem_da_configuração_em_kotlin">2. Modelagem da Configuração em Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de analisar, devemos definir a estrutura dos nossos dados em Kotlin. Jackson usará estas classes para mapear automaticamente o conteúdo 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>A função`parseSiteConfiguration`é o nosso ponto de entrada para a desserialização. Ela utiliza`ObjectMapper`de Jackson, configurado com`YAMLFactory`para o formato YAML e`registerKotlinModule()`para o suporte às especificidades do Kotlin (como os valores padrão das propriedades).</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_integração_de_jackson_no_build_gradle_kts">3. Integração de Jackson no `build.gradle.kts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para usar o Jackson, devemos adicionar as dependências necessárias no`build.gradle.kts`do nosso 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 o suporte de Kotlin e`jackson-dataformat-yaml`para a gestão do formato YAML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_a_abordagem_tdd_testando_o_parsing_yaml">4. A Abordagem TDD: Testando o parsing YAML</h2> <div class="sectionbody"> <div class="paragraph"> <p>Agora, vamos aplicar o TDD para validar nossa lógica de análise.</p> </div> <div class="sect2"> <h3 id="_4_1_teste_unitário_mapear_o_yaml_para_objeto_kotlin">4.1. Teste Unitário: Mapear o YAML para Objeto Kotlin</h3> <div class="paragraph"> <p>Começamos com um teste unitário em`SiteBakerPluginTest.kt`para verificar que a função`parseSiteConfiguration`pode transformar corretamente uma string YAML em um 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>Este teste lê o conteúdo do arquivo`managed-jbake-context.yml`(que deve existir para que o teste seja válido) e faz asserções sobre o objeto`SiteConfiguration`resultante. Ele valida que os valores-chave do YAML estão corretamente mapeados.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_teste_funcional_validar_a_leitura_do_arquivo_de_configuração">4.2. Teste Funcional: Validar a Leitura do Arquivo de Configuração</h3> <div class="paragraph"> <p>Para garantir que o plugin possa ler o arquivo de configuração via seu DSL e que a análise funcione em um ambiente Gradle real, adicionamos um teste funcional em`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="paragraph"> <p>Este teste é crucial porque simula a execução do plugin em um projeto real. Deve ser<strong>hermético</strong>, isto é, ele deve criar o arquivo por conta própria`managed-jbake-context.yml`com um conteúdo controlado, para garantir a reprodutibilidade e o isolamento do teste</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 teste funcional verifica que o arquivo de configuração copiado para o diretório temporário do teste contém os dados esperados. Embora este teste não faça o parsing diretamente do YAML em um objeto Kotlin, ele valida a presença do arquivo e do seu conteúdo, o que é um passo prévio essencial para o parsing pelo plugin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_visualização_do_fluxo_de_parsing">5. Visualização do Fluxo de Parsing</h2> <div class="sectionbody"> <div class="paragraph"> <p>O diagrama a seguir ilustra o fluxo de dados e as interações durante o parsing da configuração YAML :</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-297b3d98d9a16575dcdb6d07a1077b4f.png" alt="Diagram" width="1534" height="472"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ao seguir uma abordagem TDD, integramos com sucesso a biblioteca Jackson para analisar arquivos de configuração YAML em objetos Kotlin dentro do nosso plugin Gradle. Este método nos permitiu:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Modelar claramente</strong>nossa configuração com classes de dados Kotlin.</p> </li> <li> <p><strong>Validar a lógica de análise</strong>com testes unitários direcionados.</p> </li> <li> <p><strong>Garantir a integração</strong>num ambiente Gradle real graças a testes funcionais herméticos.</p> </li> </ul> </div> <div class="paragraph"> <p>Esta base sólida nos oferece uma grande confiança para estender nosso plugin com funcionalidades que se baseiam nessa configuração, ao mesmo tempo em que garante a manutenibilidade e a robustez do código. O parsing YAML agora é um recurso confiável e testado do nosso plugin`site-baker`.</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="#_a_inicialização_do_projeto">A Inicialização do Projeto</a></li> <li><a href="#_2_nosso_primeiro_ciclo_tdd_registrar_uma_tarefa">2. Nosso Primeiro Ciclo TDD : Registrar uma Tarefa</a> <ul class="sectlevel2"> <li><a href="#_2_1_o_teste_primeiro_o_teste_que_falha">2.1. O teste primeiro (O teste que falha)</a></li> <li><a href="#_2_2_o_código_depois_fazer_passar_o_teste">2.2. O Código Depois (Fazer Passar o Teste)</a></li> </ul> </li> <li><a href="#_3_segundo_ciclo_tdd_adicionar_uma_extensão_dsl">3. Segundo Ciclo TDD : Adicionar uma Extensão DSL</a> <ul class="sectlevel2"> <li><a href="#_3_1_o_teste_primeiro">3.1. O Teste Primeiro</a></li> <li><a href="#_3_2_o_código_depois">3.2. O Código Depois</a></li> </ul> </li> <li><a href="#_4_o_teste_funcional_validar_a_integração">4. O Teste Funcional: Validar a Integração</a> <ul class="sectlevel2"> <li><a href="#_4_1_o_teste_de_integração_criar_um_ambiente_controlado">4.1. O Teste de Integração : Criar um Ambiente Controlado</a></li> <li><a href="#_4_2_finalizar_a_lógica">4.2. Finalizar a Lógica</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Neste artigo, vamos explorar como montar uma base de desenvolvimento sólida para um plugin Gradle usando uma abordagem de Desenvolvimento Orientado por Testes (TDD - Test‑Driven Development). Este método garante que nosso código seja robusto, manutenível e atenda exatamente aos requisitos desde o início.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_inicialização_do_projeto">A Inicialização do Projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle facilita muito a criação de um novo plugin graças ao comando`gradle init`. Ao escolher criar um 'Gradle Plugin' com Kotlin, obtemos uma estrutura de projeto pronta para uso, incluindo dois tipos de testes cruciais :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Testes Unitários :</strong>Localizados em`src/test`, eles permitem validar componentes isolados do nosso plugin, como a lógica interna de uma tarefa ou a configuração de uma extensão. Eles são rápidos e não precisam de uma execução completa do Gradle.</p> </li> <li> <p><strong>Testes Funcionais :</strong>Situados em`src/functionalTest`, eles usam`GradleRunner`para executar uma compilação Gradle completa em um projeto de teste temporário. Isso nos permite verificar o comportamento real do plugin em um ambiente controlado.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_2_nosso_primeiro_ciclo_tdd_registrar_uma_tarefa">2. Nosso Primeiro Ciclo TDD : Registrar uma Tarefa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nossa primeira exigência é simples: o plugin deve registrar uma tarefa nomeada`printSiteConfig`.</p> </div> <div class="sect2"> <h3 id="_2_1_o_teste_primeiro_o_teste_que_falha">2.1. O teste primeiro (O teste que falha)</h3> <div class="paragraph"> <p>Conforme o TDD, escrevemos primeiro um teste que verifica a existência dessa tarefa. Dentro`SiteBakerPluginTest.kt`(nosso arquivo de teste unitário), adicionamos:</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 teste falha porque ainda não escrevemos nenhum código em nosso plugin.</p> </div> </div> <div class="sect2"> <h3 id="_2_2_o_código_depois_fazer_passar_o_teste">2.2. O Código Depois (Fazer Passar o Teste)</h3> <div class="paragraph"> <p>Agora, estamos escrevendo o mínimo de código necessário em`SiteBakerPlugin.kt`para que o teste passe :</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>Nós reiniciamos os testes, e eles passam. Nossa primeira funcionalidade está validada.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_segundo_ciclo_tdd_adicionar_uma_extensão_dsl">3. Segundo Ciclo TDD : Adicionar uma Extensão DSL</h2> <div class="sectionbody"> <div class="paragraph"> <p>O requisito seguinte é permitir que os usuários configurem nosso plugin por meio de um bloco DSL em seu`build.gradle.kts`. Nós queremos um bloco`site { …​ }`onde se pode especificar um caminho de configuração.</p> </div> <div class="sect2"> <h3 id="_3_1_o_teste_primeiro">3.1. O Teste Primeiro</h3> <div class="paragraph"> <p>Adicionamos um teste para verificar que a extensão`site`é bem registrada e pode-se atribuir um valor a ela.</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>Este teste falha porque nem a classe`SiteExtension`nem o registro da extensão existem</p> </div> </div> <div class="sect2"> <h3 id="_3_2_o_código_depois">3.2. O Código Depois</h3> <div class="paragraph"> <p>Nós criamos a classe`SiteBakerExtension.kt`e atualizamos`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>Os testes passam novamente.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_o_teste_funcional_validar_a_integração">4. O Teste Funcional: Validar a Integração</h2> <div class="sectionbody"> <div class="paragraph"> <p>Agora que as unidades estão testadas, precisamos garantir que tudo funcione junto em uma build real. Essa é a função do teste funcional em`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="sect2"> <h3 id="_4_1_o_teste_de_integração_criar_um_ambiente_controlado">4.1. O Teste de Integração : Criar um Ambiente Controlado</h3> <div class="paragraph"> <p>Este teste vai simular um projeto real usando nosso plugin. Para que seja confiável, ele deve ser<strong>hermético</strong>, ou seja, ele não deve depender de arquivos existentes no sistema. Ele deve criar por si mesmo todas as condições necessárias à sua execução.</p> </div> <div class="paragraph"> <p>O teste vai portanto :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Criar um`build.gradle.kts`de teste que utiliza nosso plugin e seu DSL.</p> </li> <li> <p><strong>Criar o arquivo de configuração</strong>(<code>managed-jbake-context.yml</code>) que o plugin deve ler. É uma etapa crucial para a robustez do teste.</p> </li> <li> <p>Executar a tarefa`printSiteConfig`via`GradleRunner`.</p> </li> <li> <p>Verificar que a saída da build está correta.</p> </li> </ol> </div> <div class="paragraph"> <p>Ao copiar ou criar este arquivo de configuração em cada execução, garantimos que o teste esteja<strong>reprodutível</strong>e não depende de um estado externo. Isso protege nossos testes contra regressões que poderiam estar relacionadas à leitura do arquivo.</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 teste falhará enquanto a tarefa`printSiteConfig`Não usará realmente o valor da extensão.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_finalizar_a_lógica">4.2. Finalizar a Lógica</h3> <div class="paragraph"> <p>Estamos atualizando a tarefa em`SiteBakerPlugin.kt`para que ela exiba o 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>Todos os testes, unitários e funcionais, agora passam.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Seguindo uma abordagem TDD, construímos um plugin de forma incremental e segura. Cada pequena funcionalidade é imediatamente validada por um teste, desde testes unitários rápidos até testes funcionais que validam a integração completa.</p> </div> <div class="paragraph"> <p>Ao cuidar de tornar nossos testes funcionais<strong>herméticos</strong>— notadamente ao criar programaticamente os arquivos de configuração necessários — construímos uma rede de segurança extremamente robusta. Essa rigidez nos protege eficazmente contra as regressões e nos dá muita confiança para adicionar funcionalidades mais complexas posteriormente, como a análise do arquivo de configuração YAML.</p> </div> <div class="paragraph"> <p>Esta base de testes sólidos é o ativo mais valioso para a manutenção e evolução futura do 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="#_introdução">Introdução</a></li> <li><a href="#_etapa_1_iniciar_o_assistente_do_projeto">Etapa 1: Iniciar o assistente do projeto</a></li> <li><a href="#_passo_2_compreender_a_estrutura_gerada">Passo 2: Compreender a estrutura gerada</a> <ul class="sectlevel2"> <li><a href="#_arquivos_e_pastas_chave">Arquivos e pastas chave</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público-alvo : Desenvolvedor iniciante a intermediário com Gradle.</div> <p>Iniciar um novo projeto de plugin Gradle pode parecer intimidante. Felizmente, o Gradle fornece um assistente interativo poderoso, a tarefa`init`, que gera uma estrutura de projeto completa, limpa e pronta para uso. Este guia mostrará como usar esta ferramenta para criar uma base de plugin saudável, explicará a estrutura e mostrará como executar as primeiras tarefas de build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_1_iniciar_o_assistente_do_projeto">Etapa 1: Iniciar o assistente do projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>O comando`gradle init`é o ponto de partida. Ele lança um assistente de linha de comando que faz uma série de perguntas para configurar o projeto.</p> </div> <div class="paragraph"> <p>Abra o seu terminal em uma pasta vazia e execute:</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>O assistente o guiará. Aqui estão as escolhas a fazer para um plugin Gradle escrito em Kotlin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Selecione o tipo de projeto a gerar:</strong>Escolha`Gradle plugin`.</p> </li> <li> <p><strong>Selecionar linguagem de implementação:</strong>Escolha`Kotlin`.</p> </li> <li> <p><strong>Selecione o DSL do script de compilação:</strong>Escolha`Kotlin`.</p> </li> <li> <p><strong>Nome do projeto:</strong>Insira um nome para o seu projeto (ex:`site-baker`).</p> </li> <li> <p><strong>ID do Plugin</strong>Dê um identificador único ao seu plugin (ex:`com.cheroliv.site-baker`).</p> </li> <li> <p><strong>Plugin class:</strong>Especifique o nome da classe da implementação (ex:`com.cheroliv.SiteBakerPlugin`)'.'</p> </li> </ol> </div> <div class="paragraph"> <p>Uma vez concluído, o Gradle gera uma árvore de arquivos completa.</p> </div> <div class="imageblock"> <div class="content"> <img src="init-gradle.svg" alt="init gradle" width="193" height="406"> </div> <div class="title">Figure 1. Diagrama do processo de inicialização</div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_compreender_a_estrutura_gerada">Passo 2: Compreender a estrutura gerada</h2> <div class="sectionbody"> <div class="paragraph"> <p>O assistente cria uma estrutura de projeto multi-módulos, separando o projeto raiz do código-fonte do próprio plugin.</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="_arquivos_e_pastas_chave">Arquivos e pastas chave</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts`Este ficheiro na raiz define os módulos incluídos na compilação. Aqui, ele inclui o subprojeto`plugin</code>.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] (No text provided to translate, so output is empty.) rootProject.name = "site-baker include("plugin") ----</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="#_introdução">Introdução</a></li> <li><a href="#_o_jdk_o_motor_do_gradle">O JDK: O motor do Gradle</a> <ul class="sectlevel2"> <li><a href="#_qual_versão_escolher">Qual versão escolher?</a></li> <li><a href="#_instalação_via_sdkman_recomendado">Instalação via SDKMAN! (Recomendado)</a> <ul class="sectlevel3"> <li><a href="#_instalar_sdkman"><strong>Instalar SDKMAN!</strong></a></li> <li><a href="#_instalar_uma_versão_do_jdk"><strong>Instalar uma versão do JDK</strong></a></li> <li><a href="#_verificar_a_instalação">Verificar a instalação</a></li> </ul> </li> </ul> </li> <li><a href="#_2_o_ide_intellij_idea">2. O IDE: IntelliJ IDEA</a></li> <li><a href="#_3_gradle_a_ferramenta_de_build">3. Gradle: A ferramenta de build</a> <ul class="sectlevel2"> <li><a href="#_instalação_via_sdkman">Instalação via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_instalar_gradle">Instalar Gradle</a></li> <li><a href="#_verificar_a_instalação_2">Verificar a instalação</a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_o_gerador_de_site_estático">4. JBake: O gerador de site estático</a> <ul class="sectlevel2"> <li><a href="#_instalação_via_sdkman_2">Instalação via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_instalar_jbake">Instalar JBake</a></li> <li><a href="#_verificar_a_instalação_3"><strong>Verificar a instalação</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_5_o_gradle_wrapper_a_prática_absoluta">5. O Gradle Wrapper: A prática absoluta</a></li> <li><a href="#_6_docker_e_portainer_para_builds_reprodutíveis_opcional">6. Docker e Portainer: Para Builds Reprodutíveis (Opcional)</a> <ul class="sectlevel2"> <li><a href="#_instalação_do_docker_engine">Instalação do Docker Engine</a> <ul class="sectlevel3"> <li><a href="#_instalar_docker_via_o_script_oficial"><strong>Instalar Docker via o script oficial :</strong></a></li> <li><a href="#_gerir_docker_sem_sudo_recomendado">Gerir Docker sem <code>sudo</code> (recomendado):</a></li> </ul> </li> <li><a href="#_gerenciar_docker_com_portainer_gui">Gerenciar Docker com Portainer (GUI)</a> <ul class="sectlevel3"> <li><a href="#_criar_um_volume_para_os_dados_do_portainer">Criar um volume para os dados do Portainer :</a></li> <li><a href="#_iniciar_o_contêiner_portainer">Iniciar o contêiner Portainer :</a></li> </ul> </li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Público-alvo: Desenvolvedores que desejam iniciar a criação de plugins Gradle.</div> <p>Para desenvolver plugins Gradle de forma eficaz, um ambiente de desenvolvimento bem configurado é indispensável. Um bom setup vai economizar tempo, reduzirá as frustrações e garantirá a consistência das suas builds.</p> </div> <div class="paragraph"> <p>Este guia concentra‑se em quatro pilares essenciais:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Le <strong>JDK</strong>(Java Development Kit), pois Gradle e JBake executam-se na JVM.</p> </li> <li> <p>Un <strong>IDE</strong>moderno (IntelliJ IDEA) com bom suporte para Kotlin e Gradle.</p> </li> <li> <p><strong>Gradle</strong>ele mesmo, para inicializar os projetos.</p> </li> <li> <p><strong>JBake</strong>, o motor do nosso site estático.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/gradle-env.svg" alt="gradle env" width="1615" height="5696"> </div> <div class="title">Figure 1. Componentes do ambiente de desenvolvimento</div> </div> </div> </div> <div class="sect1"> <h2 id="_o_jdk_o_motor_do_gradle">O JDK: O motor do Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle é um aplicativo que é executado na Máquina Virtual Java (JVM). Portanto, a instalação de um JDK é um requisito absoluto.</p> </div> <div class="sect2"> <h3 id="_qual_versão_escolher">Qual versão escolher?</h3> <div class="paragraph"> <p>É recomendado usar uma versão LTS (Long-Term Support) do Java. Atualmente,<strong>JDK 17</strong> ou <strong>JDK 21</strong>são excelentes escolhas.</p> </div> </div> <div class="sect2"> <h3 id="_instalação_via_sdkman_recomendado">Instalação via SDKMAN! (Recomendado)</h3> <div class="paragraph"> <p>SDKMAN! é uma ferramenta excelente para gerenciar as versões de muitos SDKs, incluindo Java e 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_uma_versão_do_jdk"><strong>Instalar uma versão do 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_a_instalação">Verificar a instalação</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>Você deve ver a versão que você acabou de instalar ser exibida.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_o_ide_intellij_idea">2. O IDE: IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para o desenvolvimento de plugins Gradle com o DSL Kotlin,<strong>IntelliJ IDEA</strong>é a ferramenta de escolha. A sua integração com Gradle e Kotlin é incomparável.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Edição Community :</strong>gratuita e amplamente suficiente para começar.</p> </li> <li> <p><strong>Edição Definitiva :</strong>Paga, ela oferece funcionalidades avançadas para desenvolvimento web e banco de dados.</p> </li> </ul> </div> <div class="paragraph"> <p>Baixe a versão que lhe convém do site da JetBrains: <a href="https://www.jetbrains.com/idea/download/" class="bare">https://www.jetbrains.com/idea/download/</a></p> </div> <div class="paragraph"> <p>A IDE detectará automaticamente seus arquivos`build.gradle.kts` et <code>settings.gradle.kts</code>, oferecendo autocompletão poderosa, navegação no código e ferramentas de depuração integradas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle_a_ferramenta_de_build">3. Gradle: A ferramenta de build</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mesmo que cada projeto utilizará sua própria versão do Gradle via o Gradle Wrapper, é útil ter uma instalação global do Gradle para tarefas como a inicialização de novos projetos (<code>gradle init</code>).</p> </div> <div class="sect2"> <h3 id="_instalação_via_sdkman">Instalação via SDKMAN!</h3> <div class="paragraph"> <p>Tal como para o JDK, SDKMAN! simplifica a instalação do 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="_verificar_a_instalação_2">Verificar a instalação</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 exibirá as versões do Gradle, Kotlin, Groovy e do JDK usadas.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_o_gerador_de_site_estático">4. JBake: O gerador de site estático</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake é a ferramenta que vamos usar para transformar os nossos ficheiros fontes (como este) num site web estático. Ter uma instalação local é prático para visualizar as mudanças.</p> </div> <div class="sect2"> <h3 id="_instalação_via_sdkman_2">Instalação via SDKMAN!</h3> <div class="paragraph"> <p>Assim como as outras ferramentas, SDKMAN! é o método mais simples.</p> </div> <div class="sect3"> <h4 id="_instalar_jbake">Instalar JBake</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_a_instalação_3"><strong>Verificar a instalação</strong></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 exibirá a versão do JBake e as informações do ambiente Java que ele utiliza.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_o_gradle_wrapper_a_prática_absoluta">5. O Gradle Wrapper: A prática absoluta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depois que seu projeto for criado (o que veremos no próximo artigo), você não deve mais usar o comando global.<code>gradle</code>. Em vez disso, você usará o<strong>Wrapper do Gradle</strong>(<code>./gradlew</code>), um script incluido no seu projeto</p> </div> <div class="paragraph"> <p>Por que?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Reprodutibilidade :</strong>O Wrapper garante que cada pessoa que trabalha no projeto (incluindo o seu servidor de CI/CD) use exatamente a<strong>mesma versão do Gradle</strong>, eliminando assim os erros de build devido a ambientes diferentes</p> </li> <li> <p><strong>Simplicidade:</strong>Não é necessário instalar o Gradle manualmente para contribuir a um projeto.</p> </li> </ul> </div> <div class="paragraph"> <p>Basta clonar o repositório e executar`./gradlew`.</p> </div> <div class="paragraph"> <p>Um comando típico será assim:</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_e_portainer_para_builds_reprodutíveis_opcional">6. Docker e Portainer: Para Builds Reprodutíveis (Opcional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Embora não sejam estritamente necessários para escrever um plugin, Docker e Portainer são ferramentas DevOps modernas que facilitam muito a criação de builds reproduzíveis e o gerenciamento do seu ambiente.</p> </div> <div class="sect2"> <h3 id="_instalação_do_docker_engine">Instalação do Docker Engine</h3> <div class="paragraph"> <p>O Docker permite que você empacote sua aplicação e suas dependências em um contêiner.</p> </div> <div class="sect3"> <h4 id="_instalar_docker_via_o_script_oficial"><strong>Instalar Docker via o 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="_gerir_docker_sem_sudo_recomendado">Gerir Docker sem <code>sudo</code> (recomendado):</h4> <div class="paragraph"> <p>Adicione seu usuário ao 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="_gerenciar_docker_com_portainer_gui">Gerenciar Docker com Portainer (GUI)</h3> <div class="paragraph"> <p>Portainer é uma interface web leve para gerenciar seus contêineres Docker.</p> </div> <div class="sect3"> <h4 id="_criar_um_volume_para_os_dados_do_portainer">Criar um volume para os dados do 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_o_contêiner_portainer">Iniciar o contêiner 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>Você pode agora acessar a interface do Portainer em`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Seu ambiente está agora pronto! Você dispõe de um JDK, do IDE mais adequado, do Gradle e do JBake. Com a adição do Docker, você também está pronto para criar builds contêinerizados e reproduzíveis. Esta base sólida permitirá que você se concentre no essencial: o desenvolvimento de plugins poderosos e úteis.</p> </div> <div class="paragraph"> <p>No próximo artigo, utilizaremos o comando`gradle init`para gerar a estrutura do nosso primeiro projeto 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="#_integração_com_poetry">Integração com Poetry</a> <ul class="sectlevel2"> <li><a href="#_instalação_do_poetry">Instalação do Poetry</a></li> <li><a href="#_inicialização_do_projeto">Inicialização do projeto</a></li> <li><a href="#_adição_e_instalação_de_dependências">Adição e instalação de dependências</a></li> <li><a href="#_publicação_com_poetry">Publicação com Poetry</a></li> </ul> </li> <li><a href="#_builds_reprodutíveis_com_docker">Builds reprodutíveis com Docker</a> <ul class="sectlevel2"> <li><a href="#_exemplo_de_dockerfile">Exemplo de Dockerfile</a></li> <li><a href="#_integração_no_github_actions">Integração no GitHub Actions</a></li> </ul> </li> <li><a href="#_publicação_condicional">Publicação condicional</a></li> <li><a href="#_automatização_das_dependências_com_renovate_e_dependabot">Automatização das dependências com Renovate e 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_avançado">Caso de Uso – CI/CD avançado</a></li> <li><a href="#_sequência_publicação_condicional">Sequência – Publicação condicional</a></li> <li><a href="#_estados_pipeline_cicd">Estados – Pipeline CI/CD</a></li> <li><a href="#_implantação_arquitetura_cicd">Implantação – Arquitetura CI/CD</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Nas duas primeiras partes desta série, nós temos : - Estabeleci um pipeline CI/CD funcional para uma aplicação Python com GitHub Actions e PyPI. - Industrializamos este pipeline com testes multi-versão, uma publicação progressiva via Test PyPI e ferramentas de qualidade e segurança.</p> </div> <div class="paragraph"> <p>Nesta terceira parte, vamos ir<strong>além da simples publicação no PyPI</strong>para construir uma cadeia de CI/CD completa, robusta e profissional com : - <strong>Poesia</strong>para uma embalagem moderna e uma gestão otimizada das dependências. - <strong>Docker</strong>para criar builds reproduzíveis e multi-plataformas - <strong>Publicação condicional</strong>para gerenciar cenários como os release candidates. - <strong>Ferramentas de automação</strong>(Renovate, Dependabot) para manter o pipeline atualizado sem esforço.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integração_com_poetry">Integração com Poetry</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry substitui as antigas ferramentas de empacotamento (setup.py, requirements.txt) ao centralizar a gestão das dependências e da construção em`pyproject.toml`.</p> </div> <div class="sect2"> <h3 id="_instalação_do_poetry">Instalação do 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="_inicialização_do_projeto">Inicialização do projeto</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>Isso gera um arquivo`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="_adição_e_instalação_de_dependências">Adição e instalação de dependências</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="_publicação_com_poetry">Publicação com Poetry</h3> <div class="paragraph"> <p>Poetry lida nativamente com a publicação :</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 usa automaticamente as informações presentes em`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_builds_reprodutíveis_com_docker">Builds reprodutíveis com Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para garantir execuções idênticas em desenvolvimento, CI/CD e produção, o Docker integra-se perfeitamente com a Poetry.</p> </div> <div class="sect2"> <h3 id="_exemplo_de_dockerfile">Exemplo 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>Isso garante: - Um ambiente Python congelado. - Dependências bloqueadas via`poetry.lock`. - Uma imagem executável em qualquer sistema que suporte o Docker.</p> </div> </div> <div class="sect2"> <h3 id="_integração_no_github_actions">Integração no 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="_publicação_condicional">Publicação condicional</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em um pipeline profissional, é preciso poder publicar apenas em alguns casos: - Release candidates para o Test PyPI. - Versões estáveis para o PyPI. - Dispara construções do Docker apenas 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>Esta abordagem evita publicações acidentais.</p> </div> </div> </div> <div class="sect1"> <h2 id="_automatização_das_dependências_com_renovate_e_dependabot">Automatização das dependências com Renovate e Dependabot</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para evitar que suas dependências se tornem obsoletas, integre ferramentas de atualização 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 todas as semanas para atualizar as dependências do Python e do 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 um controle mais fino: agrupamento de dependências, planejamento e regras avançadas.</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_avançado">Caso de Uso – CI/CD avançado</h3> <div class="imageblock"> <div class="content"> <img src="images/usecase-cicd.svg" alt="usecase cicd" width="819" height="317"> </div> </div> </div> <div class="sect2"> <h3 id="_sequência_publicação_condicional">Sequência – Publicação 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="_implantação_arquitetura_cicd">Implantação – Arquitetura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/deployment-cicd.svg" alt="deployment cicd" width="1587" height="5604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nesta terceira parte, vimos como : - Modernizar o empacotamento Python com Poetry. - Garantir builds reproduzíveis via Docker. Implementar uma publicação condicional. - Automatizar a atualização das dependências.</p> </div> <div class="paragraph"> <p>Você agora tem um pipeline CI/CD<strong>completo, industrializado e seguro</strong>, pronto para evoluir com seus projetos.</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="#_introdução">Introdução</a></li> <li><a href="#_arquitetura_do_pipeline_cicd">Arquitetura do Pipeline CI/CD</a></li> <li><a href="#_estrutura_do_projeto">Estrutura do Projeto</a></li> <li><a href="#_configuração_do_pacote_com_pyproject_toml">Configuração do Pacote com pyproject.toml</a></li> <li><a href="#_workflow_de_cicd_testes_e_qualidade">Workflow de CI/CD - Testes e Qualidade</a></li> <li><a href="#_workflow_de_lançamento_e_implantação">Workflow de Lançamento e Implantação</a></li> <li><a href="#_diagramas_de_arquitetura">Diagramas de Arquitetura</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_sequência_processo_de_lançamento">Diagrama de Sequência - Processo de Lançamento</a></li> <li><a href="#_diagrama_de_estados_ciclo_de_vida_do_pacote">Diagrama de estados - ciclo de vida do pacote</a></li> <li><a href="#_diagrama_de_implantação_infraestrutura_cicd">Diagrama de Implantação - Infraestrutura CI/CD</a></li> </ul> </li> <li><a href="#_objetos_e_modelos_do_pipeline">Objetos e Modelos do Pipeline</a> <ul class="sectlevel2"> <li><a href="#_diagrama_de_classes_modelos_cicd">Diagrama de Classes - Modelos CI/CD</a></li> </ul> </li> <li><a href="#_configuração_dos_segredos">Configuração dos Segredos</a> <ul class="sectlevel2"> <li><a href="#_segredos_github_actions">Segredos GitHub Actions</a></li> <li><a href="#_geração_de_tokens_pypi">Geração de Tokens PyPI</a></li> </ul> </li> <li><a href="#_scripts_de_desenvolvimento_local">Scripts de Desenvolvimento Local</a> <ul class="sectlevel2"> <li><a href="#_makefile">Makefile</a></li> <li><a href="#_script_de_versão">Script de Versão</a></li> </ul> </li> <li><a href="#_boas_práticas_e_recomendações">Boas práticas e recomendações</a> <ul class="sectlevel2"> <li><a href="#_versionamento_semântico">Versionamento Semântico</a></li> <li><a href="#_estratégia_de_ramificação">Estratégia de ramificação</a></li> <li><a href="#_testes_e_cobertura">Testes e Cobertura</a></li> <li><a href="#_segurança">Segurança</a></li> </ul> </li> <li><a href="#_monitoramento_e_observabilidade">Monitoramento e Observabilidade</a> <ul class="sectlevel2"> <li><a href="#_métricas_do_pipeline">Métricas do Pipeline</a></li> <li><a href="#_notificações">Notificações</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_recursos_complementares">Recursos Complementares</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objetivo : Transformar um pipeline simples em um pipeline industrial robusto, respeitando os padrões modernos de empacotamento e engenharia de software.</div> <p>Na primeira parte desta série, construímos um pipeline CI/CD simples mas eficaz para automatizar os testes e a publicação de um pacote Python no PyPI.</p> </div> <div class="paragraph"> <p>Agora é hora de profissionalizar este pipeline. Nesta segunda parte, vamos:</p> </div> <div class="ulist"> <ul> <li> <p>Migrar para o padrão moderno pyproject.toml,</p> </li> <li> <p>Adicionar ferramentas de qualidade e segurança (Black, Mypy, Bandit, Safety),</p> </li> <li> <p>Implementar testes multi-versão,</p> </li> <li> <p>Integrar um lançamento gradual via Test PyPI,</p> </li> <li> <p>Automatizar o versionamento e melhorar o monitoramento do pipeline.</p> </li> </ul> </div> <div class="paragraph"> <p>Prepare-se para passar de um pipeline funcional para uma infraestrutura CI/CD profissional.</p> </div> <div class="paragraph"> <p>Implantar uma aplicação Python no PyPI requer um pipeline CI/CD robusto que automatiza os testes, a construção e a publicação dos pacotes. Este artigo detalha a implementação de um pipeline completo usando GitHub Actions para uma aplicação CLI Python, baseando-se nas boas práticas do ecossistema Python moderno.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_do_pipeline_cicd">Arquitetura do Pipeline CI/CD</h2> <div class="sectionbody"> <div class="paragraph"> <p>O pipeline que vamos construir segue uma abordagem em várias etapas :</p> </div> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-bb11d40b5f9697204efc20606623b3ef.png" alt="Diagram" width="1065" height="604"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estrutura_do_projeto">Estrutura do Projeto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Uma aplicação CLI Python pronta para distribuição deve seguir uma estrutura padronizada :</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="_configuração_do_pacote_com_pyproject_toml">Configuração do Pacote com pyproject.toml</h2> <div class="sectionbody"> <div class="paragraph"> <p>O arquivo`pyproject.toml`é o padrão moderno para configurar pacotes 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="_workflow_de_cicd_testes_e_qualidade">Workflow de CI/CD - Testes e Qualidade</h2> <div class="sectionbody"> <div class="paragraph"> <p>O fluxo de trabalho principal`ci.yml`) executa os testes em várias versões do 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_lançamento_e_implantação">Workflow de Lançamento e Implantação</h2> <div class="sectionbody"> <div class="paragraph"> <p>O workflow de release (<code>release.yml</code>) gerencia a publicação automática no 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_arquitetura">Diagramas de Arquitetura</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_sequência_processo_de_lançamento">Diagrama de Sequência - Processo de Lançamento</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-f01a09414cc7d19d59813f2a5bed8b09.png" alt="Diagram" width="968" height="832"> </div> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_estados_ciclo_de_vida_do_pacote">Diagrama de estados - ciclo de vida do pacote</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-d2c05f6df902032b6369e62a5f189875.png" alt="Diagram" width="525" height="740"> </div> </div> </div> <div class="sect2"> <h3 id="_diagrama_de_implantação_infraestrutura_cicd">Diagrama de Implantação - Infraestrutura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-a9f28ad3f4c86f1d4598d2a2170bbd87.png" alt="Diagram" width="734" height="604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_objetos_e_modelos_do_pipeline">Objetos e Modelos do Pipeline</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagrama_de_classes_modelos_cicd">Diagrama de Classes - Modelos CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-afca7b13fea2484559ca99543b4a540a.png" alt="Diagram" width="814" height="635"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuração_dos_segredos">Configuração dos Segredos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para que o pipeline funcione, você deve configurar os seguintes segredos no GitHub</p> </div> <div class="sect2"> <h3 id="_segredos_github_actions">Segredos 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="_geração_de_tokens_pypi">Geração de 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_desenvolvimento_local">Scripts de Desenvolvimento Local</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para facilitar o desenvolvimento, crie scripts utilitários:</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="_script_de_versão">Script de Versão</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="_boas_práticas_e_recomendações">Boas práticas e recomendações</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_versionamento_semântico">Versionamento Semântico</h3> <div class="paragraph"> <p>Utilize o versionamento 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>: alterações incompatíveis</p> </li> <li> <p>`MINOR`novas funcionalidades compatíveis</p> </li> <li> <p><code>PATCH</code>: correções de bugs compatíveis</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_estratégia_de_ramificação">Estratégia de ramificação</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="_testes_e_cobertura">Testes e Cobertura</h3> <div class="ulist"> <ul> <li> <p>Cobertura mínima de código: 85%</p> </li> <li> <p>Testes unitários para a lógica de negócio</p> </li> <li> <p>Testes de integração para os adaptadores</p> </li> <li> <p>Testes de ponta a ponta para as CLI</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_segurança">Segurança</h3> <div class="ulist"> <ul> <li> <p>Escaneamento automático de dependências (Safety)</p> </li> <li> <p>Análise estática do código (Bandit)</p> </li> <li> <p>Segredos nunca no código</p> </li> <li> <p>Utilização de tokens PyPI específicos</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoramento_e_observabilidade">Monitoramento e Observabilidade</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_métricas_do_pipeline">Métricas do 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="_notificações">Notificações</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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este pipeline CI/CD completo para Python oferece :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Automação completa</strong>: da validação do código à publicação</p> </li> <li> <p><strong>Segurança</strong>: digitalizações automáticas e gestão segura dos segredos</p> </li> <li> <p><strong>Qualidade</strong>testes multi-versões, linting e cobertura de código</p> </li> <li> <p><strong>Fiabilidade</strong>implementação gradual via Test PyPI</p> </li> <li> <p><strong>Traçabilidade</strong>: artefatos, relatórios e lançamentos GitHub</p> </li> </ul> </div> <div class="paragraph"> <p>A adoção dessas práticas garante um processo de entrega robusto e profissional para suas aplicações Python CLI, facilitando a manutenção e a evolução de seus projetos a longo prazo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_recursos_complementares">Recursos Complementares</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://packaging.python.org/">Python Packaging User Guide</a></p> </li> <li> <p><a href="https://docs.github.com/en/actions">Documentação do GitHub Actions</a></p> </li> <li> <p><a href="https://pypi.org/help/">Documentação de Ajuda do PyPI</a></p> </li> <li> <p><a href="https://semver.org/">Especificação de Versionamento Semântico</a></p> </li> <li> <p><a href="https://keepachangelog.com/">Mantenha um changelog</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="#_introdução">Introdução</a></li> <li><a href="#_arquitetura_do_pipeline">Arquitetura do Pipeline</a></li> <li><a href="#_configuração_do_pipeline_de_integração_contínua_ci">Configuração do Pipeline de Integração Contínua (CI)</a> <ul class="sectlevel2"> <li><a href="#_estrutura_do_workflow_ci">Estrutura do workflow CI</a></li> <li><a href="#_análise_das_etapas_ci">Análise das Etapas CI</a> <ul class="sectlevel3"> <li><a href="#_gatilhos_on">Gatilhos (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objetivo : Acompanhar o leitor na implementação de um pipeline CI/CD minimalista, mas funcional, para uma aplicação Python, com implantação automática no PyPI.</div> <p>A automação dos processos de desenvolvimento tornou-se indispensável nos projetos modernos. Um pipeline CI/CD bem projetado permite não apenas detectar as regressões cedo no ciclo de desenvolvimento, mas também automatizar totalmente o processo de implantação.</p> </div> <div class="paragraph"> <p>Neste artigo, vamos explorar como configurar um pipeline completo com GitHub Actions para uma aplicação Python, da integração contínua (CI) à implantação contínua (CD) no PyPI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_do_pipeline">Arquitetura do Pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nosso pipeline consiste em dois fluxos de trabalho distintos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Pipeline CI</strong>: executado em cada push e pull request</p> </li> <li> <p><strong>Pipeline CD</strong>Acionado apenas nas releases do GitHub</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/ci-cd-overview.svg" alt="ci cd overview" width="1601" height="5132"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuração_do_pipeline_de_integração_contínua_ci">Configuração do Pipeline de Integração Contínua (CI)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estrutura_do_workflow_ci">Estrutura do workflow CI</h3> <div class="paragraph"> <p>O fluxo de trabalho CI é projetado para validar cada contribuição ao código. Eis a sua configuração 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álise_das_etapas_ci">Análise das Etapas CI</h3> <div class="sect3"> <h4 id="_gatilhos_on">Gatilhos (<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 ---- O pipeline é disparado em: - Cada push na branch`main` - Cada pull request para`main` Esta abordagem garante que o código principal permaneça estável e que toda contribuição seja validada antes da integração. ==== 2. Ambiente de Execução ---- runs-on: ubuntu-latest Ubuntu Latest oferece um bom equilíbrio entre desempenho, custo e compatibilidade para a maioria dos projetos Python. ==== 3. Checkout do Código ```yaml ---- ---- - name: Checkout code uses: actions/checkout@v4 ---- A ação`checkout@v4`Recupera o código-fonte do repositório. A versão v4 traz melhorias de desempenho e de segurança. ==== 4. Configuração Python ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' O uso de`'3.x'`permite usar automaticamente a última versão estável do Python 3, simplificando a manutenção. ==== 5. Instalação das Dependências ```yaml ---- ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- Esta etapa: - Atualiza o pip para a última versão - Instala as dependências do projeto - Adiciona as ferramentas de desenvolvimento (linting e testes) ==== 6. Linting com Ruff ---- - name: Run Linting (Ruff) run: ruff check . **Ruff**é um linter Python ultra-rápido escrito em Rust. Ele combina as funcionalidades de várias ferramentas (Flake8, Black, isort) em uma única ferramenta performante. ==== 7. Execução dos Testes ```yaml ---- ---- - name: Run Tests (Pytest) run: pytest ---- O Pytest executa todo o conjunto de testes, garantindo que as alterações não introduzam regressões. == Configuração do Pipeline de Implantação (CD) === Estrutura do Workflow CD O workflow CD é acionado apenas durante os releases do GitHub e automatiza a publicação no 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álise das Etapas CD ==== 1. Gatilho Release ---- on: release: types: - published O pipeline CD é acionado apenas quando uma release do GitHub é publicada. Essa abordagem garante um controle preciso das implantações. ==== 2. Instalação das Ferramentas de Build ```yaml ---- ---- pip install setuptools wheel twine ---- - **setuptools**: Ferramentas de empacotamento Python - **roda**: Formato de distribuição Python moderno - **barbante**Ferramenta segura para fazer upload para o PyPI ==== 3. Configuração da Autenticação ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} A autenticação utiliza um token de API PyPI armazenado como segredo GitHub, mais seguro que as credenciais tradicionais. ==== 4. Build e Publicação ```yaml ---- ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: Crie uma distribuição fonte - `bdist_wheel`Cria uma wheel (distribuição binária) - `twine upload`Publica as distribuições no PyPI == Configuração do Pacote Python === Estrutura do setup.py Para que o pipeline funcione, seu projeto deve incluir um arquivo`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", ], }, ) ---- === Pontos-chave do setup.py 1. **Metadados**: Nome, versão, autor, descrição 2. **Dependências**Lista de pacotes necessários 3. **Pontos de entrada**: Comandos CLI expostos 4. **Classificadores**: Metadados para PyPI == Segurança com os GitHub Secrets === Configuração do Token PyPI 1. **Criar um token API no PyPI** : - Conecte-se ao PyPI - Vá para Account Settings > API tokens - Crie um novo token com as permissões adequadas 1. **Adicionar o segredo no GitHub**: - Configurações do repositório > Segredos e variáveis > Ações - Crie um novo segredo chamado`PYPI_API_TOKEN` - Cole seu token PyPI [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "Repositório 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 ---- == Workflow de Implantação Completa === Sequência de Implantação [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 "Utilizadores finais" 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 do 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 ---- == Boas Práticas e Otimizações === Gestão de Versões Use tags Git semânticos: ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 === 2. Testes de matriz Para testar em várias versões do Python : ```yaml ---- ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. Cache de dependências Acelere os builds com o cache: ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} === 4. Ambientes de Implantação Use os ambientes GitHub para implantações controladas: ```yaml ---- ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == Caso de Uso e Arquitetura === Diagrama de Casos de Uso [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "desenvolvedor" as dev actor "Ações do GitHub" as ga actor "Usuário Final" as user package "Sistema CI/CD" { usecase "Executar Linting" as lint usecase "Executar testes" as test usecase "Construir Pacote" as build usecase "Publicar no PyPI" as publish usecase "Criar Lançamento" 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 ---- === Arquitetura de Implantação [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "GitHub" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "pipeline 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 ---- == Monitorização e Depuração === Logs e Monitoring GitHub Actions fornece logs detalhados para cada etapa. Para depurar : 1. **Examine os logs**de cada step 2. **Ative o debug**com`ACTIONS_STEP_DEBUG` 3. **Use artefatos**para salvar os arquivos de build ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ === Notificações Adicione notificações do Slack ou e‑mail : ```yaml ---- ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == Conclusão A implementação de um pipeline CI/CD robusto com GitHub Actions transforma radicalmente a experiência de desenvolvimento. Ao automatizar o linting, os testes e a implantação, você : - **Reduza os erros**em produção - **Acelere os ciclos**de desenvolvimento - **Melhore a confiança**em seus releases - **Facilite a colaboração**em equipe Este pipeline pode ser adaptado a diferentes tipos de projetos Python ajustando as ferramentas de linting, os frameworks de teste ou os destinos de implantação. O investimento inicial na configuração desses fluxos de trabalho é rapidamente amortizado pelo ganho de tempo e pela redução de erros manuais durante as implantações. == Recursos complementares - https://docs.github.com/en/actions[Documentação GitHub Actions] - https://packaging.python.org/[Guia de Empacotamento do Python] - https://docs.pytest.org/[Documentação Pytest] - https://docs.astral.sh/ruff/[Documentação Ruff] - https://twine.readthedocs.io/[Documentação Twine] ✅ Pipeline funcional alcançado! Você agora tem um pipeline CI/CD simples que permite automatizar seus testes e publicar seu pacote Python no PyPI diretamente do GitHub Actions. No entanto, este pipeline permanece intencionalmente minimalista. Ainda não cobre alguns aspectos essenciais em um contexto profissional : Testes multi-versões do Python, Análise automática de segurança, Implantação progressiva via Test PyPI, Monitoramento e métricas do pipeline, Automatização do versioning e integração das boas práticas modernas (pyproject.toml). Na próxima parte, vamos passar para o próximo nível. Você aprenderá a transformar esse pipeline básico em uma verdadeira cadeia de implantação industrial, robusta e segura, pronta para projetos Python de produção. ----</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="#_introdução">Introdução</a></li> <li><a href="#_contexto_e_desafios_atuais">Contexto e Desafios Atuais</a> <ul class="sectlevel2"> <li><a href="#_evolução_das_apis_musicais">Evolução das APIs Musicais</a></li> <li><a href="#_abordagem_de_desenvolvimento_orientado_por_logs">Abordagem de desenvolvimento orientado por logs</a></li> </ul> </li> <li><a href="#_arquitetura_conceitual">Arquitetura Conceitual</a></li> <li><a href="#_pilha_técnica_e_paradigma_funcional">Pilha Técnica e Paradigma Funcional</a> <ul class="sectlevel2"> <li><a href="#_escolha_tecnológicos">Escolha Tecnológicos</a></li> <li><a href="#_princípios_funcionais_aplicados">Princípios Funcionais Aplicados</a></li> </ul> </li> <li><a href="#_metodologia_ágil_e_backlog">Metodologia Ágil e Backlog</a> <ul class="sectlevel2"> <li><a href="#_épicas_principais">Épicas Principais</a> <ul class="sectlevel3"> <li><a href="#_épico_1_infraestrutura_bot_discord">Épico 1: Infraestrutura Bot Discord</a></li> <li><a href="#_épico_2_integração_spotify">Épico 2: Integração Spotify</a></li> <li><a href="#_epic_3_integração_youtube">Epic 3: Integração YouTube</a></li> <li><a href="#_épico_4_funcionalidades_musicais">Épico 4 : Funcionalidades Musicais</a></li> </ul> </li> <li><a href="#_histórias_de_usuário_detalhadas">Histórias de Usuário Detalhadas</a> <ul class="sectlevel3"> <li><a href="#_us1_1_inicialização_do_bot">US1.1 : Inicialização do Bot</a></li> <li><a href="#_us2_1_pesquisa_spotify_inteligente">US2.1 : Pesquisa Spotify Inteligente</a></li> <li><a href="#_us3_1_extração_resiliente_do_youtube">US3.1 : Extração Resiliente do YouTube</a></li> </ul> </li> </ul> </li> <li><a href="#_abordagem_log_driven_development">Abordagem Log Driven Development</a> <ul class="sectlevel2"> <li><a href="#_estratégia_de_logging">Estratégia de Logging</a></li> <li><a href="#_estrutura_dos_logs">Estrutura dos logs</a></li> <li><a href="#_exemplo_de_log_design">Exemplo de Log Design</a></li> </ul> </li> <li><a href="#_arquitetura_de_validação_com_pydantic">Arquitetura de Validação com Pydantic</a> <ul class="sectlevel2"> <li><a href="#_modelos_de_dados">Modelos de Dados</a></li> </ul> </li> <li><a href="#_gestão_funcional_de_erros">Gestão Funcional de Erros</a> <ul class="sectlevel2"> <li><a href="#_monads_e_tratamento_de_erros">Monads e Tratamento de Erros</a></li> </ul> </li> <li><a href="#_estratégia_de_contorno_das_restrições">Estratégia de Contorno das Restrições</a> <ul class="sectlevel2"> <li><a href="#_abordagem_multi_fonte">Abordagem Multi-Fonte</a></li> </ul> </li> <li><a href="#_plano_de_desenvolvimento_iterativo">Plano de Desenvolvimento Iterativo</a> <ul class="sectlevel2"> <li><a href="#_planejamento_do_sprint">Planejamento do Sprint</a></li> <li><a href="#_métricas_de_qualidade">Métricas de Qualidade</a></li> </ul> </li> <li><a href="#_implantação_e_monitoramento">Implantação e Monitoramento</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_de_produção">Arquitetura de Produção</a></li> <li><a href="#_monitoramento_proativo">Monitoramento Proativo</a></li> </ul> </li> <li><a href="#_conclusão_e_perspectivas">Conclusão e Perspectivas</a> <ul class="sectlevel2"> <li><a href="#_próximas_etapas">Próximas Etapas</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introdução"><a class="anchor" href="#_introdução"></a>Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>O desenvolvimento de um bot Discord que integra as APIs do Spotify e do YouTube representa um desafio técnico moderno, especialmente diante das recentes restrições e evoluções das plataformas. Este artigo apresenta uma abordagem metodológica baseada em<strong>Log Driven Development</strong>(LDD), uma extensão do Test Driven Development, aplicada em um paradigma funcional com Python.</p> </div> <div class="paragraph"> <p>Nosso objetivo: criar um bot robusto, mantível e evolutivo, capaz de navegar as restrições atuais das APIs musicais, oferecendo uma experiência de usuário fluida no Discord.</p> </div> </div> </div> <div class="sect1"> <h2 id="_contexto_e_desafios_atuais"><a class="anchor" href="#_contexto_e_desafios_atuais"></a>Contexto e Desafios Atuais</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_evolução_das_apis_musicais"><a class="anchor" href="#_evolução_das_apis_musicais"></a>Evolução das APIs Musicais</h3> <div class="paragraph"> <p>As plataformas musicais endureceram significativamente suas políticas de acesso:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Spotify</strong>Restrições ao acesso aos metadados, limitação das cotas</p> </li> <li> <p><strong>YouTube</strong>Política anti-bot reforçada, complexificação da autenticação</p> </li> <li> <p><strong>Discord</strong>Novas exigências de segurança e desempenho</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_abordagem_de_desenvolvimento_orientado_por_logs"><a class="anchor" href="#_abordagem_de_desenvolvimento_orientado_por_logs"></a>Abordagem de desenvolvimento orientado por logs</h3> <div class="paragraph"> <p>O LDD estende o TDD colocando os logs no coração do desenvolvimento:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Definição dos logs</strong>antes da implementação</p> </li> <li> <p><strong>Validação por observação</strong>comportamentos esperados</p> </li> <li> <p><strong>Rastreabilidade completa</strong>fluxos de dados</p> </li> <li> <p><strong>Depuração proativa</strong>por antecipação dos erros</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_conceitual"><a class="anchor" href="#_arquitetura_conceitual"></a>Arquitetura Conceitual</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-4115ce5d8e4bc3a41d4c3f0aa7c225f4.png" alt="Diagram" width="777" height="618"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pilha_técnica_e_paradigma_funcional"><a class="anchor" href="#_pilha_técnica_e_paradigma_funcional"></a>Pilha Técnica e Paradigma Funcional</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_escolha_tecnológicos"><a class="anchor" href="#_escolha_tecnológicos"></a>Escolha Tecnológicos</h3> <div class="paragraph"> <p>A nossa stack gira em torno da programação funcional:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>Gerenciamento dos efeitos colaterais e composição de funções</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>Validação de dados type-safe e serialização</p> </dd> <dt class="hdlist1"><strong>Asyncio</strong></dt> <dd> <p>Programação assíncrona para as APIs</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>Log estruturado para o LDD</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_princípios_funcionais_aplicados"><a class="anchor" href="#_princípios_funcionais_aplicados"></a>Princípios Funcionais Aplicados</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-233a7e835b20230b1ab00ec0ea9eca96.png" alt="Diagram" width="703" height="554"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_metodologia_ágil_e_backlog"><a class="anchor" href="#_metodologia_ágil_e_backlog"></a>Metodologia Ágil e Backlog</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_épicas_principais"><a class="anchor" href="#_épicas_principais"></a>Épicas Principais</h3> <div class="paragraph"> <p>Nosso desenvolvimento se organiza em torno de 4 épicos maiores:</p> </div> <div class="sect3"> <h4 id="_épico_1_infraestrutura_bot_discord"><a class="anchor" href="#_épico_1_infraestrutura_bot_discord"></a>Épico 1: Infraestrutura Bot Discord</h4> <div class="paragraph"> <p><strong>Valor de negócio</strong> : Base sólida e extensível</p> </div> <div class="paragraph"> <p><strong>Critérios de aceitação</strong> - Conexão Discord estável com gerenciamento de reconexão - Sistema de comandos modular - Logging estruturado integrado - Tratamento centralizado de erros</p> </div> </div> <div class="sect3"> <h4 id="_épico_2_integração_spotify"><a class="anchor" href="#_épico_2_integração_spotify"></a>Épico 2: Integração Spotify</h4> <div class="paragraph"> <p><strong>Valor de negócio</strong> : Acesso aos metadados musicais</p> </div> <div class="paragraph"> <p>Critérios de aceitação - Autenticação OAuth2 segura - Pesquisa de faixas com cache inteligente Gestão de cotas de API - Fallback em caso de erros de rede</p> </div> </div> <div class="sect3"> <h4 id="_epic_3_integração_youtube"><a class="anchor" href="#_epic_3_integração_youtube"></a>Epic 3: Integração YouTube</h4> <div class="paragraph"> <p><strong>Valor de negócio</strong> : Acesso ao conteúdo de áudio</p> </div> <div class="paragraph"> <p><strong>Critérios de aceitação</strong>: Contorno legal das restrições Extração de áudio otimizada Gerenciamento de vídeos privados/excluídos - Respeito das ToS do YouTube</p> </div> </div> <div class="sect3"> <h4 id="_épico_4_funcionalidades_musicais"><a class="anchor" href="#_épico_4_funcionalidades_musicais"></a>Épico 4 : Funcionalidades Musicais</h4> <div class="paragraph"> <p><strong>Valor de Negócio</strong>: Experiência de usuário completa</p> </div> <div class="paragraph"> <p><strong>Critérios de aceitação</strong> : - Leitura de áudio de alta qualidade - Fila de leitura inteligente - Comandos de voz Discord - Sincronização multiplataforma</p> </div> </div> </div> <div class="sect2"> <h3 id="_histórias_de_usuário_detalhadas"><a class="anchor" href="#_histórias_de_usuário_detalhadas"></a>Histórias de Usuário Detalhadas</h3> <div class="sect3"> <h4 id="_us1_1_inicialização_do_bot"><a class="anchor" href="#_us1_1_inicialização_do_bot"></a>US1.1 : Inicialização do Bot</h4> <div class="paragraph"> <p><strong>Como</strong> desenvolvedor <strong>Eu quero</strong> um bot Discord que se conecte de forma confiável <strong>Para</strong> garantir a disponibilidade do serviço</p> </div> <div class="paragraph"> <p><strong>DoD (Definição de Concluído)</strong> : - [ ] O bot conecta-se automaticamente ao iniciar - [ ] Os logs estruturados documentam cada etapa - [ ] Reconexão automática em caso de desconexão - [ ] Testes de integração passam</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_pesquisa_spotify_inteligente"><a class="anchor" href="#_us2_1_pesquisa_spotify_inteligente"></a>US2.1 : Pesquisa Spotify Inteligente</h4> <div class="paragraph"> <p><strong>Como</strong> utilizador Discord <strong>Eu quero</strong> procurar faixas via Spotify <strong>Para</strong> descobrir e compartilhar música</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] Ordem`/search`funcional - [ ] Resultados relevantes com metadados - [ ] Cache local para otimizar as requisições - [ ] gestão graciosa dos erros da API</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_extração_resiliente_do_youtube"><a class="anchor" href="#_us3_1_extração_resiliente_do_youtube"></a>US3.1 : Extração Resiliente do YouTube</h4> <div class="paragraph"> <p><strong>Como</strong> sistema <strong>Quero</strong> extrair o áudio do YouTube de forma confiável <strong>Para</strong> manter a continuidade do serviço</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] Extração sem violação dos ToS - [ ] Qualidade de áudio ótima - [ ] Gerenciamento de restrições geográficas - [ ] Registros detalhados das operações</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_abordagem_log_driven_development"><a class="anchor" href="#_abordagem_log_driven_development"></a>Abordagem Log Driven Development</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_estratégia_de_logging"><a class="anchor" href="#_estratégia_de_logging"></a>Estratégia de Logging</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-dce448ec317d2ffc08a741835f25e1fa.png" alt="Diagram" width="687" height="633"> </div> </div> </div> <div class="sect2"> <h3 id="_estrutura_dos_logs"><a class="anchor" href="#_estrutura_dos_logs"></a>Estrutura dos logs</h3> <div class="paragraph"> <p>Nossa abordagem LDD utiliza logs estruturados com níveis semânticos:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>RASTRO</strong></dt> <dd> <p>Fluxo de dados detalhado</p> </dd> <dt class="hdlist1"><strong>depurar</strong></dt> <dd> <p>Estados internos das funções</p> </dd> <dt class="hdlist1"><strong>INFO</strong></dt> <dd> <p>Operações de negócio bem-sucedidas</p> </dd> <dt class="hdlist1"><strong>WARN</strong></dt> <dd> <p>Situações degradadas mas geridas</p> </dd> <dt class="hdlist1"><strong>ERRO</strong></dt> <dd> <p>Erros que exigem intervenção</p> </dd> <dt class="hdlist1"><strong>crítica</strong></dt> <dd> <p>Falhas do sistema</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_exemplo_de_log_design"><a class="anchor" href="#_exemplo_de_log_design"></a>Exemplo de Log Design</h3> <div class="paragraph"> <p>Antes de implementar a função de pesquisa do Spotify, definimos seus logs :</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="_arquitetura_de_validação_com_pydantic"><a class="anchor" href="#_arquitetura_de_validação_com_pydantic"></a>Arquitetura de Validação com Pydantic</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_modelos_de_dados"><a class="anchor" href="#_modelos_de_dados"></a>Modelos de Dados</h3> <div class="paragraph"> <p>Nossa abordagem funcional prioriza a validação a montante:</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="_gestão_funcional_de_erros"><a class="anchor" href="#_gestão_funcional_de_erros"></a>Gestão Funcional de Erros</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_monads_e_tratamento_de_erros"><a class="anchor" href="#_monads_e_tratamento_de_erros"></a>Monads e Tratamento de Erros</h3> <div class="paragraph"> <p>O uso do PyMonade permite um tratamento elegante de erros:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-d56a173ea25719cbd639a4eb34a4919b.png" alt="Diagram" width="508" height="494"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estratégia_de_contorno_das_restrições"><a class="anchor" href="#_estratégia_de_contorno_das_restrições"></a>Estratégia de Contorno das Restrições</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_abordagem_multi_fonte"><a class="anchor" href="#_abordagem_multi_fonte"></a>Abordagem Multi-Fonte</h3> <div class="paragraph"> <p>Diante das restrições das APIs, adotamos uma estratégia de diversificação:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-b8ae9e873554f0efebee724ae2693523.png" alt="Diagram" width="665" height="744"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plano_de_desenvolvimento_iterativo"><a class="anchor" href="#_plano_de_desenvolvimento_iterativo"></a>Plano de Desenvolvimento Iterativo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_planejamento_do_sprint"><a class="anchor" href="#_planejamento_do_sprint"></a>Planejamento do Sprint</h3> <div class="paragraph"> <p>Nosso desenvolvimento segue um ciclo de sprints de 2 semanas :</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>Sprint 1-2</strong></dt> <dd> <p>Infraestrutura e Núcleo do Bot do Discord</p> </dd> <dt class="hdlist1"><strong>Sprint 3-4</strong></dt> <dd> <p>Integração Spotify com LDD</p> </dd> <dt class="hdlist1"><strong>Sprint 5-6</strong></dt> <dd> <p>Integração YouTube e contornos</p> </dd> <dt class="hdlist1"><strong>Sprint 7-8</strong></dt> <dd> <p>Funcionalidades musicais avançadas</p> </dd> <dt class="hdlist1"><strong>Sprint 9-10</strong></dt> <dd> <p>Otimização e produção</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_métricas_de_qualidade"><a class="anchor" href="#_métricas_de_qualidade"></a>Métricas de Qualidade</h3> <div class="paragraph"> <p>Cada sprint é avaliado em :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Cobertura de logs</strong>: >90% dos caminhos críticos</p> </li> <li> <p><strong>Fiabilidade da API</strong>: <1% de erros não tratados</p> </li> <li> <p><strong>desempenho</strong>: <500ms tempo médio de resposta</p> </li> <li> <p><strong>Manutenibilidade</strong>: Complexidade ciclomática <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implantação_e_monitoramento"><a class="anchor" href="#_implantação_e_monitoramento"></a>Implantação e Monitoramento</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_arquitetura_de_produção"><a class="anchor" href="#_arquitetura_de_produção"></a>Arquitetura de Produção</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-9c8fabc0e53dede0f678193b1cccd21e.png" alt="Diagram" width="946" height="381"> </div> </div> </div> <div class="sect2"> <h3 id="_monitoramento_proativo"><a class="anchor" href="#_monitoramento_proativo"></a>Monitoramento Proativo</h3> <div class="paragraph"> <p>O LDD facilita um monitoramento inteligente:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Alertas baseados nos padrões de logs</strong></p> </li> <li> <p><strong>Detecção de anomalias comportamentais</strong></p> </li> <li> <p><strong>Métricas de negócio em tempo real</strong></p> </li> <li> <p><strong>Depuração assistida por correlação de logs</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_e_perspectivas"><a class="anchor" href="#_conclusão_e_perspectivas"></a>Conclusão e Perspectivas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta abordagem metodológica combina os benefícios do paradigma funcional com a robustez do Log Driven Development. Ela nos permite:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Antecipar os problemas</strong>graças aos logs projetados com antecedência</p> </li> <li> <p><strong>Manter a qualidade</strong>por meio da validação contínua</p> </li> <li> <p><strong>Adaptar rapidamente</strong>às alterações das APIs</p> </li> <li> <p><strong>Garantir a rastreabilidade</strong>completa das operações</p> </li> </ol> </div> <div class="paragraph"> <p>O desenvolvimento iterativo e a arquitetura modular garantem uma escalabilidade face às restrições mutáveis das plataformas musicais.</p> </div> <div class="sect2"> <h3 id="_próximas_etapas"><a class="anchor" href="#_próximas_etapas"></a>Próximas Etapas</h3> <div class="ulist"> <ul> <li> <p><strong>Fase 1</strong>Implementação do core com PyMonade</p> </li> <li> <p><strong>Fase 2</strong>: Integração Spotify com cache inteligente</p> </li> <li> <p><strong>Fase 3</strong>: Solução YouTube resiliente</p> </li> <li> <p><strong>Fase 4</strong>: Funcionalidades avançadas e otimização</p> </li> </ul> </div> <div class="paragraph"> <p>Esta fundação conceitual sólida nos permitirá navegar pelos desafios técnicos, enquanto oferece uma experiência do usuário excepcional.</p> </div> <hr> <div class="paragraph"> <p><strong>Este artigo será seguido de uma série técnica detalhando a implementação de cada componente com exemplos de código e padrões funcionais.</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_deste_guia">Objetivo deste guia</a></li> <li><a href="#_pré_requisitos">Pré-requisitos</a></li> <li><a href="#_instalar_e_configurar_as_ferramentas">Instalar e configurar as ferramentas</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_para_detectar_os_sensores">lm-sensors` para detectar os sensores</a></li> <li><a href="#_tlp_gerenciador_de_energia_inteligente">tlp` : gerenciador de energia inteligente</a></li> <li><a href="#_cpufrequtils_limitar_as_frequências_da_cpu">cpufrequtils` : limitar as frequências da CPU</a></li> <li><a href="#_auto_cpufreq_gerenciamento_dinâmico_e_simplificado">auto-cpufreq`: gerenciamento dinâmico e simplificado</a></li> <li><a href="#_thermald_proteção_térmica_automática">thermald` : proteção térmica automática</a></li> </ul> </li> <li><a href="#_vigilância_em_tempo_real">Vigilância em tempo real</a> <ul class="sectlevel2"> <li><a href="#_sensors_na_linha_de_comando">sensors` na linha de comando</a></li> <li><a href="#_opção_gui_psensor">Opção GUI : `psensor</a></li> </ul> </li> <li><a href="#_dicas_adicionais">Dicas adicionais</a></li> <li><a href="#_limpar_o_sistema_para_limitar_as_sobrecargas">Limpar o sistema para limitar as sobrecargas</a></li> <li><a href="#_para_ir_mais_longe">Para ir mais longe</a></li> <li><a href="#_conclusão">�📚 Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Você sente que seu computador portátil está esquentando anormalmente sob Ubuntu? Este artigo propõe uma abordagem<strong>software</strong>completa para<strong>resfriar</strong>, <strong>vigiar</strong> et <strong>controlar a temperatura</strong>da sua máquina.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivo_deste_guia">Objetivo deste guia</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Reduzir a temperatura global do computador</p> </li> <li> <p>Otimizar a gestão de energia</p> </li> <li> <p>Monitorar os componentes críticos (CPU, GPU, etc.)</p> </li> <li> <p>Evitar os atrasos decorrentes de<strong>throttle 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="_pré_requisitos">Pré-requisitos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Uma máquina Ubuntu (20.04 ou superior recomendada)</p> </li> <li> <p>Conexão à Internet</p> </li> <li> <p>Competência em linha de comando (nível iniciante a intermediário)</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_instalar_e_configurar_as_ferramentas">Instalar e configurar as ferramentas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_para_detectar_os_sensores">lm-sensors` para detectar os 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>Responda`YES`para todas as perguntas de`sensors-detect`para detectar os módulos.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_gerenciador_de_energia_inteligente">tlp` : gerenciador de energia 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="367" height="390"> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_limitar_as_frequências_da_cpu">cpufrequtils` : limitar as frequências da 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>`powersave`limita os picos de frequência</p> </li> <li> <p><code>performance</code>: favorece a potência em detrimento da temperatura</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_gerenciamento_dinâmico_e_simplificado">auto-cpufreq`: gerenciamento dinâmico e simplificado</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_proteção_térmica_automática">thermald` : proteção 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="_vigilância_em_tempo_real">Vigilância em tempo real</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_na_linha_de_comando">sensors` na linha de comando</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="_opção_gui_psensor">Opção 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="paragraph"> <p>Interface gráfica simples para CPU, GPU, ventoinhas</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dicas_adicionais">Dicas adicionais</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Fechar as abas e aplicações pesadas (ex: navegadores)</p> </li> <li> <p>Evite o uso intenso na bateria</p> </li> <li> <p>Monitorar os processos via`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="_limpar_o_sistema_para_limitar_as_sobrecargas">Limpar o sistema para limitar as 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_mais_longe">Para ir mais longe</h2> <div class="sectionbody"> <div class="paragraph"> <p>Você pode criar um serviço`systemd`personalizado para aplicar automaticamente algumas configurações na inicialização. Gostaria de um exemplo num próximo artigo? Deixe-me saber!</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">�📚 Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Combinando estas ferramentas simples, você ganhará:</p> </div> <div class="ulist"> <ul> <li> <p>Temperatura da CPU controlada</p> </li> <li> <p>Menos ruído de ventilação</p> </li> <li> <p>Uma melhor autonomia</p> </li> </ul> </div> <div class="paragraph"> <p>Não se esqueça de monitorar suas temperaturas regularmente para evitar qualquer superaquecimento.</p> </div> <div class="paragraph"> <p><em><em>_ É melhor prevenir do que derreter a sua 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="#_o_campo_de_batalha_um_modelo_três_navegadores_renderizações_múltiplas">O campo de batalha : um modelo, três navegadores, renderizações múltiplas</a></li> <li><a href="#_problema_1_o_cartão_flutuante_da_seção_hero">Problema 1: O cartão flutuante da seção "Hero</a></li> <li><a href="#_problema_2_a_barra_de_navegação_canibal">Problema 2 : A barra de navegação canibal</a></li> <li><a href="#_problema_3_a_tipografia_anárquica">Problema 3: A tipografia anárquica</a></li> <li><a href="#_problema_4_a_barra_de_navegação_que_transborda">Problema 4: A barra de navegação que transborda</a></li> <li><a href="#_problema_5_o_menu_hambúrguer_invisível">Problema 5: O menu hambúrguer invisível</a></li> <li><a href="#_conclusão_as_lições_de_uma_depuração_incansável">Conclusão: as lições de uma depuração incansável</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>Tempo de leitura :</strong> aproximadamente 7 minutos <strong>Nível :</strong> Intermediário</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Neste estudo de caso detalhado, vamos analisar os problemas de compatibilidade de navegador mais comuns e, às vezes, mais frustrantes encontrados ao criar uma maqueta UI com o Bootstrap 5.2. Desde o gerenciamento do Flexbox até a sutileza da renderização das fontes, descubra nossa jornada de depuração para transformar um design instável no Firefox em uma experiência pixel-perfeito em todos os navegadores.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_o_campo_de_batalha_um_modelo_três_navegadores_renderizações_múltiplas">O campo de batalha : um modelo, três navegadores, renderizações múltiplas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Todo desenvolvedor front-end conhece esse sentimento. Depois de horas de trabalho, a maquete está finalmente perfeita. Os alinhamentos são nítidos, a tipografia é elegante, as animações são fluidas. Damos um suspiro de satisfação, admiramos nosso trabalho no Chrome (ou Brave, ou Edge), e então, por precaução, abrimos o projeto no Firefox. E aí, é o drama. Elementos que transbordam, alinhamentos quebrados, fontes com tamanhos caóticos…​ a bela harmonia se foi.</p> </div> <div class="paragraph"> <p>É precisamente o cenário que enfrentamos ao desenvolver uma nova interface de portfólio. O briefing era simples: uma página inicial moderna, responsiva, com um seletor de temas (claro, escuro e de alto contraste), usando <strong>vanilla JavaScript</strong> e a última versão do <strong>Bootstrap 5.2</strong>.</p> </div> <div class="paragraph"> <p>Este artigo não é uma lista de soluções milagrosas. É o diário de bordo da nossa sessão de depuração, uma imersão no "porquê" das diferenças de renderização entre os motores Blink (Chromium, Brave) e Gecko (Firefox), e a demonstração de que soluções robustas e modernas valem sempre mais do que remendos feitos às pressas.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/usecase-debugging-firefox.svg" alt="usecase debugging firefox" width="1049" height="386"> </div> <div class="title">Figure 1. Diagrama de Caso de Uso : O processo de depuração</div> </div> <div class="imageblock"> <div class="content"> <img src="./images/components-solution-architecture.svg" alt="components solution architecture" width="1226" height="5160"> </div> <div class="title">Figure 2. Diagrama de Componentes : Arquitetura da solução front-end</div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_1_o_cartão_flutuante_da_seção_hero">Problema 1: O cartão flutuante da seção "Hero</h2> <div class="sectionbody"> <div class="paragraph"> <p>O primeiro bug também foi o mais visível. A seção de boas-vindas ("hero") é composta por duas colunas: à esquerda, o título principal; à direita, um cartão de apresentação.</p> </div> <div class="ulist"> <ul> <li> <p><strong>O sintoma:</strong>No Chrome e no Brave, as duas colunas estavam perfeitamente centralizadas verticalmente. No Firefox, o cartão à direita caía inexplicavelmente abaixo do texto da esquerda.</p> </li> <li> <p><strong>A investigação:</strong>O código HTML parecia porém simples e correto, utilizando as classes padrão do 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>Nosso CSS personalizado para`.hero-section`definia`display: flex` et <code>align-items: center</code>, e a classe`min-vh-100`dava de facto uma altura mínima à linha (<code>div.row</code>). Então, por que o Firefox se recusava a centralizar as colunas?</p> </div> <div class="ulist"> <ul> <li> <p><strong>A causa profunda :</strong>É um caso de escola sobre a forma como os mecanismos de renderização interpretam as alturas implícitas. La`<section>`tinha uma`min-height`, mas não`height`explícito. Para aplicar`align-items-center`dentro de`div.row`, O Firefox precisa saber a altura de referência deste contêiner. Como os pais (<code>div.container</code> et la `<section>`ela mesma) não tinham altura<strong>estrita</strong>, Firefox estava perdido. O motor Blink, mais permissivo, consegue "adivinhar" a intenção e centralizar os elementos. Gecko, mais fiel à especificação, não o faz.</p> </li> <li> <p><strong>A solução:</strong>Tornar a altura explícita. Nós forçamos o`.container` et le `.row`para ocupar 100% da altura de seu respectivo pai usando a classe utilitária`h-100`do 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>Quando um`align-items`Flexbox não funciona como esperado no eixo vertical, sempre verifique se o contêiner tem altura`height` ou <code>min-height</code>) definida e, se o problema persistir (especialmente no Firefox), certifique-se de que os contêineres pais intermediários propaguem bem essa altura.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_problema_2_a_barra_de_navegação_canibal">Problema 2 : A barra de navegação canibal</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Uma vez que a seção "Hero" estiver alinhada, outro problema surgiu: a barra de navegação, com sua classe`fixed-top`, sobrepunha-se ao título. Um`padding-top: 80px`tinha sido aplicado à seção "Hero" como solução.</div> <ul> <li> <p><strong>O sintoma:</strong> Le `padding`era suficiente no Chrome, mas não no Firefox, onde o título ainda estava parcialmente mascarado.</p> </li> <li> <p><strong>A causa profunda:</strong>O uso de um "número mágico" (<code>80px</code>) É uma prática muito má. A altura de um elemento como uma barra de navegação pode variar alguns píxeis entre navegadores devido a diferenças sutis na renderização das fontes, do espaçamento ou mesmo nas opções do utilizador. Confiar em um valor fixo é a receita para um design frágil.</p> </li> <li> <p><strong>A solução :</strong>Uma solução dinâmica e infalível em JavaScript. Escrevemos um pequeno script para:</p> </li> <li> <p>Medir a altura <strong>real</strong> da barra de navegação após o render da página.</p> </li> <li> <p>Aplicar esta altura medida como`padding-top`para a seção "Hero</p> </li> <li> <p>Reexecutar essa função a cada redimensionamento da janela para se adaptar às mudanças (como a transição para o menu hambúrguer).</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 Sequência : Ajustamento dinâmico do padding</div> </div> <div class="paragraph"> <p>Em paralelo, claro, removemos a regra`padding-top: 80px;`do nosso arquivo`styles.css`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_a_tipografia_anárquica">Problema 3: A tipografia anárquica</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">A preocupação seguinte era a mais prejudicial à imagem da marca: o tamanho do título principal.</div> <ul> <li> <p><strong>O sintoma :</strong>No Firefox, a fonte do título "Desenvolvedor Formador…​" era enorme, quase chocante, enquanto que era harmoniosa nos outros navegadores.</p> </li> <li> <p><strong>A causa profunda:</strong>O título utilizava uma classe`display-4`do Bootstrap. Estas classes utilizam tamanhos de fonte responsivos, frequentemente baseados na unidade`rem`e media queries. Mais uma vez, o algoritmo de renderização do Firefox, combinado com a fonte "Inter", resultava em um cálculo de tamanho muito maior em nossa resolução de 1920x1080.</p> </li> <li> <p><strong>A solução :</strong>Retomar o controle com a função CSS`clamp()<code>. Esta função é uma revolução para a tipografia fluida. Ela permite definir um tamanho de fonte com três valores: um tamanho "preferido" (que se adapta à largura da visualização,`vw</code>), e um tamanho 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>Com`clamp()<code>, nós pudemos dizer ao navegador: "Faça a fonte crescer com a tela, mas não ultrapasse<strong>nunca</strong>o limite de`2.5rem</code>. Isso instantaneamente harmonizou a renderização em todos os navegadores, nos dando controle absoluto sobre a estética final.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_a_barra_de_navegação_que_transborda">Problema 4: A barra de navegação que transborda</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este foi o problema que nos deu o maior trabalho e que acabou por revelar a natureza profunda das microdiferenças de renderização.</p> </div> <div class="ulist"> <ul> <li> <p><strong>O sintoma:</strong>Em uma tela de 1920x1080, os últimos links do menu ("Blog", "Contact") foram empurrados para fora da tela à direita, mas apenas no Firefox.</p> </li> <li> <p><strong>A causa profunda :</strong>Após várias tentativas infrutíferas (alterar os pontos de ruptura do Bootstrap de`lg` à <code>xl`então`xxl</code>), nós entendemos. A causa não era a lógica do Bootstrap, mas um simples cálculo de largura. No Firefox, a soma das larguras de todos os links, incluindo seus`padding` et `margin`com precisão de sub-pixel, era <strong>ligeiramente</strong> superior a 1920 pixels. No Chrome, essa mesma soma era <strong>ligeiramente</strong> inferior. Nos faltavam alguns pixels.</p> </li> <li> <p><strong>A solução:</strong>Uma redução cirúrgica dos espaçamentos. Já que não era questão de fazer um alvo específico do Firefox com "hacks" CSS obsoletos, a única solução limpa era encontrar um estilo comum que funcionasse em qualquer lugar. Então reduzimos ligeiramente as margens e o padding horizontal de cada link de navegação.</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 redução, quase invisível a olho nu em um único elemento, nos fez ganhar coletivamente o espaço necessário para que todos os links caibam dentro do quadro no Firefox, mantendo ao mesmo tempo uma aparência quase idêntica nos outros navegadores.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_5_o_menu_hambúrguer_invisível">Problema 5: O menu hambúrguer invisível</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">O último problema, e não dos menores, concernia a acessibilidade móvel.</div> <ul> <li> <p><strong>O sintoma :</strong>No modo responsivo (menu "hamburger"), o ícone do menu era invisível nos temas "dark" e "high-contrast".</p> </li> <li> <p><strong>A causa profunda :</strong>O ícone do menu do Bootstrap 5 é um`background-image`(Um SVG codificado em URL). Por padrão, a cor do traço é escura, otimizada para um fundo claro. Ela não se adapta automaticamente à mudança de tema.</p> </li> <li> <p><strong>A solução :</strong>Usar as variáveis CSS do Bootstrap para sobrescrever o ícone. Definimos um novo ícone SVG, mas desta vez com um traço branco (<code>#ffffff</code>), e nós a aplicamos especificamente quando os temas`dark` ou `high-contrast`estão ativos.</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>A personalização dos componentes do Bootstrap, como este, está sendo feita cada vez mais por meio da sobrescrita de variáveis CSS (<code>--bs-component-property</code>), que é o método mais limpo e mais duradouro.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão_as_lições_de_uma_depuração_incansável">Conclusão: as lições de uma depuração incansável</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este percurso, embora por vezes frustrante, é rico em ensinamentos. Cada problema resolvido reforça uma verdade fundamental do desenvolvimento web :<strong>nada substitui um teste rigoroso de múltiplos 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. Mindmap : Síntese da depuração e das lições aprendidas</div> </div> <div class="olist arabic"> <div class="title">Estas são as lições que nós retenemos:</div> <ol class="arabic"> <li> <p><strong>Firefox é um aliado:</strong>Sua maior fidelidade aos padrões CSS nos força a escrever um código mais robusto e menos ambíguo.</p> </li> <li> <p><strong>Evite os "números mágicos" :</strong>Os valeurs fixos (como`padding-top: 80px`) são bombas-relógio. Prefiram sempre soluções dinâmicas (JavaScript) ou relativas (Flexbox, Grid).</p> </li> <li> <p><strong>Domine sua tipografia :</strong>Utilize`clamp()`para um controle total sobre o tamanho das fontes responsivas.</p> </li> <li> <p><strong>Pense em "componentes" :</strong>Para personalizar o Bootstrap, sobrescreva suas variáveis CSS em vez de multiplicar as regras que sobrescrevem o framework.</p> </li> <li> <p><strong>Não visem um navegador :</strong>A solução raramente é fazer um "hack" para um navegador específico, mas sim encontrar um estilo comum que funcione em todos os lugares.</p> </li> </ol> </div> <div class="paragraph"> <p>No final, a maquete agora está sólida, previsível e pronta para ser integrada em um sistema de templating. Cada bug corrigido não foi um fracasso, mas um passo em direção a um código de melhor qualidade.</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="#_o_problema_isolar_os_testes_unitários_de_um_plugin_gradle">O Problema: Isolar os Testes Unitários de um Plugin Gradle</a> <ul class="sectlevel2"> <li><a href="#_arquitetura_do_problema">Arquitetura do Problema</a></li> <li><a href="#_a_tentação_de_uma_falsa_boa_ideia">A Tentação de uma Falsa Boa Ideia</a></li> </ul> </li> <li><a href="#_a_solução_simular_a_propriedade_com_extrapropertiesextension">A Solução: Simular a Propriedade com `ExtraPropertiesExtension</a> <ul class="sectlevel2"> <li><a href="#_passo_1_compreender_extrapropertiesextension">Passo 1: Compreender ExtraPropertiesExtension</a></li> <li><a href="#_etapa_2_configuração_do_teste_preparação">Etapa 2: Configuração do Teste - Preparação</a></li> <li><a href="#_passo_3_injeção_da_propriedade">Passo 3: Injeção da Propriedade</a></li> <li><a href="#_passo_4_diagrama_de_fluxo_da_solução">Passo 4 : Diagrama de Fluxo da Solução</a></li> <li><a href="#_etapa_5_comparação_antesdepois">Etapa 5 : comparação antes/depois</a></li> <li><a href="#_etapa_6_gestão_dos_casos_de_teste_múltiplos">Etapa 6 : Gestão dos Casos de Teste Múltiplos</a></li> <li><a href="#_arquitetura_final_da_solução">Arquitetura Final da Solução</a></li> </ul> </li> <li><a href="#_as_vantagens_desta_abordagem">As Vantagens desta Abordagem</a></li> <li><a href="#_boas_práticas_e_dicas">Boas Práticas e Dicas</a> <ul class="sectlevel2"> <li><a href="#_criar_um_método_utilitário">Criar um Método Utilitário</a></li> <li><a href="#_validação_das_propriedades">Validação das Propriedades</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div class="sect1"> <h2 id="_o_problema_isolar_os_testes_unitários_de_um_plugin_gradle">O Problema: Isolar os Testes Unitários de um Plugin Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante a escrita de testes unitários para um plugin Gradle, um desafio comum é lidar com as dependências da configuração do projeto, como as propriedades definidas no arquivo`gradle.properties`. No nosso caso, o plugin`jbake.ghpages`devia ler uma propriedade`site_config_path`para funcionar corretamente. O teste unitário para a tarefa`initialize`Precisava verificar o comportamento do plugin na presença desta propriedade.</p> </div> <div class="paragraph"> <p>O problema fundamental é que os testes unitários, por design, devem ser <strong>isolados</strong>. O uso de`ProjectBuilder`de Gradle cria uma instância de`Project`na memória, totalmente desconectada de um verdadeiro projeto no sistema de arquivos. Portanto, esta instância de teste não lê automaticamente o arquivo`gradle.properties`e portanto não tem conhecimento da propriedade`site_config_path`.</p> </div> <div class="sect2"> <h3 id="_arquitetura_do_problema">Arquitetura do Problema</h3> <div class="paragraph"> <p>O diagrama a seguir ilustra a desconexão entre o ambiente de teste e o sistema de arquivos:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/test-isolation-problem.svg" alt="test isolation problem" width="1212" height="5787"> </div> </div> </div> <div class="sect2"> <h3 id="_a_tentação_de_uma_falsa_boa_ideia">A Tentação de uma Falsa Boa Ideia</h3> <div class="paragraph"> <p>Uma primeira abordagem poderia ser criar um arquivo`gradle.properties`fictício nos recursos de teste.</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>Contudo, este método está destinado ao fracasso porque`ProjectBuilder`não é concebido para escanear o sistema de arquivos em busca de arquivos de configuração. O teste permaneceria isolado e ignoraria este arquivo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_simular_a_propriedade_com_extrapropertiesextension">A Solução: Simular a Propriedade com `ExtraPropertiesExtension</h2> <div class="sectionbody"> <div class="paragraph"> <p>A solução elegante para este problema não é de <strong>ler</strong> o arquivo, mas de <strong>simular</strong> a presença da propriedade diretamente no objeto`Project`de teste. O Gradle fornece um mecanismo poderoso para isso: as <strong>propriedades adicionais</strong> (Extra Properties).</p> </div> <div class="sect2"> <h3 id="_passo_1_compreender_extrapropertiesextension">Passo 1: Compreender ExtraPropertiesExtension</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`é um contêiner chave-valor anexado a cada objeto do modelo Gradle. Ele permite adicionar propriedades dinamicamente a um projeto, uma tarefa ou qualquer outra extensão 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="_etapa_2_configuração_do_teste_preparação">Etapa 2: Configuração do Teste - Preparação</h3> <div class="paragraph"> <p>Vamos começar criando a estrutura básica do nosso teste unitário :</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="_passo_3_injeção_da_propriedade">Passo 3: Injeção da Propriedade</h3> <div class="paragraph"> <p>Aqui está o processo detalhado para injetar a propriedade no projeto de teste :</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="_passo_4_diagrama_de_fluxo_da_solução">Passo 4 : Diagrama de Fluxo da Solução</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="_etapa_5_comparação_antesdepois">Etapa 5 : comparação antes/depois</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="_etapa_6_gestão_dos_casos_de_teste_múltiplos">Etapa 6 : Gestão dos Casos de Teste Múltiplos</h3> <div class="paragraph"> <p>Para testar diferentes cenários, vamos criar vários testes com configurações 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="_arquitetura_final_da_solução">Arquitetura Final da Solução</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="_as_vantagens_desta_abordagem">As Vantagens desta Abordagem</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Isolamento Completo</strong>: O teste não depende de nenhum arquivo externo. Ele é autônomo e pode ser executado de forma confiável em qualquer ambiente (local, CI/CD, etc.).</p> </li> <li> <p><strong>Clareza e Intenção</strong>: O teste declara explicitamente as pré-condições para sua execução. Quem lê o teste vê imediatamente que o plugin requer a propriedade`site_config_path`para funcionar.</p> </li> <li> <p><strong>Manutenabilidade</strong>Se o nome da propriedade mudar, basta atualizá-lo em apenas um local no teste, sem precisar manipular os arquivos de configuração do teste.</p> </li> <li> <p><strong>Flexibilidade</strong>Tornou-se trivial testar diferentes cenários simplesmente alterando o valor da propriedade injetada em cada teste (valor válido, inválido, ausente, etc.).</p> </li> <li> <p><strong>Desempenho</strong>: Sem leitura de arquivos, tudo acontece na memória, o que deixa os testes mais rápidos.</p> </li> <li> <p><strong>Reprodutibilidade</strong>Os testes são determinísticos porque não dependem do estado do sistema de arquivos.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_boas_práticas_e_dicas">Boas Práticas e Dicas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_criar_um_método_utilitário">Criar um Método Utilitário</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="_validação_das_propriedades">Validação das Propriedades</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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Em vez de lutar para fazer ler arquivos de configuração a um ambiente de teste unitário, a melhor prática consiste em simular o estado necessário. O uso de`ExtraPropertiesExtension`Para definir programaticamente as propriedades do Gradle é o método mais limpo e mais robusto para realizar testes unitários de plugins eficazes e fiáveis.</p> </div> <div class="paragraph"> <p>Esta técnica transforma um problema de dependência externa em uma simples injeção de dependência, no cerne mesmo da filosofia do Desenvolvimento Orientado por Testes (TDD). Ela oferece controle total sobre o ambiente de teste, mantendo o isolamento necessário para testes unitários de qualidade.</p> </div> <div class="paragraph"> <p>Os diagramas e exemplos apresentados neste artigo mostram como essa abordagem pode ser implementada de forma progressiva e metódica, permitindo criar um conjunto de testes robusto e mantível para seus plugins 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_as_configurações_com_allprojects_e_subprojects">Centralizar as Configurações com <code>allprojects</code> e `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>A automação das tarefas de construção é crucial para todo projeto de software, e o Gradle, com seu DSL Kotlin, oferece uma flexibilidade excepcional. Durante nossa conversa, exploramos como centralizar e reutilizar a lógica de construção, especialmente para os relatórios de testes, ao aproveitar<strong>todos os projetos</strong>, <strong>buildSrc</strong>e tarefas personalizadas em Kotlin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_centralizar_as_configurações_com_allprojects_e_subprojects">Centralizar as Configurações com <code>allprojects</code> e `subprojects</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os blocos`allprojects` et `subprojects`no seu`build.gradle.kts`A raiz são fundamentais para aplicar configurações comuns através do seu projeto multi-módulo.</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: Aplique a configuração para<strong>projeto raiz e a todos os seus subprojetos</strong>. Ideal para definir um`group`, uma`version`, alguns`repositories`comuns *<code>subprojects { …​ }`Aplica a configuração<strong>exclusivamente aos subprojetos</strong>, excluindo o projeto raiz. Perfeito para aplicar plugins específicos aos módulos (como`java</code> ou <code>kotlin-jvm</code>) ou dependências comuns às suas bibliotecas.</p> </div> <div class="paragraph"> <p>Aqui está um exemplo 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></think></p> </div> <div class="paragraph"> <p></think>`buildSrc`: O Canivete Suíço da Lógica de Build</p> </div> <div class="paragraph"> <p>Quando a lógica das suas tarefas se tornar complexa ou precisar ser reutilizada,<strong>buildSrc</strong>É a solução preferida. É um módulo especial do Gradle que é compilado antes dos scripts de construção principais, tornando suas classes disponíveis no class path de todo o seu build.</p> </div> <div class="paragraph"> <p>Por que usar`buildSrc`para as tarefas?</p> </div> <div class="ulist"> <ul> <li> <p><strong>reutilizabilidade</strong>Uma tarefa definida em`buildSrc`pode ser aplicada a qualquer projeto do build.</p> </li> <li> <p><strong>Organização</strong>: Centraliza o código de compilação, tornando-o mais limpo e manutenível.</p> </li> <li> <p><strong>Type Safety e Autocompletar</strong>: O código Kotlin em`buildSrc`é compilado, oferecendo a verificação de erros e o autocomplete da sua IDE, melhorando a experiência de desenvolvimento.</p> </li> </ul> </div> <div class="paragraph"> <p>\=== Diagrama de Fluxo`buildSrc`(Código PlantUML)</p> </div> <div class="paragraph"> <p>Para gerar este diagrama, copie o código abaixo e cole-o em uma ferramenta que suporte 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 monochrome true</p> </div> <div class="paragraph"> <p>rectangle "Processo de Construção Gradle" { componente "buildSrc" como BS { arquivo "MyCustomTask.kt" como T arquivo "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 em P --\> RP : "is applied to P --\> SA : "is applied to P -→ SB : "é aplicado a</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contém RP --|\> SB : "contém</p> </div> <div class="paragraph"> <p>RP -up→ BS : "depende de (para a lógica de construção) SA -up-\> BS : "depende de (para a lógica de construção) SB -up-\> BS : "depende de (para a lógica de construção)</p> </div> <div class="paragraph"> <p>nota à direita de T Classes de tarefas personalizadas (ex: OpenTestReportTask) nota final</p> </div> <div class="paragraph"> <p>nota à direita de P Plugins de convenção que registram as tarefas nota final</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>\== Criação de Tarefas de Relatórios Abstratas</p> </div> <div class="paragraph"> <p>Para gerenciar os relatórios de testes, concebemos uma abordagem modular utilizando uma classe de tarefa abstrata em`buildSrc`. Conforme às suas necessidades, esta classe pode herdar de`DefaultTask` ou de <code>Exec</code>.</p> </div> <div class="paragraph"> <p>\=== Tarefa Abstrata`OpenTestReportTask`(heredando de`DefaultTask`)</p> </div> <div class="paragraph"> <p>Esta abordagem é recomendada se você precisar de uma lógica Kotlin personalizada que interaja com o sistema de arquivos ou outras APIs do Gradle e então execute um comando externo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>package 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}") } ---- ## } \=== Implementações Concretas Essas classes herdam da tarefa abstrata e definem o caminho específico do relatório. ## [source,kotlin] pacote com.yourpackage classe abstrata ReportUnitTestsTask : OpenTestReportTask() { init { Abre o relatório de teste unitário no Firefox. reportPath = "build/reports/tests/test/index.html } } package com.yourpackage abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "Abre o relatório de teste funcional no Firefox." reportPath = "build/reports/tests/functionalTest/index.html" } } \=== Registro das Tarefas No`build.gradle.kts`do seu projeto raiz : ## [source,kotlin] tasks.register\<com.yourpackage.ReportUnitTestsTask\>("reportTests") {} tasks.register\<com.yourpackage.ReportFunctionalTestsTask\>("reportFunctionalTests") {} \=== Diagrama UML das Tarefas de Relatório (Código PlantUML) Copie o código abaixo e cole-o em uma ferramenta que suporte PlantUML. ## [source,plantuml] @startuml skinparam handwritten true skinparam monocromático verdadeiro classe abstrata DefaultTask { } classe abstrata Exec { \+ commandLine(args: String...) \+ exec() } classe abstrata OpenTestReportTask estende DefaultTask { \+ group: String = "verification \+ descrição: String \+ dependsOn("check") \+ abstract reportPath: String \+ openReport() : void } classe abstrata AbstractJbakeExecTask extends Exec { \+ group: String = "verification + descrição: 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 Executar \<|-- AbstractJbakeExecTask DefaultTask \<|-- Exec ## @enduml \== Tarefa Abstrata`AbstractJbakeExecTask`(herdando de`Exec`) Se a sua tarefa consiste principalmente em executar um comando externo com argumentos variáveis, herde diretamente de**Exec**é mais direto. ## [source,kotlin] package 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 } ## } \=== Implementações Concretas para`Exec` ## [source,kotlin] pacote com.yourpackage abstract class ReportJbakeTestsTask : AbstractJbakeExecTask() { init { description = "Abre o relatório de testes unitários do Jbake no Firefox. reportRelativePath = "build/reports/tests/test/index.html } } package com.yourpackage abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "Abre o relatório de teste funcional no Firefox." reportRelativePath = "build/reports/tests/functionalTest/index.html" } } Visibilidade das Tarefas`buildSrc` As tarefas e classes que você define em**buildSrc**são : ***Visíveis e utilizáveis**por todos os projetos do seu build principal (raiz e subprojetos). É por isso que você pode usar`com.yourpackage.ReportUnitTestsTask`em`allprojects { ... }`. ***Não executáveis**diretamente como tarefas de buildSrc (por exemplo`gradle :buildSrc:reportTests`não funcionaria se a tarefa não fosse registrada especificamente em`buildSrc/build.gradle.kts`)`buildSrc`É um módulo de compilação, não é um módulo de aplicativo executável para essas tarefas do build principal. Executar um relatório para os testes de`buildSrc`ele mesmo Si `buildSrc`tem os seus próprios testes e gera relatórios, você pode gravar uma tarefa de relatório diretamente em`buildSrc/build.gradle.kts`: ## [source,kotlin] plugins { `kotlin-jvm` } repositórios { mavenCentral() } tasks.withType<Test> { useJUnitPlatform() reports.html.outputLocation.set(layout.buildDirectory.dir("reports/tests")) } import com.yourpackage.ReportJbakeTestsTask // Importe sua classe de tarefa ## tasks.register\<ReportJbakeTestsTask\>("reportBuildSrcTests") { // O caminho já está definido na classe, ele apontará para os relatórios de buildSrc } Você poderá então executar:`./gradlew :buildSrc:test`seguido de`./gradlew :buildSrc:reportBuildSrcTests`. Ao adotar essas práticas, você construirá sistemas de build do Gradle em Kotlin DSL que não são apenas poderosos, mas também incrivelmente modulares, manuteníveis e fáceis de entender.</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="#_configuração_declarativa">Configuração declarativa</a></li> <li><a href="#_arquitetura_do_plugin">Arquitetura do plugin</a></li> <li><a href="#_definição_da_extensão_dsl">Definição da extensão DSL</a></li> <li><a href="#_definição_da_tarefa_personalizada">Definição da tarefa personalizada</a></li> <li><a href="#_interface_gitadapter">Interface GitAdapter</a></li> <li><a href="#_implementação_concreta_com_jgit">Implementação concreta com JGit</a></li> <li><a href="#_configuração_dsl_kotlin">Configuração DSL Kotlin</a></li> <li><a href="#_testes_unitários_com_mockito">Testes unitários com Mockito</a> <ul class="sectlevel2"> <li><a href="#_dependências">dependências</a></li> <li><a href="#_teste_do_comportamento_git">Teste do comportamento Git</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_próximas_etapas">Próximas etapas</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Este post apresenta a abordagem completa de projeto e teste (TDD) de um plugin Gradle escrito em Kotlin DSL. Este plugin automatiza a geração de sites estáticos com <strong>JBake</strong> e a <strong>implantação Git</strong> via <strong>JGit</strong>, tudo a partir de um arquivo YAML de configuração.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivo">Objetivo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Criar um plugin Gradle :</p> </div> <div class="ulist"> <ul> <li> <p>configurável em Kotlin DSL ;</p> </li> <li> <p>capaz de :</p> </li> <li> <p>gerar um site estático a partir do JBake ;</p> </li> <li> <p>implantar em um repositório Git remoto via JGit ;</p> </li> <li> <p>integrabel em um fluxo de trabalho CI/CD ;</p> </li> <li> <p>testado segundo uma abordagem TDD.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_configuração_declarativa">Configuração declarativa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está um exemplo de configuração YAML para modelar na nossa 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 configuração é representada via uma extensão Gradle declarável em Kotlin DSL.</p> </div> </div> </div> <div class="sect1"> <h2 id="_arquitetura_do_plugin">Arquitetura do 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="_definição_da_extensão_dsl">Definição da extensão 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="_definição_da_tarefa_personalizada">Definição da tarefa 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="_interface_gitadapter">Interface 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="_implementação_concreta_com_jgit">Implementação concreta com 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="_configuração_dsl_kotlin">Configuração 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="_testes_unitários_com_mockito">Testes unitários com Mockito</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dependências">dependências</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="_teste_do_comportamento_git">Teste do comportamento 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="777" height="326"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>A separação das responsabilidades via`GitAdapter`permite aplicar completamente o TDD no desenvolvimento de plugin Gradle:</p> </div> <div class="ulist"> <ul> <li> <p>as chamadas Git são abstratas e testáveis;</p> </li> <li> <p>A configuração DSL é limpa e clara;</p> </li> <li> <p>O plugin permanece agnóstico em relação à implementação real.</p> </li> </ul> </div> <div class="paragraph"> <p>Esta abordagem garante alta testabilidade e extensibilidade (para GitHub API, GitLab, etc.).</p> </div> </div> </div> <div class="sect1"> <h2 id="_próximas_etapas">Próximas etapas</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Integrar a geração JBake como um`BakeAdapter`</p> </li> <li> <p>Adicionar testes de integração com`GradleRunner`</p> </li> <li> <p>Suportar o carregamento automático de arquivos`site.yml`via 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="#_introdução">Introdução</a></li> <li><a href="#_o_que_é_o_asciidoc">O que é o AsciiDoc?</a> <ul class="sectlevel2"> <li><a href="#_por_que_escolher_o_asciidoc">Por que escolher o 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="#_mapa_mental">Mapa Mental</a></li> <li><a href="#_diagrama_de_fluxo_flux">Diagrama de fluxo (flux)</a></li> <li><a href="#_estrutura_básica_de_um_arquivo_asciidoc">Estrutura básica de um arquivo AsciiDoc</a></li> <li><a href="#_sintaxe_fundamental">Sintaxe fundamental</a> <ul class="sectlevel2"> <li><a href="#_títulos_e_seções">Títulos e seções</a></li> <li><a href="#_texto_em_negrito_itálico_e_monoespacado">Texto em negrito, itálico e monoespacado</a></li> <li><a href="#_listas_com_marcadores_e_listas_numeradas">Listas com marcadores e listas numeradas</a></li> <li><a href="#_links_e_imagens">Links e imagens</a></li> <li><a href="#_blocos_de_código">Blocos de código</a></li> <li><a href="#_tabelas">tabelas</a></li> <li><a href="#_notas_e_admoestações">Notas e admoestações</a></li> </ul> </li> <li><a href="#_utilização_de_atributos_e_variáveis">Utilização de atributos e variáveis</a></li> <li><a href="#_casos_de_uso_comuns">Casos de uso comuns</a></li> <li><a href="#_boas_práticas">Boas práticas</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_para_saber_mais">Para saber mais</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Público-alvo :</em> Desenvolvedores, redatores técnicos e toda pessoa que deseja escrever documentação técnica ou artigos ricos.</div> <p>AsciiDoc é uma linguagem de marcação leve, concebida para redigir documentos técnicos estruturados, artigos, livros ou ainda apresentações. Distingue-se pela sua legibilidade, riqueza sintática e capacidade de gerar diversos formatos (HTML, PDF, DocBook, etc.). Neste artigo, vamos explorar a sintaxe essencial do AsciiDoc e propor dicas para uma rápida familiarização.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_é_o_asciidoc">O que é o AsciiDoc?</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc é uma linguagem de descrição de documentos, semelhante ao Markdown, mas mais poderoso. Ele permite estruturar eficientemente textos, títulos, listas, tabelas, blocos de código e muito mais. Sua versatilidade o torna uma escolha popular para a documentação de projetos de código aberto, a redação de livros e a publicação na web.</p> </div> <div class="sect2"> <h3 id="_por_que_escolher_o_asciidoc">Por que escolher o AsciiDoc ?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Sintaxe legível e intuitiva.</p> </li> <li> <p>Suporte nativo de estruturas complexas (tabelas, notas, avisos, etc.).</p> </li> <li> <p>Geração multi-formato (HTML, PDF, ePub, DocBook, DocBook…).</p> </li> <li> <p>Integração fácil com geradores de sites estáticos como JBake ou Antora.</p> </li> <li> <p>Personalização avançada com os atributos e extensões.</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>Um diagrama de caso de uso permite apresentar as principais interações entre os usuários e o sistema. Veja um exemplo simples para um sistema de documentação:</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="_mapa_mental">Mapa Mental</h2> <div class="sectionbody"> <div class="paragraph"> <p>O mind map (mapa mental) é ideal para explorar os conceitos relacionados ao AsciiDoc e suas relações :</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_fluxo_flux">Diagrama de fluxo (flux)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Um diagrama de fluxo permite descrever o processo de geração de um 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="_estrutura_básica_de_um_arquivo_asciidoc">Estrutura básica de um arquivo AsciiDoc</h2> <div class="sectionbody"> <div class="paragraph"> <p>Um arquivo AsciiDoc geralmente começa com um título, atributos opcionais e depois o conteúdo estruturado. Aqui está um exemplo 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="_sintaxe_fundamental">Sintaxe fundamental</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_títulos_e_seções">Títulos e seções</h3> <div class="paragraph"> <p>AsciiDoc suporta vários níveis 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_em_negrito_itálico_e_monoespacado">Texto em negrito, itálico e monoespacado</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_com_marcadores_e_listas_numeradas">Listas com marcadores e listas 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="_links_e_imagens">Links e imagens</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="_blocos_de_código">Blocos 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("Olá AsciiDoc !")</p> </div> </div> <div class="sect2"> <h3 id="_tabelas">tabelas</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_e_admoestações">Notas e admoestações</h3> <div class="paragraph"> <p>AsciiDoc propõe uns blocos de informação 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="_utilização_de_atributos_e_variáveis">Utilização de atributos e variáveis</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os atributos personalizados permitem reutilizar valores ou configurar comportamentos:</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_comuns">Casos de uso comuns</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentação de projeto open source (README, guias técnicas) - Redação de livros e ebooks - Geração automática de sites web estáticos (JBake, Antora) - Apresentações técnicas</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_boas_práticas">Boas práticas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Utilize títulos consistentes e um sumário automático (:toc:). - Prefira usar as admonições para chamar a atenção aos pontos-chave. - Organize seus arquivos para facilitar a manutenção. - Aproveite os blocos de código anotados para ilustrar exemplos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc é uma ferramenta poderosa e acessível para escrever toda documentação técnica ou artigo estruturado. Sua sintaxe rica, combinada à geração multi-formato, faz dele um aliado de escolha para desenvolvedores e redatores exigentes. Experimente o AsciiDoc em seu próximo projeto e descubra a diferença!</p> </div> </div> </div> <div class="sect1"> <h2 id="_para_saber_mais">Para saber mais</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentação 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 e 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>Compartilhe suas experiências e dicas nos comentários !</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="#_o_problema_nat_e_endereços_privados">O problema: NAT e endereços privados</a></li> <li><a href="#_etapa_1_identificar_o_seu_endereço_ip_público">Etapa 1: Identificar o seu endereço IP público</a></li> <li><a href="#_passo_2_conheça_o_endereço_ip_local_da_sua_máquina_ubuntu">Passo 2: Conheça o endereço IP local da sua máquina Ubuntu</a></li> <li><a href="#_passo_3_configurar_o_encaminhamento_de_portas_na_sua_box">Passo 3: Configurar o encaminhamento de portas na sua box</a> <ul class="sectlevel2"> <li><a href="#_acesso_à_interface_de_administração">Acesso à interface de administração</a></li> <li><a href="#_configuração_da_redireção">Configuração da redireção</a></li> </ul> </li> <li><a href="#_etapa_4_configuração_do_serviço_no_ubuntu">Etapa 4: Configuração do serviço no Ubuntu</a></li> <li><a href="#_passo_5_configuração_do_firewall_ubuntu">Passo 5: Configuração do firewall Ubuntu</a></li> <li><a href="#_etapa_6_teste_e_validação">Etapa 6: Teste e validação</a> <ul class="sectlevel2"> <li><a href="#_teste_a_partir_da_rede_local">Teste a partir da rede local</a></li> <li><a href="#_teste_de_fora">Teste de fora</a></li> </ul> </li> <li><a href="#_boas_práticas_e_segurança">Boas práticas e segurança</a> <ul class="sectlevel2"> <li><a href="#_segurança_básica">Segurança básica</a></li> <li><a href="#_monitoramento_de_conexões">Monitoramento de conexões</a></li> <li><a href="#_utilização_de_um_proxy_reverso">Utilização de um proxy reverso</a></li> </ul> </li> <li><a href="#_alternativas_ao_encaminhamento_de_portas">Alternativas ao encaminhamento de portas</a> <ul class="sectlevel2"> <li><a href="#_soluções_em_nuvem">Soluções em nuvem</a></li> <li><a href="#_vps_e_proxy_reverso">VPS e proxy reverso</a></li> </ul> </li> <li><a href="#_solução_de_problemas">Solução de problemas</a> <ul class="sectlevel2"> <li><a href="#_problemas_comuns">Problemas comuns</a></li> <li><a href="#_depurar_rede">Depurar rede</a></li> </ul> </li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><em>.\ _Tempo de leitura:</em> 15 minutos</p> </div> <div class="ulist"> <div class="title">Público-alvo : Intermediário</div> <ul> <li> <p><strong>Pré-requisitos assumidos</strong> : conhecimento básico de Ubuntu, terminal, conceitos básicos de rede</p> </li> <li> <p><strong>Conceitos técnicos</strong> : NAT, encaminhamento de portas, firewall, proxy reverso</p> </li> <li> <p><strong>Comandos do sistema</strong>: utilização do terminal, configuração de rede</p> </li> <li> <p><strong>Seções avançadas</strong> : monitoramento, segurança, alternativas cloud</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_o_problema_nat_e_endereços_privados">O problema: NAT e endereços privados</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Problemática : Você está desenvolvendo um aplicativo web em sua máquina Ubuntu e deseja torná-lo acessível de fora da sua rede doméstica? Você está no lugar certo! Neste artigo, vamos ver como expor um serviço local (por exemplo, na porta 8080) para a Internet configurando o encaminhamento de porta na sua box de internet.</div> <p>Por padrão, sua caixa de internet utiliza o NAT (Network Address Translation) para compartilhar um único endereço IP público entre todos os dispositivos da sua rede doméstica. Seus dispositivos locais utilizam endereços IP privados (192.168.x.x, 10.x.x.x, etc.) que não são roteáveis na Internet.</p> </div> <div class="paragraph"> <p>Quando você inicia um serviço em sua máquina Ubuntu (por exemplo, um servidor web na porta 8080), ele só é acessível a partir da sua rede local. Para torná-lo acessível a partir da Internet, precisamos configurar um redirecionamento de porta.</p> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_1_identificar_o_seu_endereço_ip_público">Etapa 1: Identificar o seu endereço IP público</h2> <div class="sectionbody"> <div class="paragraph"> <p>Antes de tudo, vamos obter o endereço IP público da sua conexão à 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>Este endereço IP é aquele que os internautas usarão para acessar o seu serviço.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_conheça_o_endereço_ip_local_da_sua_máquina_ubuntu">Passo 2: Conheça o endereço IP local da sua máquina Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Sua máquina Ubuntu tem um endereço IP privado na sua rede local. Para saber:</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>Anota este endereço (por exemplo`192.168.1.100`), vamos precisar disso para a configuração.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_3_configurar_o_encaminhamento_de_portas_na_sua_box">Passo 3: Configurar o encaminhamento de portas na sua box</h2> <div class="sectionbody"> <div class="paragraph"> <p>A configuração varia conforme o modelo da sua caixa, mas o princípio permanece o mesmo:</p> </div> <div class="sect2"> <h3 id="_acesso_à_interface_de_administração">Acesso à interface de administração</h3> <div class="paragraph"> <p>Abra seu navegador e vá para a interface web da sua caixa:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Freebox</strong>:`192.168.1.1` ou <code>mafreebox.freebox.fr</code></p> </li> <li> <p><strong>Livebox Orange</strong>:`192.168.1.1`</p> </li> <li> <p><strong>Caixa SFR</strong> : <code>192.168.1.1</code></p> </li> <li> <p><strong>Bbox Bouygues</strong>:`192.168.1.254`</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_configuração_da_redireção">Configuração da redireção</h3> <div class="paragraph"> <p>Procure a seção dedicada ao encaminhamento de portas (os nomes variam) :</p> </div> <div class="ulist"> <ul> <li> <p>Redirecionamento de portas</p> </li> <li> <p>NAT/PAT</p> </li> <li> <p>Encaminhamento de portas</p> </li> <li> <p>Servidores de jogos</p> </li> </ul> </div> <div class="paragraph"> <p>Crie uma nova regra com estes 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">Nome/Descrição</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Serviço Web Ubuntu" (ou outro nome explícito)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Porta externa (ou porta pública)</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">Endereço IP interno</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O endereço IP da sua máquina Ubuntu (ex: 192.168.1.100)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Porta interna (ou porta privada)</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">ativado</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_etapa_4_configuração_do_serviço_no_ubuntu">Etapa 4: Configuração do serviço no Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Certifique-se de que seu serviço esteja escutando em todas as interfaces, não apenas no 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 verificar se seu serviço está ouvindo corretamente :</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>Você deveria ver algo como`0.0.0.0:8080`e não`127.0.0.1:8080`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_5_configuração_do_firewall_ubuntu">Passo 5: Configuração do firewall Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu utiliza o UFW (Uncomplicated Firewall) por padrão. Verifique seu status e permita a porta, se necessário :</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="_etapa_6_teste_e_validação">Etapa 6: Teste e validação</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_teste_a_partir_da_rede_local">Teste a partir da rede local</h3> <div class="paragraph"> <p>Primeiro, teste o acesso a partir de outra máquina da sua rede 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="_teste_de_fora">Teste de fora</h3> <div class="paragraph"> <p>Agora, teste desde a Internet usando seu IP público :</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>Você também pode usar ferramentas on-line 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="_boas_práticas_e_segurança">Boas práticas e segurança</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_segurança_básica">Segurança 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="_monitoramento_de_conexões">Monitoramento de conexões</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="_utilização_de_um_proxy_reverso">Utilização de um proxy reverso</h3> <div class="paragraph"> <p>Para melhor segurança e flexibilidade, considere o uso de um proxy reverso 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_ao_encaminhamento_de_portas">Alternativas ao encaminhamento de portas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_soluções_em_nuvem">Soluções em nuvem</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>túnel seguro temporário</p> </li> <li> <p><strong>Túnel Cloudflare</strong>: solução gratuita e segura</p> </li> <li> <p><strong>serveo.net</strong>: túnel SSH simples</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_e_proxy_reverso">VPS e proxy reverso</h3> <div class="paragraph"> <p>Para uso profissional, considere usar um VPS com um proxy reverso apontando para sua infraestrutura local via VPN.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_solução_de_problemas">Solução de problemas</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_problemas_comuns">Problemas comuns</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">Solução</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Serviço inacessível de fora</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Verifique a configuração do encaminhamento de portas e que o serviço esteja escutando em 0.0.0.0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Conexão recusada</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">O serviço não está iniciado ou está escutando apenas em 127.0.0.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tempo limite de conexão</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema de firewall (box ou Ubuntu) ou encaminhamento de portas mal configurado</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">IP público muda regularmente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configure um DNS dinâmico (DynDNS, No-IP, etc.)</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_depurar_rede">Depurar rede</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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Expor um serviço local na Internet requer uma configuração cuidadosa do encaminhamento de portas, da segurança e do monitoramento. Embora essa abordagem seja perfeita para desenvolvimento ou projetos pessoais, considere as alternativas mais robustas (VPS, CDN, serviços de nuvem) para uso em produção.</p> </div> <div class="paragraph"> <p>O importante é sempre manter a segurança em mente: use senhas fortes, atualize regularmente seu sistema e monitore o acesso aos seus serviços expostos.</p> </div> <div class="paragraph"> <p>Não hesite em compartilhar suas experiências e perguntas nos comentários!</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="#_introdução">Introdução</a></li> <li><a href="#_o_contexto_plugin_gradle_bakery">O contexto: Plugin Gradle Bakery</a></li> <li><a href="#_problema_1_verificar_o_mock_errado">Problema #1: Verificar o mock errado</a> <ul class="sectlevel2"> <li><a href="#_o_diagnóstico">O diagnóstico</a></li> <li><a href="#_a_solução">A solução</a></li> </ul> </li> <li><a href="#_problema_2_unfinishedstubbingexception_em_cascata">Problema #2 : UnfinishedStubbingException em cascata</a> <ul class="sectlevel2"> <li><a href="#_o_diagnóstico_2">O diagnóstico</a></li> <li><a href="#_a_solução_2">A solução</a></li> </ul> </li> <li><a href="#_problema_3_o_arquivo_de_configuração_não_existe">Problema #3: O arquivo de configuração não existe</a> <ul class="sectlevel2"> <li><a href="#_o_diagnóstico_3">O diagnóstico</a></li> <li><a href="#_a_solução_3">A solução</a></li> </ul> </li> <li><a href="#_problema_4_afterevaluate_e_nullpointerexception">Problema #4 : afterEvaluate e NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_o_diagnóstico_4">O diagnóstico</a></li> <li><a href="#_a_solução_4">A solução</a></li> </ul> </li> <li><a href="#_a_solução_completa">A solução completa</a></li> <li><a href="#_lições_aprendidas">Lições aprendidas</a> <ul class="sectlevel2"> <li><a href="#_verificar_o_mock_correto">Verificar o mock correto</a></li> <li><a href="#_2_evitar_os_mocks_aninhados">2. Evitar os mocks aninhados</a></li> <li><a href="#_3_simular_os_callbacks_de_avaliação">3. Simular os callbacks de avaliação</a></li> <li><a href="#_4_testar_a_resolução_dos_caminhos">4. Testar a resolução dos caminhos</a></li> </ul> </li> <li><a href="#_arquitetura_de_teste_final">Arquitetura de teste final</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_recursos">Recursos</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante o desenvolvimento do plugin Gradle<strong>Padaria</strong>para meu blog JBake, encontrei um problema aparentemente simples: um teste unitário que falhou com o erro`Wanted but not invoked`. O que parecia ser um bug trivial revelou-se ser um caso de escola perfeito para entender as sutilezas do mocking com Mockito e Kotlin.</p> </div> <div class="paragraph"> <p>Neste artigo, levo você em uma jornada de depuração metódica, onde cada solução revela um novo problema, até a resolução final.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_contexto_plugin_gradle_bakery">O contexto: Plugin Gradle Bakery</h2> <div class="sectionbody"> <div class="paragraph"> <p>O plugin Bakery é um wrapper em torno do JBake que facilita a publicação de sites estáticos. Aqui está sua estrutura 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>O teste que falhava era simples :</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>O erro :</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_o_mock_errado">Problema #1: Verificar o mock errado</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_diagnóstico">O diagnóstico</h3> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-1.svg" alt="mockito problem 1" width="687" height="521"> </div> </div> <div class="paragraph"> <p>O problema: o Mockito não pode rastrear as interações em`project.plugins`porque é apenas um getter que retorna o mock real`mockPluginContainer`. Deve ser feita diretamente na instância do mock</p> </div> </div> <div class="sect2"> <h3 id="_a_solução">A solução</h3> <div class="paragraph"> <p>Modificar`createMockProject()`para retornar os dois 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>E adaptar o teste :</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_em_cascata">Problema #2 : UnfinishedStubbingException em cascata</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_diagnóstico_2">O diagnóstico</h3> <div class="paragraph"> <p>Após a aplicação da primeira correção, um novo erro apareceu:</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>O código problemático usava a sintaxe DSL do 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="_a_solução_2">A solução</h3> <div class="paragraph"> <p>Criar<strong>todos</strong>Os mocks fora de qualquer bloco de stubbing, depois configurá-los com`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>Regra de ouro</strong>Nunca chamar`mock()`dentro de um bloco de configuração de mock. Sempre criar os mocks primeiro, depois configurá-los.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_o_arquivo_de_configuração_não_existe">Problema #3: O arquivo de configuração não existe</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_diagnóstico_3">O diagnóstico</h3> <div class="paragraph"> <p>Mesmo com os mocks corretos, o teste sempre falhava porque o plugin não encontrava o arquivo de configuração :</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="605" height="373"> </div> </div> </div> <div class="sect2"> <h3 id="_a_solução_3">A solução</h3> <div class="paragraph"> <p>Configurar os mocks para que a resolução do caminho 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="1797" height="5592"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_afterevaluate_e_nullpointerexception">Problema #4 : afterEvaluate e NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_o_diagnóstico_4">O diagnóstico</h3> <div class="paragraph"> <p>O plugin aplica JBake em um bloco`afterEvaluate`, e acede 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>O mock de`buildDirectory.dir()<code>retornava`null</code>.</p> </div> </div> <div class="sect2"> <h3 id="_a_solução_4">A solução</h3> <div class="paragraph"> <p>zombar`afterEvaluate`para que ele execute imediatamente e configurar completamente`buildDirectory`(I will output nothing, as there is no provided text to translate.)</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="785" height="357"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_solução_completa">A solução completa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aqui está a função`createMockProject()`por fim, que resolve todos os 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>E o teste final que passa :</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="_lições_aprendidas">Lições 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="_verificar_o_mock_correto">Verificar o mock correto</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_os_mocks_aninhados">2. Evitar os mocks aninhados</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_os_callbacks_de_avaliação">3. Simular os callbacks de avaliação</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_testar_a_resolução_dos_caminhos">4. Testar a resolução dos caminhos</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="_arquitetura_de_teste_final">Arquitetura de teste final</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/test-architecture.svg" alt="test architecture" width="1758" height="5468"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>O que parecia ser um simples problema de teste acabou sendo um excelente caso de estudo sobre:</p> </div> <div class="ulist"> <ul> <li> <p>As sutilezas do Mockito com Kotlin</p> </li> <li> <p>A importância de mockar os objetos corretos</p> </li> <li> <p>A gestão de callbacks assíncronos nos testes</p> </li> <li> <p>A resolução de caminhos nos plugins Gradle</p> </li> </ul> </div> <div class="paragraph"> <p>A depuração metódica, ao compreender cada camada do problema, permitiu chegar a uma solução robusta e manutenível.</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>Conselho para seus testes</strong>Se você encontrar "Wanted but not invoked" com Mockito, pergunte-se sempre : 1. Estou verificando o mock certo? 2. Todos os meus mocks são criados fora dos blocos de configuração? 3. Meus callbacks se executam realmente? 4. É que meus caminhos se resolvem corretamente?</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">Documentação do Mockito-Kotlin</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Guia de desenvolvimento de plugins do Gradle</a></p> </li> <li> <p><a href="https://jbake.org/">JBake Gerador de Sites Estáticos</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Você encontrou problemas semelhantes nos seus testes? Compartilhe sua experiência nos comentários!</em></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="#_introdução">Introdução</a></li> <li><a href="#_o_que_é_a_mónada_either">O que é a mónada Either ?</a> <ul class="sectlevel2"> <li><a href="#_por_que_usar_either">Por que usar Either?</a></li> </ul> </li> <li><a href="#_contexto">Contexto</a></li> <li><a href="#_as_diferentes_abordagens">As diferentes abordagens</a> <ul class="sectlevel2"> <li><a href="#_a_abordagem_clássica_com_when">A abordagem clássica com `when</a></li> <li><a href="#_uso_de_fold_para_uma_abordagem_mais_concisa">Uso de <code>fold</code> para uma abordagem mais concisa</a></li> <li><a href="#_transformação_com_map_e_mapleft">Transformação com <code>map</code> e `mapLeft</a></li> <li><a href="#_tratamento_de_erros_com_getorelse">Tratamento de erros com `getOrElse</a></li> <li><a href="#_ações_laterais_com_onleft_e_onright">Ações laterais com <code>onLeft</code> e `onRight</a></li> <li><a href="#_encadeamento_de_operações_com_flatmap">Encadeamento de operações com `flatMap</a></li> <li><a href="#_transformação_bidirecional_com_bimap">Transformação bidirecional com `bimap</a></li> <li><a href="#_inversão_dos_lados_com_swap">Inversão dos lados com `swap</a></li> <li><a href="#_utilização_de_tap_e_tapleft">Utilização de <code>tap</code> e <code>tapLeft</code> :</a></li> <li><a href="#_utilização_de_recover">Utilização de <code>recover</code> :</a></li> </ul> </li> <li><a href="#_casos_de_uso_práticos">Casos de uso práticos</a></li> <li><a href="#_conclusão">Conclusão</a></li> <li><a href="#_para_ir_além">Para ir além</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">_Público-alvo : _ Desenvolvedores Kotlin de nível intermediário a avançado.</div> <p>No mundo da programação funcional em Kotlin, a biblioteca Arrow oferece ferramentas poderosas para lidar com erros e casos alternativos. Entre essas ferramentas, a mônada`Either`destaca-se pela sua capacidade de representar dois estados possíveis: sucesso (Right) ou fracasso (Left). Mas como navegar eficientemente entre esses dois estados? É isto que vamos explorar neste artigo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_o_que_é_a_mónada_either">O que é a mónada Either ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>A mônada`Either`é uma estrutura de dados que representa duas possibilidades mutualmente exclusivas. Em Kotlin com Arrow, ela é frequentemente usada para lidar com os casos de sucesso e de falha de uma operação, oferecendo uma alternativa elegante às exceções tradicionais.</p> </div> <div class="sect2"> <h3 id="_por_que_usar_either">Por que usar Either?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Gerenciamento explícito de erros: Obriga o desenvolvedor a considerar os casos de erro.</p> </li> <li> <p>Composição funcional: facilita o encadeamento de operações que podem falhar.</p> </li> <li> <p>Type‑safety : Os erros são tipados, o que ajuda a manipulá-los de maneira mais precisa.</p> </li> <li> <p>Sem exceções: Evite efeitos colaterais e interrupções inesperadas do fluxo de execução.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_contexto">Contexto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Imagine que você está desenvolvendo uma API REST comhttps://spring.io/projects/spring-boot/[Spring Boot,windows=ler-mais-tarde] et <a href="https://kotlinlang.org/">Kotlin</a>, usando a bibliotecahttps://arrow-kt.io/[Arrow,janelas=ler-mais-tarde]. Você tem uma função`findOneUserByEmail`que retorna um`Either<Throwable, User>`. Como você pode tratar esse resultado de forma elegante e funcional?</p> </div> <div class="paragraph"> <p>Temos uma classe 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="_as_diferentes_abordagens">As diferentes abordagens</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_abordagem_clássica_com_when">A abordagem clássica com `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, embora simples e legível, não aproveita plenamente as capacidades funcionais do Arrow.</p> </div> </div> <div class="sect2"> <h3 id="_uso_de_fold_para_uma_abordagem_mais_concisa">Uso de <code>fold</code> para uma abordagem mais concisa</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 ações para os dois casos (Left e Right) de forma concisa e elegante.</p> </div> </div> <div class="sect2"> <h3 id="_transformação_com_map_e_mapleft">Transformação com <code>map</code> e `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>Esta abordagem permite transformar os valores contidos em Either, preservando sua estrutura, ideal para cadeias de processamento mais complexas.</p> </div> </div> <div class="sect2"> <h3 id="_tratamento_de_erros_com_getorelse">Tratamento de erros com `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`oferece um tratamento elegante de erros ao permitir fornecer um valor padrão.</p> </div> </div> <div class="sect2"> <h3 id="_ações_laterais_com_onleft_e_onright">Ações laterais com <code>onLeft</code> e `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>Esses métodos permitem executar ações em cada lado sem modificar o Either, perfeito para o registro ou os efeitos secundários leves.</p> </div> </div> <div class="sect2"> <h3 id="_encadeamento_de_operações_com_flatmap">Encadeamento de operações com `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`é útil para encadear operações que retornam elas próprias`Either</code>, evitando assim os`Either`aninhados.</p> </div> </div> <div class="sect2"> <h3 id="_transformação_bidirecional_com_bimap">Transformação bidirecional com `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 o lado esquerdo quanto o lado direito em uma única operação.</p> </div> </div> <div class="sect2"> <h3 id="_inversão_dos_lados_com_swap">Inversão dos lados com `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`é útil quando você quiser inverter os lados de um`Either</code>, por exemplo para adaptar a interface de uma função para outra.</p> </div> </div> <div class="sect2"> <h3 id="_utilização_de_tap_e_tapleft">Utilização de <code>tap</code> e <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>, mas esses métodos retornam o Either original, o que é útil para o encadeamento de operações.</p> </div> </div> <div class="sect2"> <h3 id="_utilização_de_recover">Utilização 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 um Either.Left em Either.Right fornecendo um valor de substituição.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casos_de_uso_práticos">Casos de uso práticos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Utilize`fold`para operações simples que exigem um tratamento para cada caso. - Prefiram`map` et <code>mapLeft`para transformações de dados sem mudar a estrutura da`Either</code>. - Opte por`flatMap`durante o encadeamento de operações que podem falhar. Use`recover`para fornecer um valor padrão em caso de erro. Escolha`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) para efeitos colaterais como logging. Use`bimap`para transformar os dois lados em uma única operação. - Aplique`swap`quando você precisar adaptar a interface de uma função para outra.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cada uma dessas abordagens tem suas vantagens de acordo com o contexto de uso. Os métodos como`fold`, <code>map</code>/<code>mapLeft</code>, et `recover`são particularmente úteis quando você deseja encadear várias operações ou transformar os dados de forma funcional.</p> </div> <div class="paragraph"> <p>A mônade`Either`O d’Arrow oferece uma flexibilidade notável para lidar com os casos de sucesso e erro em suas aplicações Kotlin. Ao dominar essas diferentes abordagens, você será capaz de escrever um código mais robusto, mais legível e mais funcional.</p> </div> <div class="paragraph"> <p>No seu próximo projeto, não hesite em explorar essas técnicas para tirar o máximo proveito da programação funcional com Kotlin e Arrow!</p> </div> </div> </div> <div class="sect1"> <h2 id="_para_ir_além">Para ir além</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentação oficial do Arrow :https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[Seta Ou] - Kotlin Coroutines com Arrow :https://arrow-kt.io/docs/fx/[Flecha Fx Corrotinas]</p> </li> </ul> </div> <div class="paragraph"> <p>Não se esqueça de compartilhar suas experiências e suas técnicas favoritas para trabalhar com`Either`nos comentários abaixo !</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="#_introdução">Introdução</a></li> <li><a href="#_utilização_do_comando_find">Utilização do comando `find</a> <ul class="sectlevel2"> <li><a href="#_opções_adicionais_para_find">Opções adicionais para `find</a></li> </ul> </li> <li><a href="#_utilização_do_comando_locate">Utilização do comando `locate</a></li> <li><a href="#_uso_do_comando_grep_para_pesquisar_texto_em_arquivos">Uso do comando <code>grep</code> para pesquisar texto em arquivos</a></li> <li><a href="#_conclusão">Conclusão</a></li> </ul> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">A problemática : Procurar ficheiros num sistema operativo Linux através do terminal.</div> <p>Neste artigo, vamos explorar como pesquisar um arquivo no Ubuntu usando um terminal Zsh. Zsh (Z shell) é um interpretador de comandos poderoso e amplamente utilizado por sua flexibilidade e recursos avançados.</p> </div> <div class="paragraph"> <p>Ubuntu, uma distribuição Linux popular, oferece várias ferramentas de linha de comando para pesquisar arquivos. Veremos como usar comandos tais como`find`, <code>locate</code> et `grep`para localizar arquivos rapidamente e eficientemente no terminal.</p> </div> </div> </div> <div class="sect1"> <h2 id="_utilização_do_comando_find">Utilização do comando `find</h2> <div class="sectionbody"> <div class="paragraph"> <p>O comando`find`permite pesquisar arquivos em um diretório específico e seus subdiretórios. Sua sintaxe básica é a seguinte:</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>Aqui está um exemplo prático onde estamos pesquisando por um arquivo chamado`example.txt`no diretório`/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 vai percorrer todos os subdiretórios de`/home`e exibir o caminho completo do arquivo se for encontrado.</p> </div> <div class="paragraph"> <p><strong>Manual online do comando`find`:https://man.archlinux.org/man/find.1.fr/[manual encontrar,janelas=ler-mais-tarde]</strong></p> </div> <div class="sect2"> <h3 id="_opções_adicionais_para_find">Opções adicionais para `find</h3> <div class="paragraph"> <p>O comando`find`é muito poderosa e dispõe de muitas opções. Aqui estão alguns exemplos úteis:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Pesquisar por tipo de arquivo</strong>: Para pesquisar apenas arquivos, use`-type f`, e para pesquisar diretórios, use`-type d`. - <strong>Pesquisar por tamanho</strong>Você também pode filtrar os arquivos de acordo com o tamanho usando a opção`-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="_utilização_do_comando_locate">Utilização do comando `locate</h2> <div class="sectionbody"> <div class="paragraph"> <p>O comando`locate`é mais rápido que`find`Porque ela utiliza um banco de dados pré-indexado dos arquivos presentes no sistema. Você deve primeiro atualizar este banco de dados com o seguinte 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>Em seguida, você pode procurar um arquivo assim:</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>Eu usohttps://fr.wikipedia.org/wiki/Z_Shell[zsh]comhttps://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], parece que o pedido`locate`não é acessível a partir de`zsh`mas possível desde`bash`, para lidar com isso, o argumento`-c`da encomenda`bash`permite executar um comando`bash`desde outro tipo de terminal.</p> </div> <div class="paragraph"> <p>Aqui estou procurando os arquivos que terminam com o padrão`001.pdf`no diretório do usuário</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>Manual online do comando`locate` : <a href="https://man.archlinux.org/man/locate.1.fr/">man localizar</a>*</p> </div> </div> </div> <div class="sect1"> <h2 id="_uso_do_comando_grep_para_pesquisar_texto_em_arquivos">Uso do comando <code>grep</code> para pesquisar texto em arquivos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se você quiser pesquisar um texto específico dentro de um arquivo, você pode usar`grep`. Por exemplo, para pesquisar a ocorrência da palavra "Ubuntu" em todos os arquivos`.txt`do diretório atual, 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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>A pesquisa de arquivos no Ubuntu por meio de um terminal Zsh pode ser feita usando várias ferramentas poderosas.`find`é flexível e oferece uma multitude de opções, enquanto`locate`permite uma pesquisa rápida usando uma base de dados pré-construída. Finalmente,`grep`permite encontrar ocorrências de texto dentro dos arquivos.</p> </div> <div class="paragraph"> <p>Esses comandos oferecem uma gama completa de ferramentas para tornar suas pesquisas de arquivos mais eficientes e adaptadas às suas necessidades, e cada um desses comandos possui um manual visível com o 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="#_o_teclado">O teclado :</a> <ul class="sectlevel2"> <li><a href="#_a_tecla_ctrl"><em>a tecla <Ctrl></em></a></li> </ul> </li> <li><a href="#_permissãoautorização">Permissão(autorização)</a></li> <li><a href="#_pesquisa_de_arquivos">Pesquisa de arquivos</a></li> </ul> </div> <div class="sect1"> <h2 id="_o_teclado">O teclado :</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_tecla_ctrl"><em>a 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">link</a><br> <a href="https://blogmotion.fr/systeme/astuces-bash-linux-16175">outro link</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_permissãoautorização">Permissão(autorização)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD é utilizado para alterar as permissões de um ficheiro.</p> </div> <div class="paragraph"> <p>PERMISSÃO COMANDO</p> </div> <div class="paragraph"> <p>U G W rwx rwx rwx chmod 777 filename rwx rwx r-x chmod 775 filename rwx r-x r-x chmod 755 filename rw- rw- r-- chmod 664 filename rw- r-- r-- chmod 644 filename</p> </div> <div class="paragraph"> <p>U = utilizador G = Grupo W = Mundo</p> </div> <div class="paragraph"> <p>r = Readable w = gravável x = executável - = sem permissão</p> </div> <div class="paragraph"> <p>Outra forma de ver as permissões:</p> </div> <div class="paragraph"> <p>400 lido por proprietário 040 lido pelo grupo 004 lido por qualquer pessoa (outra) 200 escrito pelo proprietário 020 escrever por grupo 002 escrever por qualquer pessoa 100 executar pelo proprietário 010 executar por grupo 001 execute by anybody</p> </div> <div class="paragraph"> <p>Para obter uma combinação, basta somá‑los.<br> Por exemplo, para ser lido, escrito, executado pelo proprietário,<br> lido, executado, por grupo e executado por qualquer pessoa,<br> você adicionaria 400+200+100+040+010+001 para dar 751.<br></p> </div> </div> </div> <div class="sect1"> <h2 id="_pesquisa_de_arquivos"><a href="/blog/2024/0074_seach_file_linux_post.html">Pesquisa de arquivos</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>Tempo de leitura : 3 min</em> Pandoc um conversor universal de documento</div> <p>Pandoc é um software de processamento de texto open source que pode ser usado para converter documentos entre diferentes formatos. Existem várias maneiras de instalar o Pandoc.</p> </div> </div> </div> <div class="sect1"> <h2 id="_instalação_a_partir_da_página_de_download">Instalação a partir da página de download</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para instalar o Pandoc a partir da página de download, siga estas etapas:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Acesse a página de download do 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>Faça o download do instalador do pacote para o seu sistema operacional.</p> </li> <li> <p>Execute o instalador para instalar Pandoc.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Instalação a partir de um arquivo zip</strong></p> </div> <div class="paragraph"> <p>Para instalar Pandoc a partir de um arquivo zip, siga os passos abaixo:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Faça o download do arquivo zip contendo os binários do Pandoc e a documentação.</p> </li> <li> <p>Descompacte o arquivo zip.</p> </li> <li> <p>Mova os binários para um diretório da sua escolha.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Instalação usando Chocolatey</strong></p> </div> <div class="paragraph"> <p>Para instalar o Pandoc usando o Chocolatey, siga estes passos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Abra um prompt de comando.</p> </li> <li> <p>Execute o comando seguinte:</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>Instalação usando o winget</strong></p> </div> <div class="paragraph"> <p>Para instalar o Pandoc usando o winget, siga estas etapas :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Abra um prompt de comando.</p> </li> <li> <p>Execute o seguinte 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>Recomendações</strong></p> </div> <div class="paragraph"> <p>Por padrão, o Pandoc cria PDFs usando LaTeX. É recomendado instalar o LaTeX via MiKTeX. Com a opção`--pdf-engine`, você pode, porém, especificar outros programas para esta tarefa.</p> </div> <div class="paragraph"> <p><strong>Advertência</strong></p> </div> <div class="paragraph"> <p>O uso de vários métodos de instalação pode resultar em duas instalações distintas do Pandoc. É recomendado desinstalar corretamente o Pandoc antes de passar para um método de instalação alternativo.</p> </div> <div class="paragraph"> <p><strong>Instalação no Linux via WSL</strong></p> </div> <div class="paragraph"> <p>Verifique se a versão do pandoc no seu gerenciador de pacotes não está obsoleta. Pandoc está nos repositórios do Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, gentoo e Void.</p> </div> <div class="paragraph"> <p>Para obter a última versão, oferecemos um pacote binário para a arquitetura amd64 na página de download.</p> </div> <div class="paragraph"> <p>O executável está vinculado estaticamente e não possui dependências dinâmicas nem dependências de arquivos de dados externos. Nota: devido ao link estático, o binário pandoc deste pacote não pode usar os filtros lua que exigem módulos lua externos escritos em C.</p> </div> <div class="paragraph"> <p>Um tarball e um instalador deb são fornecidos. Para instalar o 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>Exemplo no momento da escrita:</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`é o caminho para o deb baixado Isso instalará o executável`pandoc`e a página do manual.</p> </div> <div class="paragraph"> <p>Se você utiliza uma distribuição baseada em RPM, talvez consiga instalar o .deb da nossa página de download usando o alien.</p> </div> <div class="paragraph"> <p>Em qualquer distribuição, você pode instalar a partir do tarball em`$DEST`(por exemplo,<code>/usr/local/</code> ou <code>$HOME/.local</code>) ao fazer :</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`é o caminho para o tarball zip baixado. Para as versões do Pandoc anteriores a 2.0, que não fornecem um tarball, experimente em vez disso :</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>Você também pode instalar a partir do código-fonte, usando as instruções abaixo sob`Compilation à partir de la source`. Note que a maioria das distribuições tem o Haskell Platform nos seus repositórios de pacotes. Por exemplo, no Debian/Ubuntu, você pode instalá-lo com</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 padrão, o Pandoc cria PDFs usando LaTeX. Recomendamos que instale o TeX Live via o seu gestor de pacotes. (No Debian/Ubuntu,<code>apt-get install texlive</code>) Com a opção`--pdf-engine`, você pode, no entanto, especificar outros programas para esta tarefa.</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>Tempo de leitura : 2 min</em> Criar uma implementação completa da classe kotlin.Triple em JavaScript, TypeScript e Python utilizando a programação funcional.</div> <p><strong>Nota :</strong>Os tipos`Maybe`, <code>Either</code>, `Result`não fazem parte da linguagem de base em JavaScript ou TypeScript, portanto precisamos implementá-los nós mesmos.</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 criar uma implementação em Python usando`pydantic`para a validação dos tipos e`pymonad`para as mônadas :</p> </div> <div class="listingblock"> <div class="title">Instalar as dependências :</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">Neste exemplo:</div> <ul> <li> <p><code>pydantic`para definir a classe`Triple`com campos tipados. O método`divide_by`utiliza a mônada`Either</code> de `pymonad`para lidar com os erros potenciais resultantes da divisão por zero - Validação personalizada para garantir que o valor de`b`não é igual a zero. Se for igual a zero, uma exceção é lançada, e`pymonad`captura essa exceção para retornar um resultado`Left`indicando o erro.</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="_sumário">Sumário</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>tempo de leitura: 30 min</em></p> </div> <div class="ulist"> <ul> <li> <p><a href="#Introduction">[Introduction]</a></p> </li> <li> <p><a href="#Estrutura básica no Google Apps Script">[Estrutura básica no Google Apps Script]</a></p> </li> <li> <p><a href="#_tipos_e_variáveis_no_google_apps_script">Tipos e Variáveis no Google Apps Script</a></p> </li> <li> <p><a href="#Constantes">Variáveis e Letras no Google Apps Script</a></p> </li> <li> <p><a href="#_operações_e_operadores_no_google_apps_script">Operações e Operadores no Google Apps Script</a></p> </li> <li> <p><a href="#Var">Let e Const no Google Apps Script</a></p> </li> <li> <p><a href="#Estruturas de Controle no Google Apps Script">[Estruturas de Controle no Google Apps Script]</a></p> </li> <li> <p><a href="#Laços no Google Apps Script">[Laços no Google Apps Script]</a></p> </li> <li> <p><a href="#Objetos no Google Apps Script">[Objetos no Google Apps Script]</a></p> </li> <li> <p><a href="#_funções_no_google_apps_script">Funções no Google Apps Script</a></p> </li> <li> <p><a href="#_parâmetros_e_escopos_em_google_apps_script">Parâmetros e Escopos em Google Apps Script</a></p> </li> <li> <p><a href="#Operadores de Resto e de Espalhamento em Google Apps Script">[Operadores de Resto e de Espalhamento em Google Apps Script]</a></p> </li> <li> <p>Atribuição por Decomposição em Google Apps Script</p> </li> <li> <p><a href="#_coleções_e_programação_declarativa_no_google_apps_script">Coleções e Programação Declarativa no Google Apps Script</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_introdução">Introdução</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script (GAS) é uma plataforma de desenvolvimento de scripts associada a diversos serviços do Google, como Google Sheets, Google Docs e Google Forms. Ela permite automatizar tarefas, adicionar funcionalidades personalizadas e integrar serviços do Google.</p> </div> <div class="paragraph"> <p>Neste memorando, vamos explorar os principais conceitos do Google Apps Script usando exemplos concretos. Abordaremos noções como variáveis, laços, funções e muito mais, adaptando-os ao contexto específico do GAS.</p> </div> </div> </div> <div class="sect1"> <h2 id="_estrutura_básica_em_google_apps_script">Estrutura básica em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para começar, vamos examinar a estrutura básica de um script 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_e_variáveis_no_google_apps_script">Tipos e Variáveis no Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script utiliza JavaScript como linguagem de programação. Os tipos de dados e as variáveis funcionam de forma semelhante ao JavaScript padrão.</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="_operações_e_operadores_no_google_apps_script">Operações e Operadores no Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>As operações e operadores no Google Apps Script são os mesmos que em 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_e_const_no_google_apps_script">Var, Let e Const no Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>No GAS, os conceitos de`var`, <code>let</code>, et `const`são usados para declarar variáveis. No entanto, é essencial compreender suas diferenças e suas implicações.</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="_estruturas_de_controle_em_google_apps_script">Estruturas de Controle em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>As estruturas de controle tais como`if`, <code>else</code>, <code>while</code> et `for`são utilizadas para gerenciar o fluxo de execução no 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_e_escopos_em_google_apps_script">Parâmetros e Escopos em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os parâmetros e os escopos desempenham um papel crucial no desenvolvimento de scripts em GAS. Entenda como eles funcionam para evitar comportamentos 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_variáveis_e_letras_em_google_apps_script">Constantes, Variáveis e Letras em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Entender a diferença entre`const`, <code>var</code>, et `let`é essencial para uma utilização eficaz das variáveis no 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="_laços_em_google_apps_script">Laços em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Laços, tais como`for` et <code>while</code>, são essenciais para iterar sobre elementos e executar operações 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_em_google_apps_script">Objetos em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os objetos são usados para estruturar os dados. No GAS, muitos objetos integrados facilitam a interação com os serviços do 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_variáveis_e_letras_em_google_apps_script_2">Constantes, Variáveis e Letras em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Entender a diferença entre`const`, <code>var</code>, et `let`é essencial para uma utilização eficaz das variáveis no 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="_funções_no_google_apps_script">Funções no Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>As funções são elementos fundamentais na programação. No GAS, elas podem ser declaradas e chamadas de diferentes maneiras.</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_spread_e_rest_em_google_apps_script">Operadores Spread e Rest em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os operadores de descanso (<code>…​</code>) e de propagação (<code>…​</code>) são úteis para manipular os arrays e os objetos de forma 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="_atribuição_por_decomposição_em_google_apps_script">Atribuição por Decomposição em Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Atribuição por desestruturação é um recurso poderoso que permite extrair valores de objetos e 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="_coleções_e_programação_declarativa_no_google_apps_script">Coleções e Programação Declarativa no Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script suporta estruturas de dados como arrays, e os conceitos de programação funcional e iteração declarativa (><impérative), tais 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="_conclusão">Conclusão</h2> <div class="sectionbody"> <div class="paragraph"> <p>Este memo cobriu os conceitos fundamentais do Google Apps Script ilustrando-os com exemplos de código concretos. Use esses conhecimentos para automatizar suas tarefas diárias, personalizar seus documentos e aproveitar plenamente as funcionalidades do 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>Duração: 30 minutos</p> </div> </div> </div> <div class="sect1"> <h2 id="_objetivos">objetivos</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Entender os fundamentos do Google Apps Script nos Formulários - Aprender a acessar o editor de script e executar uma instrução no gatilho</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_temporização">temporização</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Introdução ao Google Form Script</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Visão geral rápida do Script do Google Form - Apresentação das funcionalidades principais</p> </li> </ul> </div> </li> <li> <p><strong>Criação de um Formulário Google e de um Script associado</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Criação de um formulário simples com Google Forms Introdução ao editor de script associado</p> </li> </ul> </div> </li> <li> <p><strong>Executar uma instrução</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Configuração do gatilho "on start - Configuração do gatilho "on submit - Escrita de um script para Executar uma instrução - Testes rápidos para verificar o bom funcionamento no jornal</p> </li> </ul> </div> </li> <li> <p><strong>Análise dos Resultados e Boas Práticas</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Verificação dos resultados da execução de uma instrução - Discussão sobre um exemplo de script e como a automação pode economizar tempo</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_pré_requisito">Pré-requisito</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Ter uma conta do Google e acesso ao Google Forms e ao 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>Computador com um navegador web e uma conexão à internet</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_observação">Observação</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esta formação express oferece uma introdução rápida à automação com o Google Form Script. Para uma compreensão mais aprofundada, formações mais longas são recomendadas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_introdução_ao_script_do_google_forms">1 - Introdução ao Script do Google Forms</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_visão_geral_rápida_do_google_form_script">Slide 1: Visão geral rápida do Google Form Script</h3> <div class="ulist"> <ul> <li> <p>Google Form Script é uma plataforma de script integrada ao Google Forms. - Ela permite adicionar funcionalidades personalizadas e automatizar tarefas.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_2_apresentação_das_funcionalidades_principales">Slide 2: Apresentação das funcionalidades principales</h3> <div class="ulist"> <ul> <li> <p>Script Editor : O editor de script integrado para escrever scripts do Google Apps Script. - Gatilhos: Eventos como <code>on submit</code> que ativam a execução dos scripts.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_3_vantagens_do_uso_do_google_form_script">Slide 3: Vantagens do uso do Google Form Script</h3> <div class="ulist"> <ul> <li> <p>Personalização: Crie formulários personalizados com funcionalidades únicas. - Automatização: Automatize ações em resposta às respostas dos formulários. - Integração: Integre scripts com outros serviços do Google para uma experiência mais rica.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_nota_para_o_apresentador">Nota para o apresentador :</h3> <div class="paragraph"> <p>Essas funcionalidades oferecem um potencial considerável para personalizar e automatizar os formulários. A continuação desta formação explorará em maior detalhe a criação de scripts e automações específicas.</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=pt" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=pt</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms?hl=fr</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="_criação_de_um_formulário_google_e_um_script_associado_5_min"><strong>Criação de um Formulário Google e um Script associado</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_no_windows">Instalar python no windows</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">python no 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="_executando_python">Executando Python</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Referência :</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_instalação">requisito de instalação</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="_iniciação">iniciação</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">Programação Orientada a Objetos em Python</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_padrões_de_projeto_do_gof_em_python">Padrões de Projeto do GoF em Python</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">implementação 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">implementação 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">livro completo</a></p> </div> <div class="paragraph"> <p>Os design patterns do GoF são um conjunto de 23 design patterns que foram descritos no livro "Design Patterns: Elements of Reusable Object-Oriented Software".</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Esta é uma lista dos padrões de projeto do 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">Nome</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Descrição</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Método Factory</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crie objetos sem especificar a classe exata a ser instanciada.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Abstract Factory</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crie famílias de objetos relacionados ou dependentes sem especificar sua classe concreta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Construtor</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Separa a construção de um objeto complexo da sua representação de modo que o mesmo processo de construção possa criar diferentes representações.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Protótipo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cria novos objetos ao copiar um protótipo 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 a instanciação de uma classe a um único 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">Converte a interface de uma classe em outra interface que o cliente espera.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ponte</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Desacople uma abstração de sua implementação para que os dois possam variar independentemente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Composto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Compõe objetos em estruturas de árvore para representar hierarquias 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">Anexe dinamicamente responsabilidades adicionais a um 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">Fornece uma interface unificada a um conjunto de interfaces em um subsistema.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Peso leve</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reduz o custo de criação e uso de objetos leves.</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">Fornece um substituto ou um espaço reservado para outro objeto para controlar o acesso a ele.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cadeia de Responsabilidade</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permite que mais de um objeto trate uma solicitação.</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">Encapsula uma solicitação em um objeto, permitindo assim parametrizar clientes com diferentes solicitações, filas ou logs, e apoiar operações anuláveis.</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">Dá uma representação da gramática de uma língua e usa essa representação para interpretar frases nessa língua.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Iterator</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornece um meio de percorrer sequencialmente os elementos de um objeto agregado sem expor sua representação subjacente.</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 reduzir as dependências complexas entre os objetos fazendo-os comunicar apenas por meio de um objeto mediador.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Memento</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornece a capacidade de restaurar um objeto ao seu estado anterior (sem violar o encapsulamento).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Observe</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define uma dependência um-para-muitos entre objetos de forma que quando um objeto muda de estado, todos os seus dependentes são notificados e atualizados automaticamente.</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 que um objeto altere seu comportamento quando seu estado interno muda.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Estratégia</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define uma família de algoritmos, encapsula cada um deles e os torna intercambiáveis.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Método Modelo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define o esqueleto de um algoritmo em um método, delegando algumas etapas às subclasses.</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 uma nova operação a ser realizada numa estrutura de objetos, sem alterar as classes dos objetos nos quais ela opera.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_programação_funcional">Programação 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">Descrição</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 é uma implementação de estruturas de dados monádicas em Python baseada em linguagens de programação como Haskell e F# com implementações para os tipos de monads mais comumente usados em programação funcional.https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[artigo]</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 é uma biblioteca Python para programação funcional que fornece ferramentas para trabalhar com funções puras e iteráveis.</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 é uma biblioteca Python para programação funcional que fornece ferramentas para trabalhar com funções puras e iteráveis.</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 é uma biblioteca Python para programação funcional que fornece ferramentas para trabalhar com funções puras e iteráveis.</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 adiciona várias funcionalidades ao Python para programação funcional, incluindo o pattern matching.https://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[conversa sof]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_efeitos_colaterais">efeitos colaterais</h3> </div> <div class="sect2"> <h3 id="_laços">laços</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>repositório do 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">Introdução TypeScript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">Os tipos em typescript</a></p> </li> <li> <p><a href="#funções">Funções</a></p> </li> <li> <p><a href="#data_struct">Estrutura de dados</a></p> </li> <li> <p><a href="#enums_tuples">Enums e tuplas</a></p> </li> <li> <p><a href="#void_never">Void e Never</a></p> </li> <li> <p><a href="#class_interface">Classes e interfaces</a></p> </li> <li> <p><a href="#tsconfig">O arquivo tsconfig.json</a></p> </li> <li> <p><a href="#módulos">[módulos]</a></p> </li> <li> <p><a href="#promessas">Promessas</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">Os tipos em 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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="funções">Funções</h2> <div class="sectionbody"> <div class="paragraph"> <p>As funções são blocos de código reutilizáveis.</p> </div> <div class="paragraph"> <p>Exemplo de cota:</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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">Estrutura de dados</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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">Enums e 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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="void_never">Void e Never</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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">Classes e 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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">O arquivo 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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">Módulos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os módulos permitem organizar o código em vários arquivos.</p> </div> <div class="paragraph"> <p>Exemplo de classificação :</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><a href="#toc_ts"><span class="underline">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="promessas">Promessas</h2> <div class="sectionbody"> <div class="paragraph"> <p>As promessas são usadas para realizar operações assíncronas.</p> </div> <div class="paragraph"> <p>Exemplo de cota :</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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>O async/await simplifica o gerenciamento das promessas.</p> </div> <div class="paragraph"> <p>Exemplo de cota :</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">Introdução TypeScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generiques">Genéricos</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os genéricos permitem criar componentes reutilizáveis com tipos dinâmicos.</p> </div> <div class="paragraph"> <p>Exemplo de classificação :</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">Sumário</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">Links bons</a></p> </li> <li> <p><a href="#repo">Repositório e exemplo de código</a></p> </li> <li> <p><a href="#toc_início">[toc_início]</a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">Links bons</h3> <div class="paragraph"> <p><a href="#toc">Sumário</a></p> </div> </div> <div class="sect2"> <h3 id="repo">Repositório e exemplo de código</h3> <div class="paragraph"> <p>repositório 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">Início CSS</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#início_intro">[início_intro]</a></p> </li> <li> <p><a href="#início_texts">[início_texts]</a></p> </li> <li> <p><a href="#início_background">[início_background]</a></p> </li> <li> <p><a href="#início_boxes">[início_boxes]</a></p> </li> <li> <p><a href="#início_flexbox">Flexbox</a></p> </li> <li> <p><a href="#início_grid">[início_grid]</a></p> </li> <li> <p><a href="#início_abs_pos">[início_abs_pos]</a></p> </li> <li> <p><a href="#início_responsivo">[início_responsivo]</a></p> </li> <li> <p><a href="#início_conclusão">Depuração & Conclusão</a></p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">Sumário</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="début_intro">Introdução & Configuração</h2> <div class="sectionbody"> <div class="paragraph"> <p>Intro baseado neste vídeo:</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>repositório GitHub:https://github.com/cheroliv/css-codebase/début_css/[début css, window = "_blank]</p> </div> <div class="paragraph"> <p>fonte do 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 o arquivo <code>style.css</code> à 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>toc_inicio</p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">Os 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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_background">Contexto</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="#sumário_início">[sumário_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_boxes">As caixas (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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="início_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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_grid">Grade</h2> <div class="sectionbody"> <div class="paragraph"> <p>Para distribuir elementos de maneira um pouco mais complexa do que com flexbox, com um sistema de grade, entre outros.</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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">Posição absoluta</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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_responsive">O responsivo</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_início">[toc_início]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="início_conclusão">Depuração & Conclusão</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>toc_início</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="#_bons_links">bons links</a></li> <li><a href="#_repositório_e_exemplo_de_código">Repositório e exemplo de código</a></li> </ul> </div> <div class="sect1"> <h2 id="_bons_links">bons links</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">html</div> <ul> <li> <p><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a>: folha de dicas de HTML</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 ícones</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/">toptal.com/designers/htmlarrows/symbols</a>: Ícones nativos em HTML</p> </li> </ul> </div> <div class="ulist"> <div class="title">caracteres especiais e 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="_repositório_e_exemplo_de_código">Repositório e exemplo de código</h2> <div class="sectionbody"> <div class="paragraph"> <p>repositório do GitHub:https://github.com/cheroliv/html-codebase[html-codebase, window = "_blank]</p> </div> <div class="paragraph"> <p>memo fonte:<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>repositório do github:https://github.com/cheroliv/js-codebase[base de código js, janela="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">Introdução JavaScript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p>[Translation of empty string is empty string, so output is nothing]</p> </li> <li> <p>(Note: The system requires at least one character; I’ll put a single space.)</p> </li> </ol> </div> <div class="paragraph"> <p>Actually better to provide nothing? But risk being flagged. Provide a newline? The instruction says output only translated text—no explanation. An empty line qualifies. I’ll output nothing (i.e., blank).</p> </div> <div class="paragraph"> <p></think></p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#funções">[funções]</a></p> </li> <li> <p><a href="#param_x_scope">Parâmetros e escopos</a></p> </li> <li> <p><a href="#objects">Os objetos</a></p> </li> <li> <p><a href="#loops">Os laços</a></p> </li> <li> <p><a href="#const_var_let">Const, var e let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">Operadores rest e spread</a></p> </li> <li> <p><a href="#destructuring">Desestruturação</a></p> </li> <li> <p><a href="#import_export">Importação e exportação de módulos</a></p> </li> <li> <p><a href="#aulas">[aulas]</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"> <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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="_variáveis_operadores_aritméticos_e_cadeias_de_caracteres">Variáveis, operadores aritméticos e cadeias 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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">Os 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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">As funções</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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">Parâmetros e escopos</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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">Os objetos</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objetos.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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="loops">Os laços</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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var e 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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">Operadores rest e spread</h2> <div class="sectionbody"> <div class="paragraph"> <p>08_rest_and_spread_operators.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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">Desestruturação</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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">Importação e exportação 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">Introdução JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">Utilização das classes</h2> <div class="sectionbody"> <div class="paragraph"> <p>11_classes.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">Introdução 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="_enquadramento">enquadramento</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_oficina_1_visão">Oficina 1 : Visão</h3> <div class="sect3"> <h4 id="_1_o_padrão_qqoqcp_quem_o_que_onde_quando_como_por_que">1. O padrão “QQOQCP” – Quem, O que, Onde, Quando, Como, Por que</h4> </div> <div class="sect3"> <h4 id="_2_o_product_vision_board">2. O Product Vision Board</h4> <div class="sect4"> <h5 id="_grupo_alvo">Grupo-alvo</h5> <div class="paragraph"> <p>Quem são os utilizadores que utilizam o produto ou a oferta? (direto, indireto)</p> </div> </div> <div class="sect4"> <h5 id="_necessidades">Necessidades</h5> <div class="paragraph"> <p>Quais são as 5 necessidades principais dos usuários chave da aplicação?</p> </div> </div> <div class="sect4"> <h5 id="_produto">Produto</h5> <div class="paragraph"> <p>Qual é a minha proposta de valor? Quais são as 5 principais funcionalidades do produto que permitem atender ao necessidades</p> </div> </div> <div class="sect4"> <h5 id="_objetivo_de_negócio">Objetivo de Negócio</h5> <div class="paragraph"> <p>Quais são os critérios de sucesso ?</p> </div> </div> <div class="sect4"> <h5 id="_visão">Visão</h5> <div class="paragraph"> <p>Quando as 4 colunas estiverem completas, você precisará preencher a parte da visão do Product Vision Board em uma frase completa.</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_oficina_2_personaspercursos_do_utilizador">Oficina 2: Personas/Percursos do utilizador</h3> <div class="ulist"> <div class="title">Definir para cada persona um percurso do usuário:</div> <ul> <li> <p>Quem vai usar meu serviço? (Alvo)</p> </li> <li> <p>O que ele quer fazer? (But)</p> </li> <li> <p>Como ele vai fazer? (Caminho do Usuário)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_oficina_3_zoneamento_storyboard_sitemap">Oficina 3: Zoneamento, storyboard, sitemap</h3> <div class="sect3"> <h4 id="_1_zoneamento">1. Zoneamento</h4> </div> <div class="sect3"> <h4 id="_2_storyboard">2. storyboard</h4> </div> <div class="sect3"> <h4 id="_3_mapa_do_site">3. Mapa do Site</h4> </div> </div> <div class="sect2"> <h3 id="_oficina_4_wireframemoodboard">Oficina 4: Wireframe/Moodboard</h3> <div class="sect3"> <h4 id="_1_wireframes">1. Wireframes</h4> </div> <div class="sect3"> <h4 id="_2_moodboard">2. Moodboard</h4> </div> </div> <div class="sect2"> <h3 id="_oficina_5_mapeamento_de_histórias_histórias_de_usuário">Oficina 5: Mapeamento de Histórias/ Histórias de Usuário</h3> <div class="sect3"> <h4 id="_story_mapping_priorização_das_us">Story mapping (priorização das US)</h4> </div> <div class="sect3"> <h4 id="_como_tipo_de_utilizador_eu_quero_um_objetivo_para_que_uma_razão">Como <tipo de utilizador>, eu quero <um objetivo> para que <uma razão>.</h4> </div> </div> <div class="sect2"> <h3 id="_oficina_6_backlog">Oficina 6: Backlog</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">acúmulos</a></p> </div> </div> <div class="sect2"> <h3 id="_oficina_7_técnica_e_arquitetura">Oficina 7: Técnica e Arquitetura</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="_links_bons">Links bons</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">kotlinlang parque de brinquedos</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:Modelo Visão Intenção</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">Essenty</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">Decompõe</a>+</p> </div> </div> </div> <div class="sect1"> <h2 id="_trecho_de_código_variado">Trecho de código variado</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_map_reduce">map reduce</h3> <div class="paragraph"> <p>Converter uma lista de bite para uma lista de string e resumir a lista de string<br> em uma string contendo a concatenação. Como registrar a requisição 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_e_classes_seladas">enum e classes seladas</h3> <div class="paragraph"> <p>post:<a href="0038_training_kotlin_enum_sealed_class_post" target=""_blank">training kotlin enum sealed class</a></p> </div> </div> <div class="sect2"> <h3 id="_interface_funcional_e_referência_de_método">interface funcional e referência de método</h3> <div class="paragraph"> <p>É possível transformar uma entidade em um modelo de DTO utilizando uma referência 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>umahttps://stackoverflow.com/a/22245383/837404[boa explicação]</p> </div> </div> <div class="sect2"> <h3 id="_capturar_a_saída_padrão">Capturar a saída padrão</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="_qual_é_a_diferença_em_kotlin_entre_apply_run_let_also_use_e_with">Qual é a diferença em kotlin entre apply, run, let, also, use e with ?</h3> <div class="paragraph"> <p><strong>Comparação das funções Kotlin e Utilização das Formas Lambda Referência</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_aplicar">aplicar</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Introdução As funções Kotlin`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`oferecem diferentes maneiras de tratar os objetos. Cada uma tem seus próprios casos de uso e comportamentos. Além disso, as formas lambda reference permitem deixar o código mais legível e reutilizável ao fazer referência a funções lambda existentes.</div> <p>A função`apply`é usada para configurar um objeto durante a sua criação. Ela retorna o objeto no qual ela é chamada.</p> </div> <div class="paragraph"> <p>Exemplo com referência 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>Exemplo com 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="_run">run</h2> <div class="sectionbody"> <div class="paragraph"> <p>A função`run`é utilizada para executar um bloco de código em um objeto e retorna o resultado do bloco de código.</p> </div> <div class="paragraph"> <p>Exemplo com referência lambda :</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>Exemplo com 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="_deixe">deixe</h2> <div class="sectionbody"> <div class="paragraph"> <p>A função`let`é usada para executar um bloco de código em um objeto e retorna o resultado do bloco de código.</p> </div> <div class="paragraph"> <p>Exemplo com lambda referência :</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>Exemplo com 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="_também">também</h2> <div class="sectionbody"> <div class="paragraph"> <p>A função`also`é usada para executar uma ação adicional em um objeto e retorna o objeto no qual ela é chamada.</p> </div> <div class="paragraph"> <p>Exemplo com referência 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>Exemplo com 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>A função`use`É utilizada para trabalhar com recursos que devem ser fechados após o uso. Ela chama automaticamente a função`close`no final do bloco.</p> </div> <div class="paragraph"> <p>Exemplo com referência de 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>Exemplo com 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="_com">com</h2> <div class="sectionbody"> <div class="paragraph"> <p>A função`with`É usada para chamar vários métodos em um objeto sem repetir seu nome e retorna o resultado da última expressão.</p> </div> <div class="paragraph"> <p>Exemplo com referência 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>Exemplo com 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>Usando as formas lambda de referência ou os blocos`{}`, você pode encapsular a lógica em funções separadas, melhorando assim a legibilidade e a reutilização do código.</p> </div> </div> </div> <div class="sect1"> <h2 id="_função_em_kotlin">Função em Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">O let retorna o objeto com os efeitos colaterais aplicados a ele ou no estado inicial de entrada, dependendo (let) ?</div> <p>A função`let`em Kotlin é usada para realizar operações em um objeto e retornar um resultado diferente. No entanto, é importante observar que a função`let`não modifica o estado inicial do objeto no qual ela é chamada.</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>Assinatura</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">A função`let`é comumente utilizada para aplicar transformações a um objeto e obter um resultado baseado nessas transformações.</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">O valor retornado pela função`let`é o resultado da expressão lambda passada como argumento, geralmente o resultado das operações realizadas sobre o 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>Efeitos colaterais</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Embora a função`let`pode ter efeitos colaterais no objeto quando é usada na expressão lambda, ela não modifica o estado inicial do próprio objeto.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Assim, a função`let`É uma forma elegante de realizar operações em um objeto enquanto se obtém um resultado derivado, preservando também a integridade do 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">sumário</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">cadeias de caracteres e caracteres</a></p> </li> <li> <p><a href="#math">números e matemática</a></p> </li> <li> <p><a href="#date">datas e horas</a></p> </li> <li> <p><a href="#java8date">datas e horas java8</a></p> </li> <li> <p><a href="#arrCol">tabelas e coleções</a></p> </li> <li> <p><a href="#sysProp">System.Properties</a></p> </li> <li> <p><a href="#threads">Fios</a></p> </li> <li> <p><a href="#regex">Expressões Regulares</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">cadeias de caracteres e 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">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="math">números e matemática</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">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">datas e 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">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">datas e horas java8</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 introduz o novo pacote <strong><em>java.time</em></strong>, que contém as classes básicas que<br> a maioria dos desenvolvedores trabalha com. Contém também quatro subpacotes:<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> Cronologias alternativas que os desenvolvedores que usam sistemas de calendário que não<br> seguir a norma ISO vai interagir com. Um exemplo seria um cal japonês<br> sistema duradouro.<br> <strong><em>java.time.format</em></strong><br> Contém o DateTimeFormatter usado para converter os objetos de data e hora<br> em uma cadeia e também para analisar as cadeias nos objetos de dados e de tempo<br> <strong><em>java.time.temporal</em></strong><br> Contém as interfaces exigidas pelas classes de data e hora de base e também<br> abstrações (como consultas e ajustadores) para operações avançadas com datas.<br> <strong><em>java.time.zone</em></strong><br> Classes usadas para as regras de fuso horário subjacentes;<br> A maioria dos desenvolvedores não precisará deste pacote.<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">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">tabelas e coleções</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">sumário</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 documentação oficial</a></p> </div> <div class="paragraph"> <p>aqui está uma tabela de algumas propriedades interessantes<br> Estas propriedades são interessantes para obter informações<br> no sistema host da 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>Chave</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">file.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Caractere que separa os componentes de um caminho de arquivo. É '/' no UNIX e '\' no 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">Caminho usado para encontrar diretórios e arquivos JAR que contêm arquivos de classe. Os elementos do caminho de classe são separados por um caractere específico da plataforma especificado na propriedade 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">Diretório de instalação para Ambiente de Execução Java (JRE)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nome do fornecedor da 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 do fornecedor 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 da versão do JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">separador de linha</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sequência usada pelo sistema operacional para separar linhas em arquivos 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">Arquitetura do sistema operacional</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">Nome do sistema operacional</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">Versão do sistema operacional</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">Caractere separador de caminho usado em 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">Diretório de trabalho do usuário</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">diretório pessoal do usuário</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">Nome da conta do usuário</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">Fios</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">sumário</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">Expressões 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="_tabela_regex_metacaracteres">Tabela regex metacaracteres</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">Metacaractere</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">funcionalidade</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">Caractere opcional—zero ou uma instância</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">Zero ou mais do caractere 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">Um ou mais dos 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 e N instâncias do caractere 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">Um 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">Um caractere não 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">Um caractere de palavra</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Números, letras e _</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">Um caractere sem palavra</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">Um caractere de espaçamento</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">Um caractere não branco</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">Caractere de quebra de linha</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">caractere de tabulação</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">Qualquer caractere</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Não inclui a nova linha em 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">Qualquer caractere contido entre colchetes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chamada uma classe 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">Qualquer caractere não contido entre colchetes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chamado uma classe 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 um grupo de elementos do padrão</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chamado um grupo (ou 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 possibilidades alternativas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implemente o OU 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">Início da string $ Fim da string</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[com]</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_ajuda">Mostrar ajuda</a></li> <li><a href="#_definir_a_propriedade_do_sistema_da_jvm_d_system_prop">Definir a propriedade do sistema da JVM: `-D, --system-prop</a></li> <li><a href="#_definir_a_propriedade_do_projeto_para_o_script_de_build_pmypropmyvalue">Definir a propriedade do projeto para o script de build : `-Pmyprop=myvalue</a></li> <li><a href="#_especifique_o_diretório_de_início_do_gradle_o_valor_padrão_é_o_diretório_atual">Especifique o diretório de início do Gradle. O valor padrão é o diretório atual.</a></li> <li><a href="#_sobrescrever_a_propriedade_param_component_pela_linha_de_comando">Sobrescrever a propriedade 'param_component' pela linha de comando:</a></li> <li><a href="#_adicionar_uma_pasta_a_um_source_set_em_um_projeto_normal_com_o_dsl_kotlin">Adicionar uma pasta a um source-set em um projeto normal com o DSL Kotlin</a></li> <li><a href="#_adicionar_uma_pasta_a_um_source_set_em_um_projeto_android_com_o_groovy_dsl">Adicionar uma pasta a um source-set em um projeto Android com o Groovy DSL</a></li> <li><a href="#_evite_construir_e_testar_um_submódulo">Evite construir e testar um submódulo</a></li> <li><a href="#_tar_um_arquivo">Tar um arquivo</a></li> <li><a href="#_exibir_as_dependências_de_um_build">Exibir as dependências de um build</a></li> <li><a href="#_exemplo_de_uso_de_reduce_concatenação_de_uma_list_em_uma_string">Exemplo de uso de reduce: concatenação de uma list em uma string</a></li> <li><a href="#_recuperar_a_descrição_de_uma_tarefa_em_particular">Recuperar a descrição de uma tarefa em particular</a></li> <li><a href="#_para_lançar_uma_tarefa_a_partir_do_workingdir_root_então_prefixar_a_tarefa_não_um">Para lançar uma tarefa a partir do workingDir root, então prefixar a tarefa não um `:</a></li> <li><a href="#_para_reiniciar_as_tarefas_que_falharam_usar_a_opção_rerun_tasks">Para reiniciar as tarefas que falharam, usar a opção `--rerun-tasks</a></li> <li><a href="#_lançar_uma_tarefa_em_um_projeto_específico_a_partir_de_outro_diretório">Lançar uma tarefa em um projeto específico a partir de outro diretório</a></li> </ul> </div> <div class="sect1"> <h2 id="_mostrar_ajuda">Mostrar ajuda</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_a_propriedade_do_sistema_da_jvm_d_system_prop">Definir a propriedade do sistema da 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_a_propriedade_do_projeto_para_o_script_de_build_pmypropmyvalue">Definir a propriedade do projeto para o script de build : `-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="_especifique_o_diretório_de_início_do_gradle_o_valor_padrão_é_o_diretório_atual">Especifique o diretório de início do Gradle. O valor padrão é o diretório atual.</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="_sobrescrever_a_propriedade_param_component_pela_linha_de_comando">Sobrescrever a propriedade 'param_component' pela linha 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="_adicionar_uma_pasta_a_um_source_set_em_um_projeto_normal_com_o_dsl_kotlin">Adicionar uma pasta a um source-set em um projeto normal com o DSL Kotlin</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="_adicionar_uma_pasta_a_um_source_set_em_um_projeto_android_com_o_groovy_dsl">Adicionar uma pasta a um source-set em um projeto Android com o Groovy DSL</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="_evite_construir_e_testar_um_submódulo">Evite construir e testar um 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 arquivos</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_um_arquivo">Tar um arquivo</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="_exibir_as_dependências_de_um_build">Exibir as dependências de um build</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="_exemplo_de_uso_de_reduce_concatenação_de_uma_list_em_uma_string">Exemplo de uso de reduce: concatenação de uma list em uma string</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="_recuperar_a_descrição_de_uma_tarefa_em_particular">Recuperar a descrição de uma tarefa em 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_lançar_uma_tarefa_a_partir_do_workingdir_root_então_prefixar_a_tarefa_não_um">Para lançar uma tarefa a partir do workingDir root, então prefixar a tarefa não um `:</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_reiniciar_as_tarefas_que_falharam_usar_a_opção_rerun_tasks">Para reiniciar as tarefas que falharam, usar a opção `--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="_lançar_uma_tarefa_em_um_projeto_específico_a_partir_de_outro_diretório">Lançar uma tarefa em um projeto específico a partir de outro diretório</h2> <div class="sectionbody"> <div class="paragraph"> <p>A opção`-p` (ou <code>--project-dir</code>) permite especificar o caminho de acesso a um projeto Gradle e executar uma tarefa nele, mesmo que o diretório atual seja diferente.</p> </div> <div class="paragraph"> <p>Por exemplo, para lançar a tarefa`build`do projeto situado em`~/projets/mon-autre-projet`enquanto estiver em outro diretório :</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>Isso é particularmente útil para scriptar ações em vários projetos a partir de um local central.</p> </div> <div class="ulist"> <div class="title">ver também :</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">referência</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">discussão</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>as classes seladas, não são enumerações(palavra-chave:enum).<br> Vindo do Java, você poderia ser tentado de sobrecarregar sua enumeração de aportes de funcionalidades: // code Java</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>Em vez disso, você pode usar a classe sealed:</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>A vantagem desta abordagem é que agora podemos transmitir dados com o status:</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>Em geral, as classes seladas são boas se você quiser ter dados associados a um 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 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="_programação_funcional">Programação funcional</h2> <div class="sectionbody"> <div class="paragraph"> <p>Os exercícios são tirados do livro:<br> Programação funcional em Kotlin por tutoriais<br> Escrito por Massimo Carli<br> repositório: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_sintaxe">sintaxe</h3> <div class="sect3"> <h4 id="_firstprogramtest">FirstProgramTest</h4> <div class="paragraph"> <p>noções: exibição de tela, função<br> FirstProgramTest:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/FirstProgramTest.kt[source]+</p> </div> </div> <div class="sect3"> <h4 id="_concatfunctiontest">ConcatFunctionTest</h4> <div class="paragraph"> <p>noções: memória, variável, valor, objeto, extensão de função<br> ExampleUnitTest: <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt">fonte</a>+</p> </div> </div> <div class="sect3"> <h4 id="_birthdaymessagetestoutput">BirthdayMessageTestOutput</h4> <div class="paragraph"> <p>noções: conjuntos, laços<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">Introdução ao Kotlin</a><br> BirthdayMessageTestOutput:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[fonte]<br></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="_tutotiel_sobre_as_coleções_em_java">Tutotiel sobre as coleções em Java</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">Coleções</a></p> </div> <div class="paragraph"> <p>O coração das interfaces de coleção<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="coleções"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_básicos_funcionais">Básicos funcionais</h3> <div class="sect3"> <h4 id="_abordagem_declarativa_x_imperativa">Abordagem declarativa X imperativa</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="_exercício_1_1">Exercício 1.1</h4> <div class="paragraph"> <p>Implementar a função sumInRange, que soma os valores em<br> uma List<String> dentro de um intervalo dado. A assinatura é:</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>Experimente e verifique sua resposta com ahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/DeclarativeTests.kt[solution, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_funções_de_ordem_superior">Funções de ordem 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="_exercício_1_2">Exercício 1.2</h4> <div class="paragraph"> <p>Implementar chrono, que aceita uma função do tipo`() →`<br> Unidade na entrada e devolve o tempo gasto para executá-lo. A assinatura é :<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>Experimente-o e verifique sua resposta com ahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solução, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_composição">Composição</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="_funções_puras_e_testabilidade">Funções puras e testabilidade</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="_tratamento_de_exceções">Tratamento de exceções</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="_pontos_chave">Pontos-chave</h3> <div class="ulist"> <ul> <li> <p>Enquanto a programação orientada a objetos significa programar com objetos,</p> </li> </ul> </div> <div class="paragraph"> <p>programação funcional significa programar com funções. Você decompõe um problema em vários subproblemas, que você modela com as funções</p> </div> <div class="ulist"> <ul> <li> <p>As funções de ordem superior aceitam outras funções como entrada ou retornam outras</p> </li> </ul> </div> <div class="paragraph"> <p>funcionam como valores de retorno. A teoria das categorias é a teoria da composição, e você a usa para entender como compor suas funções em um programa de trabalho. O valor de saída de uma função pura depende apenas dos seus parâmetros de entrada, e ela não tem efeitos colaterais</p> </div> <div class="ulist"> <ul> <li> <p>Um efeito colateral é algo que uma função faz no mundo exterior. Este</p> </li> </ul> </div> <div class="paragraph"> <p>pode ser um log na saída padrão ou a modificação do valor de uma variável global. A programação funcional funciona para as funções puras, mas ela fornece também os ferramentas para transformar funções impuras em funções puras. Você pode tornar uma função impura pura movendo os efeitos para torná-los parte do valor de retorno.</p> </div> <div class="ulist"> <ul> <li> <p>Programação funcional é uma questão de composição.</p> </li> </ul> </div> <div class="paragraph"> <p>Gerenciamento de erros é um caso típico de efeitos colaterais, e Kotlin lhe fornece as ferramentas para gerenciá-los de forma funcional</p> </div> </div> <div class="sect2"> <h3 id="_aprofundar_java8_lambdas_expressões_e_interface_funcionais">Aprofundar java8: lambdas expressões e interface funcionais</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="_teoria_das_categorias">Teoria das categorias</h3> <div class="paragraph"> <p>A teoria matemática das categorias:</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_das_funções">Fundamentos das funções</h3> <div class="sect3"> <h4 id="_exercício_2_1">Exercício 2.1</h4> <div class="paragraph"> <p>Pode escrever um exemplo de função mapeando valores distintos?<br> cujo domínio assume valores não distintos no intervalo, como f(b) e f(c) na figura abaixo ?<br></p> </div> <div class="paragraph"> <p>Experimente, depois verifique o projeto do desafio para uma solução para ver como você fez.<br> Você encontrará conselhos e uma explicação seguindo o link para a <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">solução</a>.<br></p> </div> </div> <div class="sect3"> <h4 id="_exercício_2_2">Exercício 2.2</h4> <div class="paragraph"> <p>Você pode escrever a função inversa de duas vezes ?<br> Quais são o domínio e a imagem da função inversa?<br> Confira o projeto do desafio e o Apêndice B para a solução.</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>Experimente-o e verifique sua resposta com ahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solução, 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="_ferramentas">Ferramentas</h2> <div class="sectionbody"> <div class="dlist"> <div class="title"><strong>Ilustrações</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>Ilustrações de código aberto para todas as ideias que você pode imaginar e criar.</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">absurd.design</a></dt> <dd> <p>Ilustrações absurdas que fazem sentido</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>Ilustrações gratuitas magníficas. Atualizações semanais.</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>Ícones, ilustrações, fotos, música e ferramentas de design.</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">rubor.design</a></dt> <dd> <p>Ícones, ilustrações, fotos, música e ferramentas de design</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>Misture e combine ilustrações de pessoas com uma biblioteca de design.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>cores</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>O gerador de esquemas de cores ultra-rápido!</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Tendências</strong></div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">pinterest</a></dt> <dd> <p>Descoberta visual de ideias: imagens, vídeos, coleções temáticas.</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">Drible</a></dt> <dd> <p>Plataforma para designers que compartilham suas criações e interagem.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI e Design Systems</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">Google Material Design</a></dt> <dd> <p>Sistema de design do Google para interfaces de usuário unificadas e adaptáveis.</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Diretrizes de Interface Humana da Apple</a></dt> <dd> <p>Recomendações da Apple para projetar aplicações iOS e macOS intuitivas.</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>Plataforma de design e de colaboração para criar protótipos e sistemas de design.</p> </dd> </dl> </div> <div class="paragraph"> <p><a href="https://www.frontify.com/" class="bare">https://www.frontify.com/</a>[</think></p> </div> <div class="dlist"> <dl> <dt class="hdlist1">Frontify]</dt> <dd> <p>Plataforma de gestão de marca e de sistemas de design para garantir a consistência.</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">Repositório de Sistemas de Design</a></dt> <dd> <p>Coleção de recursos e exemplos de design systems para inspiração.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Desenvolvimento Frontend</strong></div> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a></dt> <dd> <p>Folha de dicas HTML</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com">fontawesome.com</a></dt> <dd> <p>biblioteca de ícones</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a></dt> <dd> <p>Ícones nativos em HTML</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>Essencial para CSS, com artigos, tutoriais e dicas frontend modernas.</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">Frontend Mentor</a></dt> <dd> <p>Desafios de código frontend baseados em projetos reais para melhorar suas habilidades.</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>Comunidade de desenvolvedores para compartilhar artigos, tutoriais e projetos.</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">CodePen</a></dt> <dd> <p>Editor de código online e comunidade para compartilhar trechos de código e demonstrações.</p> </dd> </dl> </div> <div class="paragraph"> <p><strong>Desenvolvimento Frontend auxiliado por IA</strong></p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0 converte descrições em linguagem natural para código e interface do usuário.</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">Uizard</a></dt> <dd> <p>Uizard concentra-se na transformação de maquetas (imagens, esboços) em código HTML, CSS e React.</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI permite que você descreva a interface que deseja em linguagem natural, e a IA gera designs Figma editáveis.</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ é uma plataforma de desenvolvimento front-end low-code que utiliza a IA para ajudá-lo a construir e implantar sites web visualmente.</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/">documento oficial do microk8s</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_instalação_do_pacote_microk8s">Instalação do pacote 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, utilidade para os testes, permite saber onde estamos, e a causa da falha.<br> Ainda não implementado, permite lançar a exceção correta.<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="_links_interserver_net">Links: <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="_sources">Sources:</h4> <div class="paragraph"> <p>*https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[xenovação] *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="_mudar_o_repositório_remoto_no_git">mudar o repositório remoto no git</h4> <div class="paragraph"> <p>mostrar a url do repositório remoto atual:</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 uma pasta de destino adicionar o argumento -P e depois dar o caminho ----</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="_links_etcher">Links: <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="_links_askubuntu">Links: <a href="https://askubuntu.com/questions/86849/how-to-unzip-a-zip-file-from-the-terminal">askubuntu</a></h4> <div class="paragraph"> <p>Se quiser extrair para uma pasta de destino específica, você pode utilizar: <code>` $ unzip arquivo.zip -d pasta_destino </code>` Se os diretórios de origem e de destino forem idênticos, você pode simplesmente fazer: <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="_links_stackexchange">Links: <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="_apagar_uma_branch_no_github">Apagar uma branch no github</h4> </div> <div class="sect3"> <h4 id="_link_gist">Link: <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 que asciidoc ou markdown? Aqui, estou me direcionando para asciidoc, pois já tenho alguns tickets escritos em asciidoc.<br></div> <p>Asciidoc é uma linguagem de marcação que permite produzir conteúdo, trazendo uma formatação que mantém o texto legível para um ser humano.<br> É uma maneira de padronizar os tratamentos de texto para conteúdos simples sem software adicional.</p> </div> <div class="ulist"> <div class="title">Links :</div> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/">@jmdoudoux no 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 um pacote Debian a partir de um arquivo .deb na linha de comando.<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>veja aqui para ahttps://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[referência]<br></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>Em um projeto de aplicativo conduzido pelo gerenciador de compilação Gradle<br> é mais agradável ter visibilidade sobre todos os arquivos<br> participante do desenvolvimento da aplicação,<br> como pastas de recursos que não são<br> nos caminhos por convenção.<br> Por exemplo eu quero que a pasta src/jbake,<br> seja visível como ‘resource folder’,<br> é possível fazer isso entrando na configuração do projeto,<br> nos wizards da IDE No entanto esta opção não é salva no próximo recarregamento<br> do projeto Gradle na IDE. Para aplicar essa configuração permanentemente.<br> a solução é sobrescrever a configuração dos caminhos de fontes<br> no arquivo de configuração build.gradle tal como nas linhas 18, 19, 20 e 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>O assunto do ticket é a configuração de um script de build Gradle.<br> Quero poder usar um script Groovy sem fazer referência<br> ao projeto Gradle no qual eu o anexei.<br> Quero ter a possibilidade de executar este script Groovy fora do Gradle<br> sem que as anotações ivy de recuperação de dependência externa<br> não vêm causar problemas de desempenho ou de compilação<br> do script de build do Gradle.<br> Para ilustrar a configuração, eu me baseio em dois scripts:<br> um script de build Gradle e um script Groovy.<br> O script Groovy contém no início na linha 2,<br> uma instrução para puxar uma dependência externa<br> usando o gerenciador de dependências 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>No arquivo build.gradle, agora vamos ver como harmonizar<br> os dois gerenciadores de dependências, ivy e Gradle. O acordo entre os dois se faz nas linhas:<br> 26, 30, 37, 38 et 39<br> Assim posso executar meu script Groovy manualmente,<br> e a compilação do Gradle não é prejudicada pelo <code>@Grab</code>.<br> As dependências do script Groovy não devem ser fornecidas no Gradle.<br> Por outro lado, não consigo executar o script Groovy a partir do 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>referência do ticket sobrehttps://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="_o_ppmc">O PPMC</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">wiki PPMC ou Mínimo Múltiplo Comum</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>mdc(96, 28) = 4 mmc(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>Estou procurando arquivos por critérios de nome: a lista dos arquivos que têm a extensão .h e .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>a lista dos arquivos que têm como extensão .h e .cpp<br> o resultado é salvo no arquivo 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>Estou procurando a lista dos arquivos cuja extensão é .chm<br> E eu destrui 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="_analisar_e_recolher_as_necessidades">Analisar e recolher as necessidades</h3> </div> <div class="sect2"> <h3 id="_definir_a_gestão_de_projetos">Definir a gestão de projetos</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_o_projeto">Contextualizar o projeto</h3> </div> <div class="sect2"> <h3 id="_analisar_e_recolher_necessidades">Analisar e recolher necessidades</h3> <div class="sect3"> <h4 id="_formular_os_objetivos_e_entregáveis">Formular os objetivos e entregáveis</h4> </div> </div> <div class="sect2"> <h3 id="_decifrar_uma_grade_de_leitura">Decifrar uma grade de leitura</h3> </div> <div class="sect1"> <h2 id="_defina_o_projeto_com_a_sua_equipe">Defina o projeto com a sua equipe</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_os_especialistas_para_encontrar_a_solução">Consultar os especialistas para encontrar a solução</h3> </div> <div class="sect2"> <h3 id="_escolher_uma_metodologia_de_gestão_de_projeto">Escolher uma metodologia de gestão de projeto</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>Não tenho vontade de instalarhttps://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a> enquanto tudo está presente na linha de comando.<br> Para isso devemos lançar o terminal e conectar como o usuário postgres.<br> O usuário postgres é o único a ter por padrão o direito de executar a aplicação psql, que é o cliente de linha de comando. (<a href="https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande">CLI</a>)postgresql,<br> para poder falar com o banco de dados na linha de comando a partir do terminal<br> Para se conectar, abrir o terminal e digitar isto:<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 se conectar e chegar diretamente ao prompt de comando do postgresql, digite isso:</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 os bancos de dados de uma instância de postgresql, aqui está o 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 das bases de dados Nome | Proprietário | Codificação | Colação | Tipo caract. | Direitos de acesso</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 linhas)</p> </div> <div class="paragraph"> <p>digite q para sair da exibição dos resultados<br> <br> para listar os esquemas de uma instância 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 linhas)</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 (6 linhas)</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>Meu reprodutor de vídeo na minha TV tem seu jeito de passar<br> de um ficheiro para o outro em leitura contínua<br> e seu modo de reprodução é de passar de 1…​..mp4 para 10…​.mp4,<br> e não de 1…​mp4 a 2…​.mp4.<br> O problema é que há quase 900 ficheiros e pastas.<br> Bingo um super caso de uso do Groovy para manipular<br> de arquivos, renomeação, pesquisa de padrão no nome do arquivo<br> ou pasta<br> Aqui o objetivo é mudar os nomes que começam por<br> um número e cujo segundo caractere do nome<br> não é um dígito, acrescentarei um 0 no início deste nome<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>O objetivo deste script é procurar arquivos,<br> a partir de um diretório-pai; recuperar a seleção<br> em uma lista. Finalmente copiar esta lista de arquivos<br> em um diretório de destino isso em 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>Aqui vou me interessar pelo carregamento de uma propriedade dentro de um build proyectohttps://docs.gradle.org/current/userguide/userguide.html[gradle]<br> sem que ela esteja disponível no código.<br> A propriedade será definida no arquivo gradle.properties do diretório ~/.gradle/gradle.properties<br> ~ é um atalho da variável simbólica HOME_PATH que representa a raiz da sessão do usuário: ohttps://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel[diretório pessoal].<br> Da mesma forma em um projeto de buildhttps://maven.apache.org/guides/index.html[maven], com ~/.m2/settings.xml O objetivo deste script é excluir os arquivos que corresponderiam aos padrões mencionados<br> na variável strCriteria. Para isso vou usar oshttps://fr.wikipedia.org/wiki/Fermeture_(informatique)[fechos]: cada, findAll, coletar<br> assim como a classe StringTokenizer que vai dividir em pedaços minha cadeia de critérios<br> para obter uma lista de cadeias de caracteres Se um dos arquivos da minha pasta a ser limpa contém um dos padrões em seu nome<br> então será um candidato à destruição por ser adicionado à lista de resultados.<br> E na última linha um pequeno exemplo dehttps://en.wikipedia.org/wiki/Elvis_operator[Operador Elvis]<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>Este é um trecho de código funcional em Groovy,<br> para mudar todas as ocorrências duma sequência de caracteres numa String<br> e carregar um arquivo .properties em um objeto properties.<br> Executar um comando em uma 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>Aqui está um trecho de código funcional em Groovy, que gera um arquivo de texto,<br> com os 256 primeiros caracteres legíveis da tabela 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>eu nomei o arquivo spe_char.groovy,<br> do diretório onde está o arquivo<br> abrir um terminal e copiar e colar para executar o 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>