https://cheroliv.com/ JBake Bootstrap Template en-gb Wed, 12 Aug 2026 15:02:47 +0000 Wed, 12 Aug 2026 15:02:47 +0000 https://cheroliv.com/en/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="#_the_gap_in_the_video_pipeline">The Gap in the Video Pipeline</a></li> <li><a href="#_hyperframes_the_engine">HyperFrames: The Engine</a></li> <li><a href="#_the_plugin_architecture">The Plugin Architecture</a> <ul class="sectlevel2"> <li><a href="#_the_four_step_pipeline">The Four-Step Pipeline</a></li> <li><a href="#_the_asciidoc_dsl">The AsciiDoc DSL</a></li> <li><a href="#_the_node_js_bridge">The Node.js Bridge</a></li> </ul> </li> <li><a href="#_two_video_plugins_two_usages">Two Video Plugins, Two Usages</a></li> <li><a href="#_the_6_epics_of_the_roadmap">The 6 EPICs of the Roadmap</a></li> <li><a href="#_why_it_works">Why It Works</a></li> <li><a href="#_conclusion_the_missing_link">Conclusion: The Missing Link</a></li> <li><a href="#_references">References</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time : 8 minutes</div> <p>Two weeks ago, I launched`capsule-gradle`— a plugin that transforms a reveal.js deck into a WebM video capsule with TTS. Today, I am adding a new plugin: <code>hyperframes-gradle</code>. It does something that capsule-gradle does not: transform AsciiDoc <strong>directly</strong> into MP4 video, without going through reveal.js.</p> </div> <div class="paragraph"> <p>Here is why this plugin exists, how it interfaces with the existing setup, and what the HyperFrames engine by HeyGen brings to the content production pipeline.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_gap_in_the_video_pipeline">The Gap in the Video Pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>My documentation pipeline produces two types of videos:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Revision capsule</strong> (capsule-gradle) — a reveal.js deck captured in WebM with</p> </li> </ol> </div> <div class="paragraph"> <p>TTS narration. Perfect for reviewing a module.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Animation slides</strong> (slider-gradle) — an interactive HTML reveal.js deck for</p> </li> </ol> </div> <div class="paragraph"> <p>the in-person trainer.</p> </div> <div class="paragraph"> <p>But a third format is missing: the <strong>standalone video</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">Use case</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Current solution</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Missing</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Trainer slides</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">Revision capsule</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>Teaser video</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>None</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>Animated technical demo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>None</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-to-video</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>None</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The first use case is critical: how to automatically generate a 60-second video presenting a project or a module, with GSAP animations, TTS narration, and background music — all from the same AsciiDoc file as the slides?</p> </div> <div class="paragraph"> <p>Capsule-gradle cannot answer this: it <strong>already</strong> requires a reveal.js deck. slider-gradle does produce this deck, but it is not designed for video rendering. A <strong>direct</strong> pipeline was needed: AsciiDoc → video.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_the_engine">HyperFrames: The Engine</h2> <div class="sectionbody"> <div class="paragraph"> <p>I discoveredhttps://github.com/heygen-com/hyperframes[HyperFrames] il y a a few days ago. It is an open-source framework (Apache 2.0) created by HeyGen, the AI video unicorn. 22,700 stars on GitHub. The pitch can be summed up in one sentence:</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>Write HTML. Render video. Built for agents.</strong></p> </div> </blockquote> </div> <div class="paragraph"> <p>The principle: you write HTML with`data-*`attributes, you reference a GSAP animation (or CSS, Lottie, Three.js…), and the engine renders it all into MP4 via Puppeteer (headless Chrome) + FFmpeg. Deterministic result: same input, same frames, same video.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><div id="stage" data-composition-id="intro" data-start="0" data-width="1920" data-height="1080"> <video class="clip" data-start="0" data-duration="6" data-track-index="0" src="background.mp4" muted playsinline></video> <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1"> Formation Docker & Kubernetes </h1> <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.3" src="music.wav"></audio> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.__timelines = window.__timelines || {}; window.__timelines.intro = tl; </script> </div></code></pre> </div> </div> <div class="paragraph"> <p>What makes HyperFrames different from Remotion? No React, no bundler, no JSX. Raw HTML that AI agents know how to write natively. It is tailored <strong>exactly</strong> for my pipeline: planner-gradle with deepseek can generate this HTML from an SPG/SPD plan, and a Gradle plugin can convert it to MP4.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_plugin_architecture">The Plugin Architecture</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle follows the same pattern as all my plugins: the <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">« Independent Plugin + Consumer Root » pattern</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="_the_four_step_pipeline">The Four-Step Pipeline</h3> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-hyperframes.svg" alt="pipeline hyperframes" width="1005" height="100"> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>AsciidoctorJ</strong> parses the source AsciiDoc and extracts the custom blocks</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> generates the HyperFrames HTML with the</p> </li> </ol> </div> <div class="paragraph"> <p>`data-*`corresponding attributes.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RenderHyperframesTask</strong> calls the HyperFrames CLI 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>The MP4 is deployed into`output/`with a`metadata.json`for orchestration.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_the_asciidoc_dsl">The AsciiDoc DSL</h3> <div class="paragraph"> <p>The true added value of the plugin is the AsciiDoc DSL. The user never writes HTML. They annotate their existing AsciiDoc document:</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>The docinfo attributes (<code>:hyperframes-width:</code>) configure the dimensions. Custom blocks define the compositions and tracks. The `[hyperframes-animation]`block contains the raw GSAP code — which the AI agent can generate from a natural language description.</p> </div> </div> <div class="sect2"> <h3 id="_the_node_js_bridge">The Node.js Bridge</h3> <div class="paragraph"> <p>The only technical point of friction: HyperFrames is in Node.js/TypeScript, and my plugins are in Kotlin/JVM. The solution is a`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 code coupling JVM ↔ Node.js. The contract is via command line and files on disk. This is the same pattern as`plantuml-gradle` (which calls the PlantUML CLI) or`slider-gradle`(which calls AsciidoctorJ). Nothing new under the sun — just applied to a more recent tool.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_two_video_plugins_two_usages">Two Video Plugins, Two Usages</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.762%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">hyperframes-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">reveal.js deck (existing HTML)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">AsciiDoc → HyperFrames HTML</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Use case</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Revision capsule</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Standalone explanatory video</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nature</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides → video</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Document → video</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rendering</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">Animation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Native reveal.js transitions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GSAP/CSS data-attributes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stack</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% JVM (Kotlin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JVM + external Node.js CLI</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>They do not replace each other. They complement each other. The complete value chain:</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ slider-gradle ──→ reveal.js deck ──→ capsule-gradle ──→ WebM (revision capsule)</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ hyperframes-gradle ──→ MP4 (standalone video)</p> </div> <div class="paragraph"> <p>The user writes a single AsciiDoc file. slider-gradle produces the slides. capsule-gradle produces the revision capsule. hyperframes-gradle produces the teaser video and technical demos.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_6_epics_of_the_roadmap">The 6 EPICs of the Roadmap</h2> <div class="sectionbody"> <div class="paragraph"> <p>The plugin is structured into 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">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Priority</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 governance + architecture scoping</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ COMPLETED</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">Gradle plugin stub + AsciidoctorJ integration</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">HyperFrames CLI Bridge (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">Custom AsciiDoc DSL (blocks, docinfo, templates)</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">runner-gradle integration (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">Ready-to-use templates (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 + Maven Central / Gradle Portal publication</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Session 000 (bootstrap) is already completed. Session 001 will tackle HF-1: the Gradle plugin stub and AsciidoctorJ integration.</p> </div> </div> </div> <div class="sect1"> <h2 id="_why_it_works">Why It Works</h2> <div class="sectionbody"> <div class="paragraph"> <p>Three reasons:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HyperFrames is "built for agents"</strong>. My pipeline relies on AI agents</p> </li> </ol> </div> <div class="paragraph"> <p>(planner-gradle + deepseek) that generate content. HyperFrames accepts raw HTML — the format that LLMs master best. No React, no JSX, no learning curve for the agent.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>The AsciiDoc DSL is natural</strong>. My entire ecosystem speaks AsciiDoc.</p> </li> </ol> </div> <div class="paragraph"> <p>slider-gradle, codex-gradle, training-gradle — they all consume`.adoc`. Adding custom blocks`[hyperframes-composition]`is a logical extension, not a break.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>The Node.js bridge is a proven pattern</strong>. ProcessBuilder outside the JVM,</p> </li> </ol> </div> <div class="paragraph"> <p>that is what I already do for PlantUML, Graphviz, Piper. Adding HyperFrames changes nothing in the architecture — it is just one more external tool, driven from 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>The true strength of the pattern is that there are <strong>no</strong> npm dependencies in the Gradle build. The plugin does not import Node.js code. It executes a shell command. If HyperFrames evolves or breaks, the plugin is not coupled — simply update the command.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_missing_link">Conclusion: The Missing Link</h2> <div class="sectionbody"> <div class="paragraph"> <p>With hyperframes-gradle, my video pipeline is complete. I have:</p> </div> <div class="ulist"> <ul> <li> <p>The <strong>interactive slides</strong> (slider-gradle)</p> </li> <li> <p>The <strong>revision capsules</strong> (capsule-gradle)</p> </li> <li> <p>The <strong>standalone videos</strong> (hyperframes-gradle)</p> </li> </ul> </div> <div class="paragraph"> <p>Three formats. A single source file: AsciiDoc.</p> </div> <div class="paragraph"> <p>The next goal is HF-1: get the plugin to compile and generate a first HyperFrames HTML from an annotated AsciiDoc document. Session 001 is already scoped.</p> </div> <div class="paragraph"> <p>hyperframes-gradle exists. The governance is in place. The backlog is written. The architecture is documented. The plugin is born.</p> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">Article 0124 — The Independent Plugin + Consumer Root Architecture</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 — Documentation</a></p> </li> <li> <p><code>foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc</code>— Detailed Architecture</p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_understanding_the_stack_who_does_what">Understanding the Stack: Who Does What?</a></li> <li><a href="#_introduction_why_an_audit">Introduction: Why an Audit?</a></li> <li><a href="#_the_opencode_database_a_gold_mine">The OpenCode Database: A Gold Mine</a> <ul class="sectlevel2"> <li><a href="#_the_schema">The Schema</a></li> <li><a href="#_the_extraction_code">The Extraction Code</a></li> </ul> </li> <li><a href="#_the_results_73_days_of_consumption">The Results: 73 Days of Consumption</a> <ul class="sectlevel2"> <li><a href="#_global_view">Global View</a></li> <li><a href="#_breakdown_by_model_and_provider">Breakdown by Model and Provider</a></li> <li><a href="#_intra_session_models_what_the_session_table_doesnt_see">Intra-Session Models: What the Session Table Doesn’t See</a></li> </ul> </li> <li><a href="#_pricing_comparison_western_providers">Pricing Comparison — Western Providers</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="#_huggingface_inference_providers">HuggingFace Inference Providers</a></li> <li><a href="#_groq">Groq</a></li> </ul> </li> <li><a href="#_pricing_comparison_chinese_providers">Pricing Comparison — Chinese Providers</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="#_summary_table_all_providers">Summary Table — All Providers</a></li> <li><a href="#_the_hidden_cost_prompt_engineering_and_iterations">The Hidden Cost: Prompt Engineering and Iterations</a></li> <li><a href="#_combining_ollama_cloud_pro_subscriptions_the_docker_method">Combining Ollama Cloud Pro Subscriptions: The Docker Method</a></li> <li><a href="#_what_the_audit_doesnt_measure">What the Audit Doesn’t Measure</a></li> <li><a href="#_conclusion_the_verdict_of_the_numbers">Conclusion: The Verdict of the Numbers</a></li> <li><a href="#_references">References</a> <ul class="sectlevel2"> <li><a href="#_pricing_sources">Pricing Sources</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 22 minutes</div> <p>I’m often asked how much my AI consumption costs. I answer "20 bucks a month" and people look at me with wide eyes. So today, I’m opening the black box for you. This article is the full audit of my 73 days of vibe coding: the methodology for extracting data from the OpenCode SQLite database, the SQL code to query the tables, and the exhaustive comparison with <strong>all</strong> market providers — Western and Chinese. The result is so asymmetrical that I had to check my calculations three times.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_understanding_the_stack_who_does_what">Understanding the Stack: Who Does What?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before diving into the numbers, let’s clarify the architecture. There are three distinct actors in my setup, and it’s important not to confuse them:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/stack-architecture.svg" alt="stack architecture" width="1474" height="431"> </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 is NOT a model provider.</strong>It is an open-source CLI (<a href="https://github.com/anomalyco/opencode">github.com/anomalyco/opencode</a>) that orchestrates AI agents. It doesn’t sell subscriptions; it doesn’t provide inference. It’s the equivalent of`git`for versioning: a tool, not a service. <strong>Ollama Cloud is the inference provider.</strong>My local Ollama installation acts as a <strong>client</strong> — it authenticates with Ollama servers via a unique SSH key (Device Key) and delegates the execution of models tagged`:cloud`to them. The Pro subscription (€20/month) unlocks higher quotas and allows combining multiple accounts on the same machine via Docker.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_introduction_why_an_audit">Introduction: Why an Audit?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Two months ago, I was using models for free on my local Ollama installation. Then I subscribed to a first Ollama Cloud Pro subscription at €20/month, which allows me to use cloud models (those with the`:cloud`tag) via the`ollama-cloud`provider. A second subscription followed a month later, on a separate Docker instance with its own account and its own SSH key — the combining method described in <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">my article on combining subscriptions</a>.</p> </div> <div class="paragraph"> <p>The question that haunted me: <strong>are these €20 per month justified?</strong> Not by guesswork. With figures.</p> </div> <div class="paragraph"> <p>To answer, I needed precise data. Not estimates. Not averages. My <strong>actual</strong> consumption, token by token, model by model, session by session.</p> </div> <div class="paragraph"> <p>And OpenCode — the CLI — stores all of that in a SQLite database.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_opencode_database_a_gold_mine">The OpenCode Database: A Gold Mine</h2> <div class="sectionbody"> <div class="paragraph"> <p>OpenCode persists the entire history of its sessions in a SQLite file located at`~/.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="_the_schema">The Schema</h3> <div class="paragraph"> <p>The database contains about twenty tables, but three of them are crucial for our audit:</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>The`session`table is perfect for a global audit: each session has its aggregated token count, its used model, and its cost. The`model`field is raw JSON:</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>The`cost`field in the OpenCode database only reflects <strong>external API fees</strong> paid on consumption via API key (Google Gemini, OpenAI, etc.). Calls via Ollama — whether local or via Ollama Cloud Pro — are marked`cost=0`because the cost is a flat fee (subscription), not per-token. The real cost of these calls is the monthly subscription.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_the_extraction_code">The Extraction Code</h3> <div class="paragraph"> <p>No need to install anything. Node.js 22+ includes an experimental SQLite module (<code>node:sqlite</code>) that works perfectly. Here is the script that gave me everything:</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>The`--experimental-sqlite`flag is required on Node.js 22.x. On Node.js 24+, the module is stable and no longer requires the flag.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_results_73_days_of_consumption">The Results: 73 Days of Consumption</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_global_view">Global View</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">Metric</th> <th class="tableblock halign-left valign-top">Value</th> <th class="tableblock halign-left valign-top">Context</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>OpenCode Sessions</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 sessions/day on average</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Input Tokens</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.62 billion</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Including 94.5M in cache hits</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Output Tokens</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21 million</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Input/output ratio ~125:1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Reasoning Tokens</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">Negligible — almost no thinking</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>External API Cost</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">Non-subscription fees (Gemini + free tiers)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>This figure of \$0.22 is crucial: it represents everything I paid <strong>on top of</strong> my Ollama Cloud Pro subscription. Which is to say, almost nothing. The subscription covers the essentials.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/repartition-mensuelle.svg" alt="repartition mensuelle" width="638" height="207"> </div> </div> <div class="paragraph"> <p>The takeoff between March and April is spectacular: ×35 in one month. This is the transition from "test" usage to "production" usage — when I started running OpenCode agents continuously for my Gradle plugins.</p> </div> </div> <div class="sect2"> <h3 id="_breakdown_by_model_and_provider">Breakdown by Model and Provider</h3> <div class="paragraph"> <p>Since the`model`field of the`session`table is JSON,`json_extract()`allows for a clean breakdown:</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">Model × Provider</th> <th class="tableblock halign-left valign-top">Sessions</th> <th class="tableblock halign-left valign-top">Input</th> <th class="tableblock halign-left valign-top">Output</th> <th class="tableblock halign-left valign-top">Cost</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>Three different providers for exactly the same DeepSeek V4 Pro model: * <code>ollama-cloud</code>→ via <strong>paid Pro subscription</strong> (cloud managed by Ollama) * <code>ollama-b</code>→ <strong>second Pro subscription</strong>, isolated in a distinct Docker container * <code>ollama</code>→ native local instance, <strong>free</strong> (runs directly on my machine) The sum of the three gives 936M input, 8.4M output — this is my total DeepSeek V4 Pro consumption, across all providers. Only`ollama-cloud`(220M input) costs a subscription. The remaining 716M are free (local or combined subscriptions).</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_intra_session_models_what_the_session_table_doesnt_see">Intra-Session Models: What the Session Table Doesn’t See</h3> <div class="paragraph"> <p>The`session`table only captures the <strong>primary</strong> model of the session. But during a single session, an OpenCode agent can switch between several models. The`message`table reveals it:</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>I no longer use Qwen, GLM, Kimi, or other models. They appear in the history because I tested quite a few things in April. Since mid-May, I’ve been locked onto DeepSeek V4 Pro — it’s the only one that handles the load on long context with agent governance (see <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">my Kimi/GLM/DeepSeek comparison</a>). The 32% of deepseek messages in the history are misleading: today it’s 100%.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pricing_comparison_western_providers">Pricing Comparison — Western Providers</h2> <div class="sectionbody"> <div class="paragraph"> <p>The awkward question: how much would this same consumption cost with traditional providers?</p> </div> <div class="paragraph"> <p>My calculation base for the comparison:<strong>220M input tokens + 1.9M output tokens</strong>— <strong>only</strong> the volume passed through`ollama-cloud`(the only one corresponding to my paid subscription). The remaining 716M are free (local Ollama and Docker instance 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">Provider</th> <th class="tableblock halign-left valign-top">Model</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>My setup</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">Model</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</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">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"><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>Even Haiku 4.5, the most "economical" Claude model, costs 11× my subscription. And it knows nothing of my codebase, doesn’t generate in my style, and hallucinates on Gradle Kotlin DSL APIs.</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">Model</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</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">Model</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</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 at €69 is the only "close" competitor in pure price — but it’s a light dense model, not a 1.6T MoE like DeepSeek V4 Pro. The quality of generated code is not comparable.</p> </div> </div> <div class="sect2"> <h3 id="_huggingface_inference_providers">HuggingFace Inference Providers</h3> <div class="paragraph"> <p>HuggingFace doesn’t perform inference itself — it aggregates third-party <strong>providers</strong> (Novita, Together, DeepInfra, Cerebras, SambaNova, Fireworks, Groq…) via a unified API. You choose the cheapest or fastest provider. Here are the rates found in May 2026 for DeepSeek V4 Pro:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">HF Provider</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Novita (cheapest)</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">Together</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">Fireworks</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non-public pricing</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Even the cheapest provider on HuggingFace (Novita) charges 19× the price of my subscription. And unlike Ollama Cloud, HuggingFace charges <strong>additional</strong> platform fees if you don’t have an HF PRO subscription (\$9/month).</p> </div> </div> <div class="sect2"> <h3 id="_groq">Groq</h3> <div class="paragraph"> <p>Groq has <strong>none</strong> of the models I use — their catalog is limited to GPT-OSS, Llama, and Qwen 32B. Impossible to compare.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pricing_comparison_chinese_providers">Pricing Comparison — Chinese Providers</h2> <div class="sectionbody"> <div class="paragraph"> <p>The real test is the Chinese market. If DeepSeek is a Chinese model, its native API should be cheaper, right?</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">Period</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">-75% Promo (ends May 31)</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">Full price (starting June)</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>Even with DeepSeek’s aggressive promo (-75% extended), the direct API costs<strong>5×</strong>more. At the normal rate,<strong>20×</strong>. And that’s <strong>only</strong> DeepSeek — no access to other models.</p> </div> </div> <div class="sect2"> <h3 id="_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</h3> <div class="paragraph"> <p>Kimi only offers its own models. No DeepSeek.</p> </div> </div> <div class="sect2"> <h3 id="_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</h3> <div class="paragraph"> <p>The only provider aggregating all Chinese models — but via resale with a margin. Prices are loaded dynamically in JavaScript, making scraping impossible.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_summary_table_all_providers">Summary Table — All 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">Provider</th> <th class="tableblock halign-left valign-top">Model</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Cost/month</th> <th class="tableblock halign-left valign-top">× my subscription</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~€20</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3,5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (promo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,44</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$98</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$374</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (normal)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$390</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">20×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">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="imageblock"> <div class="content"> <img src="./images/cout-comparaison-barres.svg" alt="cout comparaison barres" width="655" height="279"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_hidden_cost_prompt_engineering_and_iterations">The Hidden Cost: Prompt Engineering and Iterations</h2> <div class="sectionbody"> <div class="paragraph"> <p>Token cost is only part of the equation. The real cost is developer time.</p> </div> <div class="paragraph"> <p>With OpenCode + Ollama Cloud Pro + my agent governance (EAGER/LAZY/Hot/Warm/Cold, described in <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">the article on governance</a>), I get:</p> </div> <div class="ulist"> <ul> <li> <p><strong>0 repetitive prompt engineering</strong>: context is injected automatically</p> </li> <li> <p><strong>90%+ first-shot correct</strong>: code compiles the first time</p> </li> <li> <p><strong>Zero deepseek hallucinations over 8 consecutive sessions</strong>(documented in <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">the Kimi/GLM/DeepSeek comparison</a>)</p> </li> </ul> </div> <div class="paragraph"> <p>With Claude or GPT <strong>without</strong> fine-tuning or governance:</p> </div> <div class="ulist"> <ul> <li> <p>2-3 iterations per task on average</p> </li> <li> <p>Systematic prompt engineering</p> </li> <li> <p>Hallucinations on Kotlin/Gradle APIs as soon as context exceeds 30K tokens</p> </li> </ul> </div> <div class="paragraph"> <p>The "effective" monthly cost — tokens × iterations × correction time — is 27× to 54× that of my solution, as I demonstrated in <a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">the article on the efficiency ratio</a>.</p> </div> <div class="paragraph"> <p><em><em>_ It’s not just a story of price per token. A Claude Opus at 57× the price requiring 3× more iterations is an effective cost ~170× higher. To put it bluntly: paying an intern a McKinsey partner’s salary. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_combining_ollama_cloud_pro_subscriptions_the_docker_method">Combining Ollama Cloud Pro Subscriptions: The Docker Method</h2> <div class="sectionbody"> <div class="paragraph"> <p>If a single subscription isn’t enough, you combine them. The principle is to isolate each subscription in its own Ollama installation, with its own SSH authentication key. Docker makes this trivial.</p> </div> <div class="paragraph"> <p>The complete method is detailed in <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">the Docker combining article</a>, here is the principle:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-dual-abonnement.svg" alt="architecture dual abonnement" width="581" height="481"> </div> </div> <div class="paragraph"> <p>The pattern is simple:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Create a volume`~/ollama-b-data`</p> </li> <li> <p>Launch a Docker container`ollama/ollama:0.20.2`mapped to`11435:11434`</p> </li> <li> <p>Retrieve the container’s SSH key → register it on ollama.com</p> </li> <li> <p>Do`ollama signin`with a second email</p> </li> <li> <p>Configure OpenCode with two providers (`ollama`on :11434,`ollama-b`on :11435)</p> </li> </ol> </div> <div class="paragraph"> <p>Two accounts, one credit card, zero conflicts.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_the_audit_doesnt_measure">What the Audit Doesn’t Measure</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">Blind spot</th> <th class="tableblock halign-left valign-top">Impact</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Quality of produced code</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.6 billion tokens don’t say if the code compiles. My 8 DeepSeek V4 Pro sessions have a first-shot rate >90%.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>OpenCode Ecosystem</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The CLI is free, but its value (agents, sandboxes, history, prompt caching) is immense. It’s not included in the subscription price — it’s a separate tool.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Opportunity cost</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spending 2h/day debugging hallucinations from an inferior model costs more than €20/month.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Peace of mind</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fixed flat rate = no surprises. With per-token, an activity spike can hurt badly.</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>The prices cited are those of May 2026. In six months, everything will have dropped. But the structural power balance — fixed subscription vs. pay-as-you-go — will remain favorable to the subscription for heavy consumers.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_verdict_of_the_numbers">Conclusion: The Verdict of the Numbers</h2> <div class="sectionbody"> <div class="paragraph"> <p>After 73 days, 1,022 OpenCode sessions, and 2.6 billion 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">Metric</th> <th class="tableblock halign-left valign-top">Verdict</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cumulative external API cost</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$0.22</strong>(nearly zero)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Cloud Pro subscription cost</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~€20/month</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus equivalent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$1,148/month</strong>— 57× more expensive</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5 equivalent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$1,157/month</strong>— 58× more expensive</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">HuggingFace/Novita equivalent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$374/month</strong>— 19× more expensive</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek direct API equivalent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$390/month</strong>— 20× more expensive</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Cheapest equivalent (Gemini Flash)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$69/month</strong>— 3.5× more expensive, inferior model</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Best market offer</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro at €20/month</strong>— unbeatable</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>__</em> At €20 per month for access to DeepSeek V4 Pro (1.6T params, MoE, CSA+HCA, 1M context) via Ollama Cloud, I have the best quality/price ratio on the global market. Even direct Chinese providers are 5× to 20× more expensive. Even HuggingFace, with its low-cost provider aggregation, is 19× more expensive. The Western market (Claude, GPT) is at 50-60× — another planet.</p> </div> <div class="paragraph"> <p>This ratio is so unbalanced that it cannot last forever. Take advantage of it while it exists. <em>__</em></p> </div> <div class="paragraph"> <p>So yes, my 20 bucks a month is the best technical investment of my developer life. And now you have the numbers to prove it.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — EAGER/LAZY/Hot/Warm/Cold Agent Governance</a></p> </li> <li> <p><a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Article 0112 — DeepSeek V4 Pro vs Kimi K2.6 vs GLM 5.1</a></p> </li> <li> <p><a href="0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html">Article 0119 — Benchmark DGX Spark vs Cloud vs LLM Subscriptions</a></p> </li> <li> <p><a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">Article 0120 — Combining Two Ollama Cloud Pro Subscriptions with Docker</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Gradle Plugin to Drive Two Ollama Instances</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Article 0122 — 27× to 54× Efficiency Ratio</a></p> </li> </ul> </div> <div class="sect2"> <h3 id="_pricing_sources">Pricing Sources</h3> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/pricing">Ollama Cloud — Pro Rates \$20/month</a></p> </li> <li> <p><a href="https://api-docs.deepseek.com/quick_start/pricing">DeepSeek API — Official V4 Pro Rates</a></p> </li> <li> <p><a href="https://platform.kimi.com/docs/pricing/chat-k26">Kimi Moonshot — K2.6 Rates</a></p> </li> <li> <p><a href="https://huggingface.co/inference/models">HuggingFace Inference Providers — Rates per provider</a></p> </li> <li> <p><a href="https://www.anthropic.com/pricing">Anthropic — Claude API Rates</a></p> </li> <li> <p><a href="https://openai.com/api/pricing/">OpenAI — GPT API Rates</a></p> </li> <li> <p><a href="https://together.ai/pricing">Together AI — Inference Rates</a></p> </li> <li> <p><a href="https://groq.com/pricing">Groq — API Rates</a></p> </li> <li> <p><a href="https://deepinfra.com/pricing">DeepInfra — GPU and model rates</a></p> </li> <li> <p><a href="https://help.aliyun.com/zh/model-studio/text-generation-model/">Alibaba Bailian — Available models</a></p> </li> <li> <p><a href="https://github.com/anomalyco/opencode">OpenCode — Open source CLI on GitHub</a></p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_three_architectures_that_wasted_my_time">The Problem: Three Architectures That Wasted My Time</a> <ul class="sectlevel2"> <li><a href="#_option_1_the_isolated_plugin_no_dogfooding">Option 1: The Isolated Plugin (no dogfooding)</a></li> <li><a href="#_option_2_the_classic_monorepo_includeplugin">Option 2: The Classic Monorepo (<code>include(":plugin")</code>)</a></li> <li><a href="#_option_3_the_composite_build_includebuild">Option 3: The Composite Build (<code>includeBuild()</code>)</a></li> </ul> </li> <li><a href="#_the_solution_two_independent_builds_one_consumer_root">The Solution: Two Independent Builds, One Consumer Root</a> <ul class="sectlevel2"> <li><a href="#_the_workflow">The Workflow</a></li> <li><a href="#_the_concrete_workflow">The Concrete Workflow</a></li> </ul> </li> <li><a href="#_why_this_architecture_won_me_over">Why This Architecture Won Me Over</a> <ul class="sectlevel2"> <li><a href="#_1_native_dogfooding_instant_feedback">1. Native Dogfooding, Instant Feedback</a></li> <li><a href="#_2_zero_config_cloning">2. Zero-Config Cloning</a></li> <li><a href="#_3_isolated_builds_independent_ci">3. Isolated Builds, Independent CI</a></li> </ul> </li> <li><a href="#_the_anatomy_of_the_name_plugin_sub_folder">The Anatomy of the <code>{name}-plugin/</code> Sub-folder</a> <ul class="sectlevel2"> <li><a href="#_the_version_catalog_two_distinct_files">The Version Catalog: Two Distinct Files</a></li> </ul> </li> <li><a href="#_what_we_dont_do">What We Don’t Do</a></li> <li><a href="#_comparison_the_three_architectures_facing_dogfooding">Comparison: The Three Architectures Facing Dogfooding</a></li> <li><a href="#_the_dag_contract_a_root_build_never_imports_from_a_sub_folder">The DAG Contract: A Root Build Never Imports from a Sub-folder</a></li> <li><a href="#_conclusion_the_apparent_duplication_that_saves_time">Conclusion: The Apparent Duplication That Saves Time</a></li> <li><a href="#_references">References</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 11 minutes</div> <p>You clone a Gradle plugin repository. You open a terminal. What do you type next?<code>./gradlew tasks</code>, of course. But in which folder? The root? The sub-module? Do you first have to read a README to know how to build? If you hesitate for even a second, the project architecture is broken.</p> </div> <div class="paragraph"> <p>Here is how I solved this problem once and for all — and why this pattern is now the signature of all my Gradle plugins in`foundry/public/`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_three_architectures_that_wasted_my_time">The Problem: Three Architectures That Wasted My Time</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before converging on the current pattern, I experimented with three classic approaches for organizing a Gradle plugin. Each had a deal-breaking flaw.</p> </div> <div class="sect2"> <h3 id="_option_1_the_isolated_plugin_no_dogfooding">Option 1: The Isolated Plugin (no dogfooding)</h3> <div class="paragraph"> <p>The project contains only the plugin. No consumption example. No project that exercises it. To test it, you must create an external project, reference the plugin via`mavenLocal`or a composite build, and only then verify that it works.</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>A Gradle plugin without a consumption example is like a library without integration tests. You never know if the latest change has broken the user experience.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_option_2_the_classic_monorepo_includeplugin">Option 2: The Classic Monorepo (<code>include(":plugin")</code>)</h3> <div class="paragraph"> <p>Gradle`init`generates`settings.gradle.kts`with`include("plugin")`. The root and the sub-module share the same daemon, the same configurations, the same catalogs. Convenient, but coupled.</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>Where it fails:</p> </div> <div class="ulist"> <ul> <li> <p>The root<strong>must</strong>have the same Gradle version as the sub-module.</p> </li> <li> <p>`libs.versions.toml`is shared — common version catalogs, dependencies</p> </li> </ul> </div> <div class="paragraph"> <p>leaking from one module to another.</p> </div> <div class="ulist"> <ul> <li> <p>Impossible to build the plugin independently of the root.</p> </li> <li> <p>The CI must build both modules, even if only the plugin has changed.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_option_3_the_composite_build_includebuild">Option 3: The Composite Build (<code>includeBuild()</code>)</h3> <div class="paragraph"> <p>We separate the two into distinct Gradle builds and link them via <code>includeBuild("mon-plugin")`in`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>This is already better. The plugin build is isolated. But the consumer must explicitly reference the external build — and the output of `./gradlew tasks`at the root depends on the correct configuration of the composite. Cloning is not zero-config: you need to know that the plugin is in a separate folder, that the root references it, 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>I was looking for something better. Much better.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_two_independent_builds_one_consumer_root">The Solution: Two Independent Builds, One Consumer Root</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is the pattern I eventually adopted:</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>The key:`{name}-plugin/`is a <strong>complete and autonomous</strong> Gradle project. It has its own wrapper, its own settings, its own version catalog. It clones, builds, tests, and publishes without the root being aware of its existence.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>The root, meanwhile, does only <strong>one</strong> thing: apply the 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>Three lines in the case of`bakery-gradle`. Nothing more. Zero`include()<code>, zero`includeBuild()</code>, zero sub-projects. A classic Gradle build that applies a plugin just as any consumer would.</p> </div> <div class="sect2"> <h3 id="_the_workflow">The Workflow</h3> <div class="imageblock"> <div class="content"> <img src="./images/architecture-deux-builds.svg" alt="architecture deux builds" width="1219" height="151"> </div> </div> </div> <div class="sect2"> <h3 id="_the_concrete_workflow">The Concrete Workflow</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="_why_this_architecture_won_me_over">Why This Architecture Won Me Over</h2> <div class="sectionbody"> <div class="paragraph"> <p>Three benefits that, combined, are worth the cost of "duplication":</p> </div> <div class="sect2"> <h3 id="_1_native_dogfooding_instant_feedback">1. Native Dogfooding, Instant Feedback</h3> <div class="paragraph"> <p>The best test for a Gradle plugin is to use it. Not a mocked unit test. Not a`GradleRunner`with a test project. A <strong>real</strong> build applying the plugin to real files.</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>If the plugin is broken, the root build says so. No need to go look for an external test project. Dogfooding is the <strong>first</strong> task a new contributor runs. It is the definitive smoke test.</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>The rule is simple: if the root compiles and`./gradlew tasks` displays your plugin tasks, the plugin is functional. No surprises in production.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_zero_config_cloning">2. Zero-Config Cloning</h3> <div class="paragraph"> <p>Un `git clone && ./gradlew tasks`and the newcomer sees everything working without configuring anything. The`build.gradle.kts`root is the living documentation of the plugin’s usage. The`site.yml`next to it shows the expected configuration.</p> </div> <div class="paragraph"> <p>Compare this with the alternative: a three-paragraph README that explains how to build the plugin AND how to build the test project. A new contributor skims the README, makes a mistake, opens an issue — when the information could be <strong>executable</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>The most robust documentation isn’t the one we read. It’s the one we<strong>execute</strong>. The root build is the plugin’s executable documentation.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3_isolated_builds_independent_ci">3. Isolated Builds, Independent CI</h3> <div class="paragraph"> <p>The plugin has its own Gradle wrapper, its own lifecycle, its own tests. You can:</p> </div> <div class="ulist"> <ul> <li> <p>Upgrade Gradle in the plugin without touching the root</p> </li> <li> <p>Add a dependency in the plugin without it leaking into the root</p> </li> <li> <p>Break the plugin without impacting the root build (as long as you</p> </li> </ul> </div> <div class="paragraph"> <p>don’t publish the broken version)</p> </div> <div class="ulist"> <ul> <li> <p>Have one CI that builds/tests the plugin, and another that exercises the</p> </li> </ul> </div> <div class="paragraph"> <p>root — independently</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="_the_anatomy_of_the_name_plugin_sub_folder">The Anatomy of the <code>{name}-plugin/</code> Sub-folder</h2> <div class="sectionbody"> <div class="paragraph"> <p>Let’s look closer at what lives in the plugin folder:</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>Everything is there. No dispersion between the root and the sub-folder. The developer working on the plugin never needs to leave`codebase-plugin/`. The developer using the plugin only looks at the root — and the`build.gradle.kts`of 3 lines tells them everything they need to know.</p> </div> <div class="sect2"> <h3 id="_the_version_catalog_two_distinct_files">The Version Catalog: Two Distinct Files</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>(root)</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">Number of dependencies</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2-3 (plugin + readme eventually)</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">Role</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consume the plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Build the plugin</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Who reads it</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The plugin user</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The plugin developer</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The root has a deliberately minimal catalog. The plugin has a complete catalog. Confusion is impossible: each build has its own dependency scope.</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>If you’ve ever spent an hour debugging a dependency collision between your plugin and your test project, you understand the value of this separation. Independent catalogs eliminate this problem by design.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_what_we_dont_do">What We Don’t Do</h2> <div class="sectionbody"> <div class="paragraph"> <p>This pattern isn’t magic. It imposes a constraint that I willingly accept:</p> </div> <div class="paragraph"> <p><strong>The root does not build the plugin.</strong> You must`publishToMavenLocal` ou deploy to a repository before the root can consume it.</p> </div> <div class="paragraph"> <p>This is a minimal cost, and it’s the <strong>right</strong> constraint. The root consumes the plugin like an external client — via Maven. Exactly as a third-party project would. If the plugin isn’t publishable, the root tells you immediately.</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="_comparison_the_three_architectures_facing_dogfooding">Comparison: The Three Architectures Facing 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">Isolated plugin</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">Composite`includeBuild()`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Root + indep. plugin</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`git clone && gradlew tasks`gives the plugin tasks</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">Plugin build independent of 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">Separate version catalog</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No`include()` ni <code>includeBuild()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Native dogfooding without 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">⚠️</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">Independent plugin CI</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">Root is a real consumption example</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The right column checks all the boxes. That’s why I’m not going back.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_dag_contract_a_root_build_never_imports_from_a_sub_folder">The DAG Contract: A Root Build Never Imports from a Sub-folder</h2> <div class="sectionbody"> <div class="paragraph"> <p>This architecture integrates naturally into the N0→N3 DAG of my workspace. The pattern is: <strong>the N2 plugin is the hub of its own dependencies, the N3 root is a terminal that applies hubs</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/contrat-dag-architecture.svg" alt="contrat dag architecture" width="742" height="428"> </div> </div> <div class="paragraph"> <p>Le <code>codebase-gradle/build.gradle.kts`is 6 lines. No`src/</code>, no`buildSrc/<code>, no`gradle/rag-bench.gradle.kts</code>. Just <code>plugins { alias(libs.plugins.codebase) }`and the repositories. All the complexity lives in`codebase-plugin/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_apparent_duplication_that_saves_time">Conclusion: The Apparent Duplication That Saves Time</h2> <div class="sectionbody"> <div class="paragraph"> <p>When I show this structure to someone, the first reaction is often: "But you have two`gradlew`, two`settings.gradle.kts`, two`libs.versions.toml`— that’s duplication!"</p> </div> <div class="paragraph"> <p>Yes. And no.</p> </div> <div class="paragraph"> <p>"Duplication" is reproducing the same information in two places. Here, these are two <strong>distinct</strong> files serving two <strong>distinct</strong> purposes: the plugin catalog (30+ dependencies to build) and the root catalog (2-3 dependencies to consume). The plugin wrapper (locked version for development) and the root wrapper (potentially different version, for exercising the plugin).</p> </div> <div class="paragraph"> <p>This is not duplication. This is <strong>separation of concerns</strong> applied to the build system. Each build does one thing, and one thing only. The root consumes. The plugin builds.</p> </div> <div class="paragraph"> <p>The cost? One`publishToMavenLocal`command between the plugin build and the root build. The gain? Architectural clarity that removes hours of downstream debugging.</p> </div> <div class="paragraph"> <p>Since I deployed this pattern on`bakery-gradle`, <code>plantuml-gradle</code>, <code>codebase-gradle</code>, and other`foundry/public/<code>plugins, I have never hesitated again when opening a terminal in one of my repos. The first reflex —</code>./gradlew tasks`— always works, always gives the right tasks, and tells me instantly if everything is healthy.</p> </div> <div class="paragraph"> <p>That is what good architecture is. It isn’t read in a README. It is proven in a terminal, in less than ten seconds.</p> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Article 0105 — Integrating Graphify into a Gradle Workflow</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — OSS/CSS Granularization</a></p> </li> <li> <p><a href="0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html">Article 0123 — The Knowledge Graph as a Recommendation Engine</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_the_scene_tuesday_may_12_530_pm">The Scene: Tuesday, May 12, 5:30 PM</a></li> <li><a href="#_the_diagnosis_three_types_of_relations_that_no_template_sees">The Diagnosis: Three Types of Relations That No Template Sees</a></li> <li><a href="#_the_first_temptation_would_be_to_call_an_llm_during_the_bake_for">The first temptation would be to call an LLM during the bake: "For</a> <ul class="sectlevel2"> <li><a href="#_this_is_the_most_important_architectural_point_the_temptation_would_be_to">This is the most important architectural point. The temptation would be to</a></li> <li><a href="#_here_is_the_complete_three_step_pipeline">Here is the complete three-step pipeline:</a></li> <li><a href="#_chronological_fallback">Chronological Fallback</a></li> </ul> </li> <li><a href="#_emerging_ontology_when_articles_group_together_without_knowing_each_other">Emerging Ontology: When Articles Group Together Without Knowing Each Other</a></li> <li><a href="#_the_dag_contract_who_imports_whom">The DAG Contract: Who Imports Whom</a></li> <li><a href="#_what_we_gain_and_what_we_dont">What We Gain (And What We Don’t)</a></li> <li><a href="#_perspectives_the_blog_as_a_public_knowledge_graph">Perspectives: The Blog as a Public Knowledge Graph</a></li> <li><a href="#_conclusion_the_file_system_knows_what_the_template_ignores">Conclusion: The File System Knows What the Template Ignores</a></li> <li><a href="#_article_0105_integrating_graphify_into_a_gradle_workflow">Article 0105 — Integrating Graphify into a Gradle workflow</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 14 minutes</div> <p>You are reading an article about integrating pgvector with LangChain4j. At the bottom of the page, JBake suggests "Related Articles." You click. It’s an article about…​ the configuration of Kitty Terminal. The only common point between the two? They were published less than fifteen days apart. That’s not a recommendation. It’s a calendar disguised as editorial.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_tuesday_may_12_530_pm">The Scene: Tuesday, May 12, 5:30 PM</h2> <div class="sectionbody"> <div class="paragraph"> <p>I am rereading one of my articles — <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">the one on the Knowledge Graph as a tool for codebase understanding</a>. The content is dense: nodes, edges, communities, PlantUML, onboarding. A technical article with a 15-minute read that leverages`graphify-gradle`, <code>plantuml-gradle</code>, and graph topology concepts.</p> </div> <div class="paragraph"> <p>At the bottom of the page, "Related Articles" propose:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>An article on Firebase Contact Form (0113)</p> </li> <li> <p>An article on the Eager/Lazy mechanism (0108)</p> </li> <li> <p>An article on Gradle script → plugin migration (0102)</p> </li> <li> <p>An article on stacking Ollama Pro subscriptions (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>Three of these four articles have <strong>no</strong> connection to the Knowledge Graph. They are there because they are the latest published — temporal proximity, not semantic proximity.</p> </div> <div class="paragraph"> <p>I look at the template`post.thyme`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes (liens internes SEO) --> <th:block th:each="post,postStat : ${published_posts}"> <th:block th:if="${!post.uri.equals(content.uri) and postStat.index lt 4}"> ... </th:block> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>`published_posts`is a chronological list.`postStat.index lt 4`takes the first four that are not the current post. That’s it. No similarity logic. No notion of content. Just a`for`loop disguised as a recommendation.</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>This isn’t a JBake bug. It’s the default behavior of every static site generator: the post list is flat and ordered by date. The template does what it can with what it has.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>But that’s no reason to accept it.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_diagnosis_three_types_of_relations_that_no_template_sees">The Diagnosis: Three Types of Relations That No Template Sees</h2> <div class="sectionbody"> <div class="paragraph"> <p>My article corpus — 23 posts in 4 months — has a rich structure that the chronological template completely flattens:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Explicit references</strong>: I use`xref:`extensively in my articles.</p> </li> </ol> </div> <div class="paragraph"> <p>Article 0122 references 0106 (knowledge graph) and 0116 (epistemic compartmentalization). These links are editorial <strong>hard linking</strong> — I deliberately decided to connect these concepts.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Shared tags</strong>: each article has`:jbake-tags:`. The article on</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) has`gradle, graphify, plantuml, knowledge-graph`. The article on the Knowledge Graph (0106) has <code>knowledge-graph, graphify, plantuml</code>. Three common tags out of seven — 43% overlap.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Co-occurring named entities</strong>: "pgvector", "RAG", "embedding"</p> </li> </ol> </div> <div class="paragraph"> <p>appear together in four different articles. "LangChain4j", "Ollama", "Gradle plugin" in six others. These are not declared tags — they are <strong>emerging patterns</strong> from the corpus that only an NLP can detect. Today, my site uses <strong>none</strong> of these three layers. It uses</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/trois-couches-relation-articles.svg" alt="trois couches relation articles" width="1110" height="239"> </div> </div> <div class="paragraph"> <p>layer zero: the insertion order in a Java list. The Solution: A Gradle Pipeline, Not a Hot LLM Call</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_first_temptation_would_be_to_call_an_llm_during_the_bake_for">The first temptation would be to call an LLM during the bake: "For</h2> <div class="sectionbody"> <div class="paragraph"> <p>this article, find the three most similar articles in the corpus." Don’t do that. An LLM call for every</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>costs time, money, and`./gradlew bake`introduces non-determinism into your build. The LLM’s response may change between two builds without the content having changed. Your CI becomes non-reproducible, your tests become flaky. The solution is deterministic: a Gradle pipeline that pre-calculates the similarity graph</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>and stores it in . The template reads the result`graph.json`— it never triggers a calculation. The Architecture: Bakery Imports Graphify, Not Engine</p> </div> <div class="sect2"> <h3 id="_this_is_the_most_important_architectural_point_the_temptation_would_be_to">This is the most important architectural point. The temptation would be to</h3> <div class="paragraph"> <p>wire the collaboration in : engine applies`engine/build.gradle.kts`graphify for the scan, bakery for the bake, and engine bridges the two. This is an anti-pattern. Engine is a <strong>consumer terminal</strong> — it applies</p> </div> <div class="paragraph"> <p>plugins; it doesn’t implement business logic. The rule is: the burden of proof is on the proprietary plugin. <strong>.Correct architecture — Bakery imports Graphify</strong></p> </div> <div class="paragraph"> <p>The DAG contract is respected: bakery (N2) imports graphify (N0), N2 > N0,</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/bakery-import-graphify.svg" alt="bakery import graphify" width="489" height="439"> </div> </div> <div class="paragraph"> <p>no violation. Engine (N3) imports bakery (N2), N3 > N2, OK. Engine has <strong>no</strong> line of code that references</p> </div> <div class="paragraph"> <p>or any other notion of similarity. It applies bakery, period. The`graph.json`, <code>relatedPosts</code>, collaboration is internal to bakery. The Pipeline: Scan → Graph → Template</p> </div> </div> <div class="sect2"> <h3 id="_here_is_the_complete_three_step_pipeline">Here is the complete three-step pipeline:</h3> <div class="paragraph"> <p><strong>Scan</strong> (graphify):</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>scans the workspace. In its`graphify-plugin`current form, it already detects</p> </li> </ol> </div> <div class="paragraph"> <p>between`xref:`and`.adoc`exposes them in as`graph.json`type edges.<code>reference`We enrich it for editorial content:<br> * Parse JBake metadata ( )</code>:jbake-tags:`, <code>:jbake-description:`of each blog de chaque `.adoc</code>* Calculate tag co-occurrences → edges with weight`tag_cooccurrence`* Extract named entities from descriptions via TF-IDF → edges`entity_overlap` * Inject a`blog_articles`section into the existing`graph.json` existant<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> (bakery): during the`./gradlew bake`, `BakeryPlugin`it reads</p> </li> </ol> </div> <div class="paragraph"> <p>`graph.json`and resolves related articles for each 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>): the JBake model now receives a</p> </li> </ol> </div> <div class="paragraph"> <p>structured map instead of a flat chronological list.<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>The template is the same — it doesn’t know <strong>where</strong> the data comes from. Only the contract between bakery and JBake has changed:`published_posts`(chronological list) becomes`relatedPosts`(graph-weighted map).</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>The "reason" badge (e.g.,<code>xref 0122</code>, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) explains to the reader <strong>why</strong> this article is related. This isn’t just transparency — it’s pedagogy on the topology of your own content.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_chronological_fallback">Chronological Fallback</h3> <div class="paragraph"> <p>Si `graph.json`is missing (local build without prior scan, first deployment, CI that hasn’t integrated the graphify scan yet), the template must degrade gracefully:</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>The default behavior is identical to the current behavior. The recommendation engine is a <strong>progressive enhancement</strong> — not a breaking change.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_emerging_ontology_when_articles_group_together_without_knowing_each_other">Emerging Ontology: When Articles Group Together Without Knowing Each Other</h2> <div class="sectionbody"> <div class="paragraph"> <p>The most interesting layer is the third: the emerging ontology. Articles that don’t cite each other, don’t have the same tags, but <strong>talk about the same thing</strong> without knowing it.</p> </div> <div class="paragraph"> <p>Let’s take a concrete example. Three articles from my corpus:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — DGX Spark Benchmark vs LLM Subscription Cloud</p> </li> <li> <p>0121 — Gradle Plugin Controlling Two Ollama Pro Instances</p> </li> <li> <p>0122 — 27x 45x Efficiency Ratio AI Expert Fleet</p> </li> </ol> </div> <div class="paragraph"> <p>These three articles have <strong>no</strong> xrefs between them. Their tags only overlap by 20% ("ollama", "llm" common). But a light NLP on the descriptions reveals an obvious cluster: "cost", "subscription", "cloud", "GPU", "API key", "Ollama Pro", "efficiency", "ratio".</p> </div> <div class="paragraph"> <p>They form an ontological cluster: <strong>the economics of self-hosted vs cloud LLM</strong>. This cluster is declared nowhere. It emerges from the 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>This ontological cluster becomes a composite edge in`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>The NLP is intentionally light — TF-IDF + cosine similarity on descriptions. No need for BERT, no need for a language model. The corpus has 23 articles; the similarity matrix fits in a 50 KB JSON file.</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>The power of NLP doesn’t come from the sophistication of the algorithm, but from the <strong>corpus size</strong> and the <strong>quality of the descriptions</strong>. A `:jbake-description:`well-written description of 150 characters contains more signal for TF-IDF than a full 3000-word article.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_the_dag_contract_who_imports_whom">The DAG Contract: Who Imports Whom</h2> <div class="sectionbody"> <div class="paragraph"> <p>This is where architectural discipline pays off. The N0→N3 DAG defined in`engine/build.gradle.kts`provides a simple rule: no project imports a higher-level project.</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">Consumer Plugin</th> <th class="tableblock halign-left valign-top">Imported Plugin</th> <th class="tableblock halign-left valign-top">Consumer Level</th> <th class="tableblock halign-left valign-top">Imported Level</th> <th class="tableblock halign-left valign-top">Valid?</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">engine</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">engine</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">✅ Technically OK, but <strong>conceptually wrong</strong> — the collaboration is internal to bakery</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Engine applies bakery. Bakery applies graphify. That’s it. If one day I want to add the codebase vector store (N1) for cross-corpus semantic search, bakery imports it too. Engine doesn’t change.</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>The pattern is: <strong>the N2 plugin is the hub for its own dependencies</strong>. Engine N3 is not a hub — it’s a terminal that applies hubs.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_what_we_gain_and_what_we_dont">What We Gain (And What We Don’t)</h2> <div class="sectionbody"> <div class="paragraph"> <p>The main gain is editorial, not technical:</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">Before</th> <th class="tableblock halign-left valign-top">After</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Related articles = 4 latest posts</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Related articles = top 4 by weight in the Knowledge Graph</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reader reads about RAG → Kitty Terminal recommendation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reader reads about RAG → pgvector, chunking, vector store recommendation</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero transparency on why</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Badge <code>xref 0122</code>, <code>tag:gradle</code>, `cluster:rag`badge visible</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Standard JBake, zero effort, zero value</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Deterministic, reproducible, testable Gradle pipeline</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No learning curve for the reader</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The reader discovers the <strong>topology</strong> of my content</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>What we <strong>don’t</strong> gain:</p> </div> <div class="ulist"> <ul> <li> <p>This isn’t a "real" recommendation engine (no collaborative</p> </li> </ul> </div> <div class="paragraph"> <p>filtering, no A/B testing, no feedback loop)</p> </div> <div class="ulist"> <ul> <li> <p>Quality depends on the richness of JBake metadata — if your</p> </li> </ul> </div> <div class="paragraph"> <p>descriptions are empty, TF-IDF sees nothing</p> </div> <div class="ulist"> <ul> <li> <p>NLP is offline — new articles are only clustered during the</p> </li> </ul> </div> <div class="paragraph"> <p>next scan (which is good: the build remains deterministic)</p> </div> </div> </div> <div class="sect1"> <h2 id="_perspectives_the_blog_as_a_public_knowledge_graph">Perspectives: The Blog as a Public Knowledge Graph</h2> <div class="sectionbody"> <div class="paragraph"> <p>This feature opens a broader perspective: what if`cheroliv.com` became a <strong>navigable knowledge graph</strong> itself?</p> </div> <div class="paragraph"> <p>Articles are nodes. Tags are communities. Xrefs are edges. The reader no longer reads an isolated article — they navigate a <strong>knowledge graph</strong> where the current article is the entry point.</p> </div> <div class="paragraph"> <p>Imagine a homepage that displays not a chronological list of recent posts, but a <strong>corpus map</strong>: ontological clusters, pivot articles (those with the most edges), recommended reading paths ("If you liked the article on Graphify, then read the one on the Knowledge Graph as a tool for understanding").</p> </div> <div class="paragraph"> <p>It’s no longer a blog. It’s a <strong>semantic atlas</strong>.</p> </div> <div class="paragraph"> <p>And this isn’t science fiction. The`graph.json`already exists. It only lacks the navigation interface.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_file_system_knows_what_the_template_ignores">Conclusion: The File System Knows What the Template Ignores</h2> <div class="sectionbody"> <div class="paragraph"> <p>What I designed this Tuesday evening is the replacement of a lazy heuristic (chronological order) with a faithful representation of the structure of my corpus (the Knowledge Graph).</p> </div> <div class="paragraph"> <p>The template`post.thyme`doesn’t change. What changes is what we feed it. Before: a Java list ordered by`date`. After: a weighted graph resulting from three layers of analysis — xrefs, tag co-occurrences, and emerging ontology via NLP.</p> </div> <div class="paragraph"> <p>The loop is closed. graphify scans the workspace. Bakery reads the graph and feeds the template. The reader sees relevant recommendations. And engine — the conductor — doesn’t even know that any of this exists. That is good architecture. Each plugin does one thing.</p> </div> <div class="paragraph"> <p>And the consumer terminal doesn’t need to know how. References</p> </div> </div> </div> <div class="sect1"> <h2 id="_article_0105_integrating_graphify_into_a_gradle_workflow"><a href="0105_integrer_graphify_workflow_gradle_post.html">Article 0105 — Integrating Graphify into a Gradle workflow</a></h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Article 0106 — The Knowledge Graph as an understanding tool</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — OSS/CSS Granularization</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Gradle Plugin Controlling Two Ollama Pro Instances</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Article 0122 — 27× to 45× more efficient: AI expert fleet</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Article 0122 — 27× à 45× plus efficace : flotte d’experts IA</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_why_fine_tuning_instead_of_rag">The problem: why fine-tuning instead of RAG?</a></li> <li><a href="#_the_idea_a_fleet_of_experts_not_a_single_model">The idea: a fleet of experts, not a single model</a></li> <li><a href="#_codebase_under_the_microscope_7900_files_144000_lines">Codebase under the microscope: 7,900 files, 144,000 lines</a></li> <li><a href="#_inference_23_models_on_ollama_cloud_from_17month">Inference: 23 models on Ollama Cloud from €17/month</a> <ul class="sectlevel2"> <li><a href="#_start_at_17month_scale_if_needed">Start at €17/month, scale if needed</a></li> <li><a href="#_routing_in_practice">Routing in practice</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 22 minutes</div> <p>When you use an LLM for daily software development, you always end up hitting the same wall: the model doesn’t know <strong>your</strong> codebase. It doesn’t know that you use such ahttps://fr.wikipedia.org/wiki/Graphe_orient%C3%A9_acyclique[DAG]pattern, such a Gradle convention, or such epistemic stratification in yourhttps://fr.wikipedia.org/wiki/AsciiDoc[<code>.adoc</code>]files. So you inject context, you repeat, you correct, you iterate. And time — and money — slip away.</p> </div> <div class="paragraph"> <p>I therefore asked the question bluntly: how much would a team of models fine-tuned on my workspace cost, capable of spitting out code <strong>in my style</strong> without needing to be explained every time? And above all: how does this approach compare to classic proprietary solutions — Claude, GPT, Gemini, Grok?</p> </div> <div class="paragraph"> <p>The answer surprised me. Much less than I imagined. And the cost/efficiency ratio against the industry giants is indecent. Here is the full detail.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_why_fine_tuning_instead_of_rag">The problem: why fine-tuning instead of RAG?</h2> <div class="sectionbody"> <div class="paragraph"> <p>RAG is good. <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">My knowledge graph</a> and <a href="0116_compartimentage_epistemique_automatise_llm_post.html">my epistemic compartmentalization</a> work. But RAG has a fundamental flaw: with every request, you must re-inject the relevant context. Your prompt grows, your latency explodes, and the model never <strong>internalizes</strong> your patterns — it reads them every time as an external document.</p> </div> <div class="paragraph"> <p>Fine-tuning, on the other hand, is muscle memory. The model <strong>knows</strong> that you write`build.gradle.kts`with tasks recorded via`tasks.register`, that your`AGENTS.adoc`follow a standardized syntax, that your workspace is structured in boroughs. It doesn’t need to be reminded.</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>Fine-tuning is not a replacement for RAG. It is a complementary layer. RAG remains relevant for data that changes often (logs, tickets, recent commits). Fine-tuning is for long-term <strong>structural</strong> and <strong>stylistic</strong> knowledge.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_the_idea_a_fleet_of_experts_not_a_single_model">The idea: a fleet of experts, not a single model</h2> <div class="sectionbody"> <div class="paragraph"> <p>A single model fine-tuned on my entire workspace is already good. But it’s suboptimal. My workspace covers very different domains:</p> </div> <div class="ulist"> <ul> <li> <p>Gradle plugins (Kotlin, convention plugins, composite builds)</p> </li> <li> <p>DAG Engine (Kotlin, scheduling, execution)</p> </li> <li> <p>LLM Agents (Python, LangChain4j, RAG)</p> </li> <li> <p>Architectural documentation (AsciiDoc, governance)</p> </li> <li> <p>Infra/DevOps (Docker, GitHub Actions, CI/CD)</p> </li> </ul> </div> <div class="paragraph"> <p>A single model should be good everywhere, excellent nowhere. The solution? A<strong>fleet of specialized models</strong>, with an orchestrator that routes each request to the right expert.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/fleet-architecture.svg" alt="fleet architecture" width="871" height="462"> </div> </div> <div class="paragraph"> <p>Total fleet:<strong>1 orchestrator + 22 experts = 23 models</strong>. And the monthly inference cost?<strong>€17/month</strong>on an annual Ollama Pro subscription — expandable by stacking accounts if quotas are exceeded, as demonstrated in <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">my multi-account Docker method</a>. We start at €17, then add €20 per tier based on actual need. No waste.</p> </div> </div> </div> <div class="sect1"> <h2 id="_codebase_under_the_microscope_7900_files_144000_lines">Codebase under the microscope: 7,900 files, 144,000 lines</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before estimating training costs, we need to know what to train. I audited my workspace by rigorously excluding everything ignored by 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/ ---- Here is the result for tracked files only: [cols="2,2"] |=== |Metric |Value |Tracked source files |**7,896** |Lines of code (LOC) |**143,805** |Git repositories |**26** |Main languages |Kotlin (1,903), AsciiDoc (2,765), Python (5,029) |=== [IMPORTANT] ==== These 5,000+ Python files include`runtimes/`from notebooks and utility scripts. The application core (Gradle plugins, DAG engine, agents) is primarily in Kotlin and AsciiDoc. ==== From this mass, I estimate I can generate a synthetic dataset of**~170 million tokens**via an instructor LLM (distillation of the codebase into instruction/response pairs). === Dataset detail by expert type [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 ---- == Choosing the models: 100% MoE, zero dense This is where the architecture becomes truly efficient. A *dense* model activates all its weights for every token. An *MoE* (Mixture of Experts) model only activates a fraction of its parameters. The inference cost — and fine-tuning cost — is proportional to the**activated**parameters, not the**stored**parameters. Let's look at what the market offers in MoE today on Ollama Cloud: [cols="3,2,2,1,3"] |=== |Model |Total params |Activated |Activation |Ollama Cloud |DeepSeek V4-Pro |1.6T |49B |3.1% |✅ native |DeepSeek V4-Flash |292B |13B |4.5% |✅ native |Gemma 4 26B-A4B |26B |3.8B |14.6% |✅ native |Qwen3.6-35B-A3B |35B |3B |8.6% |❌ (not yet integrated) |Qwen3.5-35B-A3B |35B |3B |8.6% |✅ native |❌ Qwen3.5-27B |27B |27B |100% dense |eliminated |❌ Qwen3.5-4B/9B |4B/9B |4B/9B |100% dense |eliminated |❌ Gemma 4 31B |31B |31B |100% dense |eliminated |🧪 Gemma 4 E2B/E4B |5B/8B |5B/8B |100% dense |validation pipeline |=== [CAUTION] ==== The activation ratio is the discriminating criterion. A Gemma 4 26B-A4B only activates 3.8B of its 26B parameters — that's 7× less than a dense 27B, for comparable coding agent performance (77.1% vs 80% on LiveCodeBench v6). ==== === Why I'm abandoning dense models The exception: Gemma 4 E2B and E4B. These two models, under Apache 2.0, are perfect for testing and validating a training pipeline at a lower cost. A 2-3h run on an E2B costs less than $5 — if the dataset or hyperparameters are faulty, we know it for a few dollars. Once the pipeline is dialed in, they can even be used for ultra-micro tasks (trivial reformatting, binary classification). But for the main fleet experts, I'm sticking with MoE. Here's why: .But not only: Gemma 4 E2B/E4B, experts in fine anonymization [NOTE] ==== Google designed these small models to be competitive in native tool calling — they know how to call functions, manipulate regex, and search for patterns. Once fine-tuned on anonymization examples (emails, tokens, UUIDs, file paths), they become ultra-fast**dataset anonymizers**. We feed them a block of raw text, they call`sed`/`regex`via a tool call and return the cleaned block. The inference cost is negligible: 5B activated, it fits on a single entry-level GPU. These models are not business experts — they are**specialized workers**in the dataset production chain. ==== * Its training VRAM (even in QLoRA) is proportional to the**27B total** * Its training time is proportional to the**27B activated** Let's compare with a Qwen3.6-35B-A3B (MoE): [cols="3,2,2,2"] |=== | |Qwen3.5-27B (dense) |Qwen3.6-35B-A3B (MoE) |Ratio |VRAM QLoRA |~55 GB |~35 GB |1.6× |GPU-hours (8M tok) |~12h |~4h |**3×** |Cost per fine-tune |~$24 |~$8 |**3×** |SWE-bench Verified |75.0% |73.4% |comparable |=== MoE costs 3× less to train for agent-coding performance within 5%. Across 22 experts, the gap amounts to thousands of euros. == Training estimation: 811 H100-hours I broke down the training cost model by model, in 4-bit QLoRA, with the datasets described above. === Lightweight MoE micro-experts (3-3.8B activated) These models require 1 H100 (80 GB) per run. Model VRAM in Q4 is around 13-18 GB, leaving plenty of room for LoRA optimizer states and activations. [cols="4,2,3,2"] |=== |Model |Nb of runs |GPU-h/run |Total GPU-h |Gemma 4 26B-A4B-FT |6 |3.5 h |**21 h** |Qwen3.6-35B-A3B-FT |5 |4.0 h |**20 h** |Qwen3.5-35B-A3B-FT |5 |4.0 h |**20 h** |*Micro subtotal* | | |*61 h* |=== === V4-Flash Executives (13B activated / 292B stored) DeepSeek V4-Flash is a special case. Even though only 13B are activated per token, the full model in Q4 weighs ~142 GB — all experts must be in VRAM during training. Thus,**3× H100**per run is needed to be comfortable. [cols="4,2,3,3,2"] |=== |Model |Dataset |GPUs |Hours |Total GPU-h |V4-Flash Generalist-Base |50M tok |3× H100 |50 h |**150 h** |V4-Flash expert ×5 |15M tok |3× H100 |40 h |**600 h** |*Executive subtotal* | | | |*750 h* |=== [cols="3,2,1"] |=== |**TOTAL** | |**811 H100-h** |=== [NOTE] ==== For comparison, a full fine-tune of V4-Flash (without QLoRA, all weights) would cost ~4,000 H100-h just for the 6 models. QLoRA divides the cost by 5. It is the only way to make the project economically viable at this scale. ==== === GPU Rates: who rents what in May 2026 I benchmarked the main H100 providers. The list price, for 811 hours. [cols="3,2,2,2"] |=== |Provider |$/H100·h |Total 811h |Reliability |**Vast.ai spot** |$1.60 |**$1,298** |★★☆ interruptible |**Crusoe Cloud** |$2.00 |**$1,622** |★★★★ reliable datacenter |FluidStack |$1.98 |$1 606 |★★★ |TensorDock |$1.80 |$1 460 |★★☆ |RunPod |$2.29 |$1 857 |★★★ good compromise |CoreWeave |$2.25 |$1 825 |★★★★ corporate |Lambda Labs |$2.49 |$2 019 |★★★★ premium |=== [TIP] ==== Vast.ai spot is the cheapest but your runs can be interrupted at any time. For training, that's risky. Crusoe at $2.00/h is the best reliability/price ratio. The $324 surcharge vs Vast is worth the peace of mind. ==== === Wall-clock: how long to train everything? With a single 3× H100 node, the 31 runs (1 generalist + 30 experts) take about**12 days**sequentially. If you rent 2 nodes in parallel, it drops to**6 days**. In practice, micro-experts can run on separate nodes (1 H100 each) while the V4-Flashes occupy the 3× H100 node. With smart planning:</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>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)</pre> </div> </div> <div class="paragraph"> <p>7 days of rental, all done.</p> </div> </div> </div> <div class="sect1"> <h2 id="_inference_23_models_on_ollama_cloud_from_17month">Inference: 23 models on Ollama Cloud from €17/month</h2> <div class="sectionbody"> <div class="paragraph"> <p>This is the most elegant part of the architecture.</p> </div> <div class="paragraph"> <p>Ollama Cloud allows uploading private models (Pro plan feature). My 22 fine-tuned models are pushed as`.gguf`to my Ollama space, marked as private, and accessible via the standard API.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/inference-flow.svg" alt="inference flow" width="918" height="524"> </div> </div> <div class="sect2"> <h3 id="_start_at_17month_scale_if_needed">Start at €17/month, scale if needed</h3> <div class="paragraph"> <p>The Ollama Pro plan (€17/month annually) allows 3 concurrent cloud models. In this architecture, I never need more than 2-3 experts simultaneously:</p> </div> <div class="ulist"> <ul> <li> <p>The classification phase (V4-Pro) occupies 1 slot, for a few seconds</p> </li> <li> <p>The targeted expert occupies 1 slot, for the time it takes to generate its response</p> </li> <li> <p>The 3rd slot remains in reserve for parallel tasks</p> </li> </ul> </div> <div class="paragraph"> <p>If usage increases, I add additional Pro accounts via the Docker method described in <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">my article on stacking subscriptions</a>. No €100/month Max plan — I only add what I actually need.</p> </div> <div class="paragraph"> <p>The only limiting factor is the monthly<strong>GPU-time quota</strong>of Ollama (50× the free plan for Pro). For my usage of a few hundred requests per day, this is more than enough.</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>The marginal cost of a call to V4-Pro (49B activated) vs Gemma 4 26B-A4B (3.8B activated) is the<strong>same for me: zero</strong>. It’s the Ollama flat rate that absorbs the compute difference. My only indicator is latency.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_routing_in_practice">Routing in practice</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- Volume de requêtes estimé : ~500/jour ├─ 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 ---- The bulk of the traffic goes through the small ones. The big model only intervenes as a last resort. == The painful comparison: Claude, GPT, Gemini, Grok vs my fleet This is where the gap becomes dizzying. Let's look at what the same volume of work (500 requests/day, ~300 input tokens + 2,000 output tokens on average) would cost with the market's proprietary solutions in May 2026. === Anthropic — Claude (May 2026 rates) Anthropic recently *lowered* its prices. The pressure from open-weight solutions like DeepSeek and Qwen is being felt. [cols="3,2,2,2,2"] |=== |Model |Input $/MTok |Output $/MTok |Cost/day |**Cost/month** |Opus 4.7 (most intelligent) |$5 |$25 |$25.75 |**$772** |Sonnet 4.6 (balanced) |$3 |$15 |$15.45 |**$463** |Haiku 4.5 (fastest) |$1 |$5 |$5.15 |**$154** |=== [CAUTION] ==== These rates are *after* Anthropic's latest price drop (May 2026). Before that, Opus was at $15/$75 per MTok. The fear of open-weight is real. ==== Even the cheapest Claude model — Haiku 4.5 at**€154/month**— costs 9× more than my €17 Ollama Pro subscription. And Haiku doesn't know my codebase, doesn't generate in my style, and requires systematic prompt engineering. The most intelligent — Opus 4.7 — blows the budget at**€772/month**for a modest volume of 500 requests per day. That is**45× more expensive**than my solution. === OpenAI — GPT (May 2026 rates) [cols="3,2,2,2,2"] |=== |Model |Input $/MTok |Output $/MTok |Cost/day |**Cost/month** |GPT 5.5 (most intelligent) |$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** |=== Even OpenAI's "economical" model — GPT 5.4 Mini at €139/month — costs 8× my subscription, for a model that knows *nothing* of my conventions and requires heavy prompt engineering. GPT 5.5, their flagship:**€927/month**. For *zero-shot* on my codebase. With 2-3 iterations per task due to unmastered style, the real monthly cost easily doubles. === Google — Gemini (May 2026 rates) [cols="3,2,2,2,2"] |=== |Model |Input $/MTok |Output $/MTok |Cost/day |**Cost/month** |Gemini 3.1 Pro (High) |$3.50 |$17.50 |$18.00 |**$540** |Gemini 3.1 Pro |$2 |$10 |$10.30 |**$309** |Gemini 3 Flash |$0.30 |$1.50 |$1.54 |**$46** |=== Gemini 3 Flash at €46/month is competitive in pure price — but without fine-tuning, it generates "generic" code. Not *Cheroliv* code. === Grok — xAI (May 2026 rates) [cols="3,2,2,2,2"] |=== |Model |Input $/MTok |Output $/MTok |Cost/day |**Cost/month** |Grok 4 |$4 |$16 |$16.48 |**$494** |Grok 4 Mini |$0.80 |$3.20 |$3.30 |**$99** |=== === Microsoft — Azure OpenAI (May 2026 rates) Azure applies the same prices as the direct OpenAI API, but additionally charges for infrastructure and network. A 10-20% surcharge for the managed service should be expected. [cols="3,2,2,2,2"] |=== |Model |Input $/MTok |Output $/MTok |Cost/day |**Cost/month** |GPT 5.4 (Azure, Global) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 + infrastructure |15% surcharge |15% surcharge |$17.77 |**$533** |=== [NOTE] ==== The rates above concern the API, not "chat" subscriptions (Claude Pro at $20/month, ChatGPT Plus at $20/month). We are comparing *developer* usage here, where you chain hundreds of requests per day via API to generate, refactor, and document. Consumer subscriptions have quotas that are hit long before 500 requests/day. ==== === The final comparative table [cols="3,2,2,2,2,2"] |=== |Solution |Codebase Knowledge |Integrated Style |Cost/month |Iterations |**Effective Cost** |**My fleet (Ollama Pro)** |✅ Fine-tuned |✅ In the weights |**€17** |0-1 |**€17** |Claude Opus 4.7 |❌ Zero-shot |❌ Prompt required |$772 |2-3 |$1 500-2 300 |Claude Haiku 4.5 |❌ Zero-shot |❌ Prompt required |$154 |3-4 |$460-615 |GPT 5.5 |❌ Zero-shot |❌ Prompt required |$927 |2-3 |$1 854-2 781 |GPT 5.4 |❌ Zero-shot |❌ Prompt required |$463 |2-3 |$925-1 390 |GPT 5.4 Mini |❌ Zero-shot |❌ Prompt required |$139 |3-5 |$417-695 |Gemini 3.1 Pro High |❌ Zero-shot |❌ Prompt required |$540 |2-3 |$1 080-1 620 |Grok 4 |❌ Zero-shot |❌ Prompt required |$494 |2-3 |$988-1 482 |**Azure GPT 5.4** |❌ Zero-shot |❌ Prompt required |$533 |2-3 |$1 066-1 600 |=== [plantuml, cost-comparison, svg] ---- @startuml skinparam backgroundColor #FAFAFA title Rapport coût/efficacité — ma flotte vs le marché (mai 2026) rectangle "17€/mois" as OURS #4ECDC4 rectangle "Opus 4.7\n772€" as OPUS #FF6B6B rectangle "Sonnet 4.6\n463€" as SONNET #FF8B94 rectangle "GPT 5.5\n927€" as GPT #FFD93D rectangle "Gemini 3.1 Pro\n540€" as GEMINI #6C5CE7 rectangle "Grok 4\n494€" as GROK #A8E6CF rectangle "Haiku 4.5\n154€" as HAIKU #DFE6E9 rectangle "GPT 5.4 Mini\n139€" as MINI #B2BEC3 note bottom of OURS Avec fine-tune intégré. Zéro prompt engineering. 90%+ first-shot correct. end note @enduml ---- €17/month for 23 fine-tuned AI experts. The flagship Claude Opus 4.7 costs**45× more**for inferior quality on *my* codebase. GPT 5.5 costs**54× more**. Even the cheapest model on the market (Gemini Flash at €46) costs**2.7× more**without knowledge of my workspace. The verdict is final: fine-tuning on MoE architectures in 2026 is not just "cheaper." It is an efficiency factor of**27× to 54×**on the cost/quality ratio compared to proprietary solutions. Anthropic, OpenAI, Google — they all know it, and that's why they are lowering their prices in panic. == Efficiency factor: 5-8× vs using V4-Pro alone Let's compare the two extremes. === Scenario A: V4-Pro alone for everything [cols="3,2"] |=== |Metric |Value |Codebase Knowledge |0 (zero-shot) |Naming Convention |40-60% first-shot correct |Prompt Engineering Required |Yes, systematic |Iterations per task |2-3 |Inference Cost |$100/month (Ollama Max) |Average Latency |~20 tok/s + network |=== === Scenario B: Orchestrated MoE Fleet [cols="3,2"] |=== |Metric |Value |Codebase Knowledge |Integrated (fine-tune) |Naming Convention |90-95% first-shot correct |Prompt Engineering |No (style is in the weights) |Iterations per task |0-1 |Inference Cost |$60/month (3× Ollama Pro) |Average Latency |~50 tok/s (light models) |=== [cols="4,2,2,2"] |=== |Dimension |V4-Pro alone |MoE Fleet |Factor |Monthly cloud cost |$100 |**$60** |1.7× |Context to inject |High (prompt) |**Zero** |∞ |Average iterations |2-3 |**0-1** |2-3× |Perceived latency |20 tok/s |50 tok/s |**2.5×** |First-shot correct |50% |90%+ |**1.8×** |=== **Overall efficiency factor: 5-8×**— in perceived developer productivity. [NOTE] ==== The factor is not measured in tokens or dollars. It is measured in "how much time I spend explaining to the model what it should already know." With fine-tuned models, this time tends toward zero. ==== == The complete budget: a one-shot investment, a ridiculous flat rate [cols="3,2"] |=== |Item |Amount |Training GPU (811 H100-h, Crusoe $2/h) |**$1,622** |Synthetic dataset generation (LLM API) |**$400** |Inference (Ollama Pro annual, $17/month) |**$204** |**Total first year** |**$2,226** |**Monthly equivalent** |**$186** |**Estimated cost per request** |< $0.01 |=== [plantuml, budget-breakdown, svg] ---- @startuml skinparam backgroundColor #FAFAFA rectangle "Budget Année 1 : $2 226" as Total #E8E8E8 { rectangle "Training GPU\n$1 622 (73%)" as Train #FF6B6B rectangle "Dataset\ndistillation\n$400 (18%)" as Data #FFE66D rectangle "Ollama Pro\n$204 (9%)" as Cloud #4ECDC4 } 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 @enduml ---- $186/month the first year,**$17/month**starting year 2. The price of a premium Netflix subscription, for a team of 23 AI experts available 24/7, writing code *in my style* without me needing to explain my conventions. === Profitability calculation With edster.cloud and its margin of ~95%, the break-even point is at**~$2,340 in additional revenue**over the year. In practice: * 1 software steering mission → $3,000-5,000 → investment covered + profit * 1 corporate training → $5,000-10,000 → comfortable * Implicit upsell: "my AI team masters my software forge" → commercial differentiator From year 2, training is no longer paid (unless the dataset is updated). The annual cost drops to**$204**($17/month). The cost/value ratio is that of a unicorn: almost zero. == Limits of the exercise This remains a *rough estimate*. Several variables can shift the budget: [cols="2,3"] |=== |Variable |Impact |Synthetic dataset generation |If the distillation API fails (hallucinations, poorly formed pairs), human time is needed for curation. Hidden cost. |Ollama GPU-time Quotas |If usage exceeds Pro plan quotas, an upgrade or switch to dedicated GPU will be necessary. |Effective quality of fine-tunes |A failed fine-tune → must be redone. The real risk is hyperparameters, not GPU rental. |Rapid model evolution |Qwen3.6/Gemma 4 were released < 1 month ago. In 6 months, the next generation will be better AND cheaper to fine-tune. |=== [WARNING] ==== Do not launch 811 hours of training without first testing the pipeline on *a single* micro-model. A 3-4h run on a Qwen 35B-A3B costs $8. If the dataset is garbage, you'll know for $8, not for $1,622. ==== == Conclusion: fine-tuning has become an accessible luxury A year ago, fine-tuning a 292B parameter model (even in QLoRA) was a research project. Today, in May 2026, it's a feasible project for an independent developer: * **811 H100-hours**of training — $1,622 at Crusoe * **23 specialized models**loaded on Ollama Cloud —**$17/month** * **0 servers, 0 local GPUs, 0 infra maintenance** Democratization came from three convergent factors: 1. **MoE architectures**— which allow efficient fine-tuning of models where only a fraction of weights are activated 2. **Ollama Cloud flat plans**— which transform a variable cost (per-token) into a fixed cost (subscription) 3. **High-quality open-weight models**— DeepSeek V4, Qwen3.6, Gemma 4 are under MIT/Apache 2.0 licenses "Civilization advances by extending the number of important operations which we can perform without thinking about them." Fine-tuning is exactly that: an operation you delegate to the machine so you no longer have to think about it. And in 2026, it costs less than a salaried junior developer. --- _Article published on {jbake-date}_ == Fine-tuned models of the fleet [cols="2,2,2,2,3"] |=== |Activated size |Number |Base model |Domain |Dataset |13B |1 |DeepSeek-V4-Flash-Base |General workspace |50M tokens |13B |5 |DeepSeek-V4-Flash |Gradle, Kotlin, DAG, Doc, Infra |15M tokens |3.8B |6 |Gemma 4 26B-A4B |Micro-tasks, formatting, scripts |5M tokens |3B |5 |Qwen3.6-35B-A3B |Refactoring, review, intermediate doc |5M tokens |3B |5 |Qwen3.5-35B-A3B |Legacy tasks, compatibility |5M tokens |=== == Resources === Open-weight models on HuggingFace * https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Base[DeepSeek V4-Flash-Base — 292B params, MIT license] * https://huggingface.co/Qwen/Qwen3.6-35B-A3B[Qwen3.6-35B-A3B — 35B/3B activated, Apache 2.0 license] * https://huggingface.co/Qwen/Qwen3.5-35B-A3B[Qwen3.5-35B-A3B — 35B/3B activated, Apache 2.0 license] * https://huggingface.co/google/gemma-4-26B-A4B-it[Gemma 4 26B-A4B — 26B/3.8B activated, Apache 2.0 license] === Pricing sources (May 2026) * https://ollama.com/pricing[Ollama Cloud rates — Pro plan $17/month annual] * https://www.anthropic.com/pricing[Anthropic rates — Claude API (Opus 4.7 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5)] * https://openai.com/api/pricing/[OpenAI rates — GPT API (GPT 5.5 $5/$30, GPT 5.4 $2.50/$15)] * https://deepinfra.com/pricing[DeepInfra rates — GPU instances H100 $1.79/h, B200 $2.79/h] * Vast.ai, Crusoe Cloud, FluidStack, TensorDock, RunPod, CoreWeave, Lambda Labs — manual price checks, dated May 2026 === Official announcements * https://qwen.ai/blog?id=qwen3.6-35b-a3b[Official Qwen3.6-35B-A3B announcement — Qwen blog]— agentic coding, Apache 2.0, 262K context</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_why_gradle_for_infra">Why Gradle For Infra?</a></li> <li><a href="#_the_complete_build_gradle_kts">The Complete build.gradle.kts</a></li> <li><a href="#_anatomy_of_key_tasks">Anatomy of Key Tasks</a> <ul class="sectlevel2"> <li><a href="#_startollamab_the_launcher"><code>startOllamaB</code> — The Launcher</a></li> <li><a href="#_signinb_the_interactive"><code>signInB</code> — The Interactive</a></li> <li><a href="#_pullmodelb_the_parametric"><code>pullModelB</code> — The Parametric</a></li> <li><a href="#_statusollamaall_the_diagnostic"><code>statusOllamaAll</code> — The Diagnostic</a></li> <li><a href="#_cleanollamab_the_identity_preserving_cleanup"><code>cleanOllamaB</code> — The Identity-Preserving Cleanup</a></li> </ul> </li> <li><a href="#_complete_workflow_from_zero_to_two_sessions">Complete Workflow — From Zero to Two Sessions</a></li> <li><a href="#_why_not_make_it_a_real_gradle_plugin">Why Not Make It a Real Gradle Plugin?</a></li> <li><a href="#_lessons_learned">Lessons Learned</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_resources">Resources</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p>reading time: 18 minutes</p> </li> </ol> </div> <div class="paragraph"> <p>Why type docker commands by hand when you can encapsulate everything in Gradle tasks? Here is how I industrialized my dual-Ollama Pro config with zero external shell scripts. Start, stop, identity, sign-in, pull — everything goes through`./gradlew`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>In the previous article, I showed how to make two Ollama Pro accounts coexist on the same machine by isolating the second instance in a Docker container. The setup works, but daily management quickly becomes tedious: remembering the container name, relaunching the right commands`docker exec`, checking which port is active…​</p> </div> <div class="paragraph"> <p>You know that moment when you have 14 terminals open, you type`docker exec ollama-instance-b ollama list`for the fourth time, and you tell yourself "there must be a cleaner way" ?</p> </div> <div class="paragraph"> <p>That way is Gradle.</p> </div> <div class="paragraph"> <p>Not just for building code. Gradle as a local infrastructure orchestrator. Tasks that provision, verify, test, and clean. All versioned in a`build.gradle.kts`that lives next to the`docker-compose.yml`.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-gradle-ollama.svg" alt="architecture gradle ollama" width="717" height="511"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_gradle_for_infra">Why Gradle For Infra?</h2> <div class="sectionbody"> <div class="paragraph"> <p>The question is legitimate. Gradle is a build tool. Normally, it compiles, tests, packages. It doesn’t launch Docker containers.</p> </div> <div class="paragraph"> <p>Except that Gradle is also a dependency graph engine — and that’s where it becomes interesting for our case.</p> </div> <div class="paragraph"> <p>We want:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The container to be launched before a sign-in</p> </li> <li> <p>The identity to be verified before a model pull</p> </li> <li> <p>An API test to fail silently if the container is down</p> </li> </ol> </div> <div class="paragraph"> <p>Pure dependency graph. Gradle is built for this. The Kotlin DSL makes writing tasks fluid, and the`doLast`allows executing system commands as if they were application code.</p> </div> <div class="paragraph"> <p>And above all: no bashrc to maintain, no scripts lingering in`~/bin`, no Makefile next to the docker-compose. Everything lives in a single file, in the same place as the project code.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_complete_build_gradle_kts">The Complete build.gradle.kts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is the file I ended up writing. It does everything, from volume provisioning to the verification curl, including interactive sign-in.</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>There it is. Twelve tasks, a single entry point, and zero friction.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomy_of_key_tasks">Anatomy of Key Tasks</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_the_launcher"><code>startOllamaB</code> — The Launcher</h3> <div class="paragraph"> <p>Nothing magical: a`docker run -d`with the right parameters. The trick is in`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>If the container already exists, the`docker run`command fails (exit code ≠ 0). Without this property, Gradle would stop the entire build with an error. Here, the failure is silent — and the`doLast`detects if it was a "already exists" or a real error.</p> </div> <div class="paragraph"> <p>Le `doLast`is crucial: it runs <strong>after</strong> the command execution, which allows inspecting`executionResult.get().exitValue`and logging an appropriate message.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_the_interactive"><code>signInB</code> — The Interactive</h3> <div class="paragraph"> <p>This is the only task requiring human interaction. Gradle passes`System.in`to the process so that the`ollama signin`prompt can be displayed normally:</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>Without this, the sign-in would block because stdin would be closed and you would never see the prompt.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_the_parametric"><code>pullModelB</code> — The Parametric</h3> <div class="paragraph"> <p>A generic task that accepts a parameter 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>The fallback is important:`project.findProperty("model") as? String ?: "qwen3:0.6b"`ensures the task doesn’t crash if the parameter is forgotten.</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_the_diagnostic"><code>statusOllamaAll</code> — The Diagnostic</h3> <div class="paragraph"> <p>Two`curl`health checks on ports`11434` et <code>11435</code>, with a fallback in`runCatching`so it doesn’t crash if one of the instances is down. The output is structured:</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>One glance, and you know exactly what is running and what is wrong.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_the_identity_preserving_cleanup"><code>cleanOllamaB</code> — The Identity-Preserving Cleanup</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>The container is deleted, but the volume`~/ollama-b-data`is<strong>preserved</strong>. The SSH identity survives the cleanup. At the next`startOllamaB`, the same keys will be reused — no need to re-do the sign-in or re-register the 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`does not touch the volume. If you want to erase identity B (and start everything from scratch), you must delete</code>~/ollama-b-data`manually. This is intentional — a`clean`should not destroy credentials.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_complete_workflow_from_zero_to_two_sessions">Complete Workflow — From Zero to Two Sessions</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is the ideal sequence for someone arriving at the project who wants to set everything up without opening documentation:</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>Less than two minutes, everything is provisioned. No README to read, no environment variables to set. The`helpOllama`task serves as integrated documentation.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet-sequence.svg" alt="workflow complet sequence" width="757" height="1103"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_not_make_it_a_real_gradle_plugin">Why Not Make It a Real Gradle Plugin?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Legitimate question. Extracting this`build.gradle.kts`into a standalone Gradle plugin would have advantages: reuse across projects, declarative configuration, DSL extension.</p> </div> <div class="paragraph"> <p>But for now, it makes no sense. This build has no complex business logic — it’s a wrapper around Docker and curl commands. The overhead of a full Gradle plugin (with extensions, unit tests, publication) would be disproportionate for 12 utility tasks.</p> </div> <div class="paragraph"> <p>Le `build.gradle.kts`inline lives in the project that needs it. It is trivial to copy elsewhere. If one day I have three projects depending on it, I will transform it into a plugin. For now, 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>The day you have three`build.gradle.kts`identical in three projects, that’s the signal to extract a plugin. Before that, duplication is less costly than abstraction. Dev wisdom.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lessons_learned">Lessons Learned</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle is more than just a build tool</strong>— The dependency graph engine makes it a formidable infrastructure orchestrator.<code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code>: these three primitives are enough to drive a Docker container with the same reliability as a CI pipeline.</p> </li> <li> <p><strong><code>isIgnoreExitValue</code> is your friend</strong>— In an ideal world,<code>docker run`on an already existing container would return a warning rather than an error exit code. In the real world, you use`isIgnoreExitValue = true`and handle the diagnostic in`doLast</code>.</p> </li> <li> <p><strong>Parametric tasks kill ambiguity</strong> — Un <code>pullModelB`generic with</code>-Pmodel=…​`replaces N specialized tasks. One single task, one single doc, one single behavior.</p> </li> <li> <p><strong><code>runCatching</code> for health checks</strong>— When testing N endpoints, the crash of the first should not prevent testing the others.<code>runCatching</code>+`getOrElse`per endpoint, and the diagnostic remains complete even in case of partial failure.</p> </li> <li> <p><strong>The <code>helpOllama</code> task as executable documentation</strong> — Un `println()`well-formatted replaces a three-paragraph README. It’s self-documenting, always up-to-date, and accessible without leaving the terminal.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>We have moved from typing docker commands by hand to a complete, versioned, reusable Gradle workflow. Twelve tasks cover the entire lifecycle: provisioning, identity, sign-in, pull, test, diagnostic, cleanup.</p> </div> <div class="paragraph"> <p>The docker-compose + build.gradle.kts + opencode.json combo forms a clean trinity: Docker for isolation, Gradle for orchestration, OpenCode for consumption. Each layer has its responsibility, and none overflow into the other.</p> </div> <div class="paragraph"> <p>Next step? Automating the lifecycle in CI so that Ollama instances are available in ephemeral dev environments. But that’s another article.</p> </div> </div> </div> <div class="sect1"> <h2 id="_resources">Resources</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/tutorial_using_tasks.html">Gradle User Manual — Tasks</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">Gradle User Manual — Custom Tasks</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Ollama Docker Image on Docker Hub</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle Kotlin DSL — Documentation</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Article published on 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_why_twice_the_same_thing">Why Twice the Same Thing?</a></li> <li><a href="#_the_heart_of_the_problem_the_device_key">The Heart of the Problem: The Device Key</a></li> <li><a href="#_setup_step_by_step">Setup — Step by Step</a> <ul class="sectlevel2"> <li><a href="#_prerequisites">Prerequisites</a></li> <li><a href="#_step_1_create_the_volume">Step 1: Create the Volume</a></li> <li><a href="#_step_2_run_the_docker_container">Step 2: Run the Docker Container</a></li> <li><a href="#_step_3_retrieve_the_public_key">Step 3: Retrieve the Public Key</a></li> <li><a href="#_step_4_register_the_key_on_ollama_com">Step 4: Register the Key on Ollama.com</a></li> <li><a href="#_step_5_test_with_a_small_free_model">Step 5: Test with a Small Free Model</a></li> </ul> </li> <li><a href="#_the_v1models_api_trap">The <code>/v1/models</code> API Trap</a></li> <li><a href="#_result_two_sessions_two_accounts_zero_conflict">Result: Two Sessions, Two Accounts, Zero Conflict</a></li> <li><a href="#_lessons_learned">Lessons Learned</a></li> <li><a href="#_to_go_further">To Go Further</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 14 minutes</div> <p>Two Pro subscriptions, one machine, one credit card, and zero network conflicts. How Docker allowed me to double my cloud inference capacity without buying a second PC.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>I have been using Ollama Pro for several months to power my OpenCode sessions with cloud models. The thing is, even with a Pro subscription, you quickly hit <strong>rate limiting</strong> when running several agents in parallel. The obvious solution: a second subscription.</p> </div> <div class="paragraph"> <p>But here is the drama.</p> </div> <div class="paragraph"> <p>Ollama identifies each machine by a unique SSH key — its famous <strong>Device Key</strong>. Two instances on the same OS would share the same identity, and it is impossible to link two Pro accounts to the same device. And as you might guess, I wasn’t going to buy a second laptop just for that.</p> </div> <div class="paragraph"> <p>The solution: cheat. Make Ollama believe it is running on two different machines, even though they share the same CPU, the same RAM, and the same network connection. Docker will provide us with a perfect isolation bubble.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-dual-ollama.svg" alt="architecture dual ollama" width="509" height="420"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_twice_the_same_thing">Why Twice the Same Thing?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before you call me a lunatic, let me explain the use case.</p> </div> <div class="paragraph"> <p>With a single Pro subscription, I can run a model like`deepseek-v4-pro:cloud`in an OpenCode session. The problem arises when I want <strong>two</strong> simultaneous sessions. Rate limiting quotas mean the second session lags or is simply rejected.</p> </div> <div class="paragraph"> <p>With two independent Pro subscriptions:</p> </div> <div class="ulist"> <ul> <li> <p>OpenCode Session 1 → Pro Account A (<code>localhost:11434</code>)</p> </li> <li> <p>OpenCode Session 2 → Pro Account B (<code>localhost:11435</code>)</p> </li> </ul> </div> <div class="paragraph"> <p>Each session has its own quota, its own context, and does not interfere with the other. It is human multi-processing.</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>Two Pro subscriptions = two different emails. The same credit card works — the Ollama payment system does not block multiple subscriptions from the same payment method. I’ve checked.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_the_heart_of_the_problem_the_device_key">The Heart of the Problem: The Device Key</h2> <div class="sectionbody"> <div class="paragraph"> <p>When you install Ollama, a pair of ed25519 SSH keys is generated in the identity directory:</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>This key is uploaded to Ollama’s servers during the`ollama signin`. This is what says "this machine belongs to such-and-such Pro account." If your two instances share the same`id_ed25519`file, they share the same identity. Game over.</p> </div> <div class="paragraph"> <p>The workaround: give our second instance its own identity directory, isolated in a Docker volume.</p> </div> </div> </div> <div class="sect1"> <h2 id="_setup_step_by_step">Setup — Step by Step</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prerequisites">Prerequisites</h3> <div class="ulist"> <ul> <li> <p>A functional native Ollama installation (official script`curl | sh`)</p> </li> <li> <p>Docker installed and functional</p> </li> <li> <p>Portainer or docker-compose for deployment</p> </li> <li> <p>Two Ollama accounts with two distinct emails</p> </li> </ul> </div> <div class="paragraph"> <p>I used version`0.20.2`— the one provided by the official script and the corresponding Docker image.</p> </div> </div> <div class="sect2"> <h3 id="_step_1_create_the_volume">Step 1: Create the Volume</h3> <div class="paragraph"> <p>A simple directory on the host will serve as a persistent volume for instance B’s identity:</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>This folder will be mounted in the Docker container as`/root/.ollama`, where Ollama stores its identity keys, history, and models.</p> </div> </div> <div class="sect2"> <h3 id="_step_2_run_the_docker_container">Step 2: Run the Docker Container</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>What is happening here:</p> </div> <div class="ulist"> <ul> <li> <p>Host port<strong>11435</strong>is mapped to the container’s internal<strong>11434</strong>. Thus, the Docker instance listens on`:11435`without conflict with the native instance occupying`:11434`.</p> </li> <li> <p>Volume`~/ollama-b-data`is mounted on`/root/.ollama`— this is where the SSH identity will be stored.</p> </li> <li> <p>`OLLAMA_HOST=0.0.0.0`allows the container to accept external connections.</p> </li> </ul> </div> <div class="paragraph"> <p>I deployed this stack via Portainer, but a simple`docker compose up -d`works just as well.</p> </div> </div> <div class="sect2"> <h3 id="_step_3_retrieve_the_public_key">Step 3: Retrieve the Public Key</h3> <div class="paragraph"> <p>Since the container is blank on the first start, Ollama automatically generates a new SSH key pair in the volume. We retrieve the public key:</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>I verify that this key is <strong>different</strong> from the one in the native instance:</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>Two distinct keys, two separate identities. Done.</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>If your container restarts, it <strong>reuses</strong> the keys present in the volume. The identity is persistent. You will not lose the association with the Pro account.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_step_4_register_the_key_on_ollama_com">Step 4: Register the Key on Ollama.com</h3> <div class="paragraph"> <p>Head to <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → Add SSH Key. Paste the public key from the Docker instance and validate.</p> </div> <div class="paragraph"> <p>Then, link this identity to Pro account 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>The browser opens, we log in with the email of account B, and the token is associated with the container’s SSH key. We verify that everything is 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="_step_5_test_with_a_small_free_model">Step 5: Test with a Small Free Model</h3> <div class="paragraph"> <p>Before spending the price of a Pro subscription, I want to be sure the pipe is working. I pull a small local free model to validate connectivity:</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>Port`11435`responds, the model is served. Instance B is alive.</p> </div> <div class="paragraph"> <p>Once reassured, I move to pulling the actual Pro cloud model:</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 for a cloud model manifest — normal, the inference happens server-side, not locally. And here is the ultimate test:</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>Hello to you too, instance B.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_v1models_api_trap">The <code>/v1/models</code> API Trap</h2> <div class="sectionbody"> <div class="paragraph"> <p>I lost 20 minutes on a silly detail. When I configured the`ollama-b`provider in OpenCode, nothing appeared in the model selector. Nothing. Zip.</p> </div> <div class="paragraph"> <p>The reason? The`/v1/models`API of instance B returned`{"object":"list","data":null}`instead of`{"object":"list","data":[]}`when no model was pulled. The`null`value crashed the parsing on the OpenCode side, which failed to display the provider.</p> </div> <div class="paragraph"> <p>The solution: declare the models <strong>explicitly</strong> in the OpenCode configuration rather than relying on dynamic discovery.</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>With this explicit declaration, OpenCode immediately sees provider B and its models. One session restart, and the`/models`selector shows both instances side by side.</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>If you don’t see your custom provider in`/models`, don’t waste three hours restarting your terminal. Declare the models manually in`opencode.json`— it fixes the problem instantly.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_result_two_sessions_two_accounts_zero_conflict">Result: Two Sessions, Two Accounts, Zero Conflict</h2> <div class="sectionbody"> <div class="paragraph"> <p>In the end, I can run two OpenCode sessions simultaneously:</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>Each session has its own quota, its own rate limit, and they don’t step on each other’s toes. Same machine, same credit card, two different emails.</p> </div> <div class="paragraph"> <p>And the best part? The Docker container is in`restart: always`. It survives system reboots without manual intervention.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lessons_learned">Lessons Learned</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker isolates everything, even identity</strong>— A simple volume bind mount is enough to give a container its own set of SSH keys, making it indistinguishable from a different physical machine in the eyes of Ollama.</p> </li> <li> <p><strong>Two emails, same CC</strong>— Ollama does not block multiple subscriptions from the same payment method. Only the email must be distinct.</p> </li> <li> <p><strong>Test for free before paying</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><code>/v1/models</code> with <code>data: null</code> breaks OpenCode</strong>— If you configure a custom provider with`"models": {}`, OpenCode attempts to discover models via the API. If the API responds`data: null`, the provider does not appear. Declare models explicitly.</p> </li> <li> <p><strong>Two accounts is human multi-processing</strong>— One Pro account = one active OpenCode session. Two accounts = two parallel sessions. For someone juggling several Gradle projects simultaneously, it’s a game changer.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_to_go_further">To Go Further</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Ollama Settings — SSH Key Management</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Official Ollama Documentation</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Ollama Docker Image on Docker Hub</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Ollama Provider Configuration</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Article published on 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/en/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="#_why_choose_kitty_and_zsh">Why choose Kitty and Zsh?</a></li> <li><a href="#_system_prerequisites">System Prerequisites</a></li> <li><a href="#_downloading_and_installing_kitty">Downloading and Installing Kitty</a> <ul class="sectlevel2"> <li><a href="#_download_the_installation_script">Download the installation script</a></li> <li><a href="#_creating_symbolic_links">Creating Symbolic Links</a></li> </ul> </li> <li><a href="#_integrating_kitty_into_xubuntu">Integrating Kitty into Xubuntu</a> <ul class="sectlevel2"> <li><a href="#_copy_the_desktop_file">Copy the desktop file</a></li> <li><a href="#_modify_the_desktop_file">Modify the desktop file</a></li> <li><a href="#_set_kitty_as_the_default_terminal_optional">Set Kitty as the default terminal (optional)</a></li> </ul> </li> <li><a href="#_installing_zsh">Installing Zsh</a></li> <li><a href="#_set_zsh_as_the_default_shell">Set Zsh as the default shell</a> <ul class="sectlevel2"> <li><a href="#_global_method_for_all_terminals">Global Method (for all terminals)</a></li> <li><a href="#_kitty_specific_method">Kitty-specific Method</a></li> </ul> </li> <li><a href="#_zsh_configuration_optional">Zsh Configuration (optional)</a> <ul class="sectlevel2"> <li><a href="#_create_a_zshrc_file">Create a .zshrc file</a></li> <li><a href="#_example_of_a_minimal_configuration">Example of a minimal configuration</a></li> </ul> </li> <li><a href="#_complete_workflow_summary">Complete Workflow Summary</a></li> <li><a href="#_final_verification">Final Verification</a> <ul class="sectlevel2"> <li><a href="#_open_the_configuration_file">📂 Open the configuration file</a></li> <li><a href="#_️_add_or_modify_font_size">🖋️ Add or modify <code>font_size</code></a></li> <li><a href="#_save_and_relaunch_kitty">💾 Save and relaunch Kitty</a></li> <li><a href="#_dynamic_adjustment_temporary_zoom">✅ Dynamic Adjustment (Temporary Zoom)</a></li> </ul> </li> <li><a href="#_installation_and_configuration_of_oh_my_zsh">Installation and Configuration of Oh My Zsh</a> <ul class="sectlevel2"> <li><a href="#_installing_oh_my_zsh">Installing Oh My Zsh</a></li> <li><a href="#_changing_the_theme">Changing the Theme</a></li> <li><a href="#_verification">Verification</a></li> <li><a href="#_use_case_diagram">Use case diagram</a></li> </ul> </li> <li><a href="#_enabling_translucency_in_kitty">Enabling Translucency in Kitty</a> <ul class="sectlevel2"> <li><a href="#_prerequisites_for_transparency">Prerequisites for Transparency</a></li> <li><a href="#_configuring_transparency_in_kitty_conf">Configuring Transparency in kitty.conf</a></li> <li><a href="#_restart_kitty">Restart Kitty</a></li> <li><a href="#_possible_additions">Possible Additions</a></li> <li><a href="#_sequence_diagram_kitty_initialization_with_transparency">Sequence Diagram - Kitty Initialization with Transparency</a></li> <li><a href="#_known_limitations">Known Limitations</a></li> </ul> </li> <li><a href="#_disabling_the_audible_bell">Disabling the Audible Bell</a></li> <li><a href="#_updating_kitty">Updating Kitty</a></li> <li><a href="#_references">References</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>This guide explains step-by-step how to install the <strong>kitty</strong> terminal on Xubuntu, configure it correctly, and replace bash with <strong>zsh</strong> as the default shell. The kitty project is available here: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a>.</p> </div> <div class="paragraph"> <p><em><em>_ Kitty is a modern, fast, and configurable terminal, particularly suited for demanding developers. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_why_choose_kitty_and_zsh">Why choose Kitty and Zsh?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty stands out due to:</p> </div> <div class="ulist"> <ul> <li> <p>Superior performance thanks to GPU acceleration,</p> </li> <li> <p>A configuration entirely based on a single text file,</p> </li> <li> <p>Excellent support for fonts and ligatures.</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh, for its part, is a powerful interactive shell offering:</p> </div> <div class="ulist"> <ul> <li> <p>Intelligent completion,</p> </li> <li> <p>A customizable prompt,</p> </li> <li> <p>High compatibility with bash.</p> </li> </ul> </div> <div class="paragraph"> <p>By combining Kitty and Zsh, you benefit from a productive and aesthetic environment.</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>This guide is intentionally limited to installation via script and to Xubuntu.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_system_prerequisites">System Prerequisites</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before starting, ensure you have:</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu installed,</p> </li> <li> <p>internet access,</p> </li> <li> <p>a functional bash shell to run the script.</p> </li> </ul> </div> <div class="paragraph"> <p>Check your environment:</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="_downloading_and_installing_kitty">Downloading and Installing Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty recommends installing it via an official script that places the files in`~/.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>This method is independent of package managers (no`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_download_the_installation_script">Download the installation script</h3> <div class="paragraph"> <p>Run the following command:</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>This command performs:</p> </div> <div class="ulist"> <ul> <li> <p>binary download,</p> </li> <li> <p>extraction into`~/.local/kitty.app`,</p> </li> <li> <p>creation of symbolic links.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/download-install.svg" alt="download install" width="353" height="336"> </div> </div> </div> <div class="sect2"> <h3 id="_creating_symbolic_links">Creating Symbolic Links</h3> <div class="paragraph"> <p>In order to be able to invoke`kitty`from the terminal, create a symbolic link:</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>Add`~/.local/bin`to your PATH if not already done:</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>You can verify the installation:</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="_integrating_kitty_into_xubuntu">Integrating Kitty into Xubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>For Kitty to appear in the applications menu:</p> </div> <div class="sect2"> <h3 id="_copy_the_desktop_file">Copy the desktop file</h3> <div class="paragraph"> <p>Copy the provided`.desktop`file:</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="_modify_the_desktop_file">Modify the desktop file</h3> <div class="paragraph"> <p>Edit the file:</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>Check or modify the following lines:</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>Replace`YOURUSER`with your username.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/desktop-integration.png" alt="desktop integration" width="479" height="335"> </div> </div> </div> <div class="sect2"> <h3 id="_set_kitty_as_the_default_terminal_optional">Set Kitty as the default terminal (optional)</h3> <div class="paragraph"> <p>To make Kitty the default terminal launched:</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>Select`kitty`in the proposed menu.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_installing_zsh">Installing Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>If Zsh is not yet installed, run:</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>Verify the installation:</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="_set_zsh_as_the_default_shell">Set Zsh as the default shell</h2> <div class="sectionbody"> <div class="paragraph"> <p>You can change your shell globally or only within Kitty.</p> </div> <div class="sect2"> <h3 id="_global_method_for_all_terminals">Global Method (for all terminals)</h3> <div class="paragraph"> <p>Identify the absolute path:</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>Generally`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>Modify the default shell:</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>Log out and log back in.</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="_kitty_specific_method">Kitty-specific Method</h3> <div class="paragraph"> <p>If you prefer to only change the shell in Kitty, edit the configuration file:</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>Add this line:</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>Save and restart Kitty.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh_configuration_optional">Zsh Configuration (optional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>To customize your Zsh:</p> </div> <div class="sect2"> <h3 id="_create_a_zshrc_file">Create a .zshrc file</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="_example_of_a_minimal_configuration">Example of a minimal configuration</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="_complete_workflow_summary">Complete Workflow Summary</h2> <div class="sectionbody"> <div class="paragraph"> <p>The diagram below summarizes the entire process:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/full-workflow.png" alt="full workflow" width="357" height="643"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_final_verification">Final Verification</h2> <div class="sectionbody"> <div class="paragraph"> <p>Launch 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>You should see that`zsh`is active:</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>Expected result:</p> </div> <div class="paragraph"> <p>/usr/bin/zsh</p> </div> <div class="paragraph"> <p>To change the font size in<strong>Kitty</strong>, you must adjust the`font_size`parameter in the configuration file. Here is the detailed procedure:</p> </div> <div class="sect2"> <h3 id="_open_the_configuration_file">📂 Open the configuration file</h3> <div class="paragraph"> <p>The main configuration file is usually located in:</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>If this file does not exist yet, you can create it. Example:</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="_️_add_or_modify_font_size">🖋️ Add or modify <code>font_size</code></h3> <div class="paragraph"> <p>Add the following directive, or modify it if it already exists:</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>Here`14.0`corresponds to the desired size. You can use any decimal value, for example`12.0`, <code>15.5</code>, etc.</p> </div> </div> <div class="sect2"> <h3 id="_save_and_relaunch_kitty">💾 Save and relaunch Kitty</h3> <div class="ulist"> <ul> <li> <p>Save (<code>Ctrl + O</code>, then`Entrée`) and quit (<code>Ctrl + X</code>) if you are using`nano`.</p> </li> <li> <p>Close all Kitty windows, then relaunch the terminal for the change to take effect.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_dynamic_adjustment_temporary_zoom">✅ Dynamic Adjustment (Temporary Zoom)</h3> <div class="paragraph"> <p>If you wish to zoom in/out temporarily without modifying the configuration, use the default keyboard shortcuts:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Increase font size</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Decrease font size</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Reset size</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>These settings do not persist after closing the terminal.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_installation_and_configuration_of_oh_my_zsh">Installation and Configuration of Oh My Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Once Zsh is installed and configured as the default shell, you can enrich your environment with <strong>Oh My Zsh</strong>, a Zsh configuration management framework, offering:</p> </div> <div class="ulist"> <ul> <li> <p>a collection of themes for the prompt,</p> </li> <li> <p>numerous plugins,</p> </li> <li> <p>a clear organization of the configuration.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_installing_oh_my_zsh">Installing Oh My Zsh</h3> <div class="paragraph"> <p>Ensure that Zsh is active:</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>If necessary, run:</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>Then download and run the official installation script:</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>This script:</p> </div> <div class="ulist"> <ul> <li> <p>creates the`~/.oh-my-zsh`,</p> </li> <li> <p>folder, optionally backs up your`~/.zshrc`,</p> </li> <li> <p>file, and automatically activates the new prompt.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_changing_the_theme">Changing the Theme</h3> <div class="paragraph"> <p>Open your configuration file:</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>Modify the`ZSH_THEME`variable to choose another theme (for example`agnoster`):</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster"</p> </div> <div class="paragraph"> <p>Save and then reload the configuration:</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="_verification">Verification</h3> <div class="paragraph"> <p>Launch Kitty and verify that the prompt has indeed changed. You can confirm that Oh My Zsh is active by running:</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>The result should be similar to:</p> </div> <div class="paragraph"> <p>/home/your_user/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_use_case_diagram">Use case diagram</h3> <div class="imageblock"> <div class="content"> <img src="./images/ohmyzsh-installation.png" alt="ohmyzsh installation" width="532" height="480"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_enabling_translucency_in_kitty">Enabling Translucency in Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>One of the most appreciated features of Kitty is the ability to add <strong>transparency</strong> to the terminal background. This allows you to slightly see the underlying environment (window, desktop, etc.), which is particularly useful for multitasking.</p> </div> <div class="sect2"> <h3 id="_prerequisites_for_transparency">Prerequisites for Transparency</h3> <div class="paragraph"> <p>Transparency in Kitty relies on the<strong>window compositor</strong>used by the graphical environment. Under Xubuntu (based on XFCE), ensure that<strong>composition is enabled</strong>.</p> </div> <div class="ulist"> <div class="title">To check:</div> <ul> <li> <p>right-click on the desktop > Settings ><strong>Window Manager Tweaks</strong>,</p> </li> <li> <p>tab<strong>Compositor</strong>: the <strong>"Enable display compositing"</strong> box must be checked.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/transparency-usecase.png" alt="transparency usecase" width="683" height="228"> </div> </div> </div> <div class="sect2"> <h3 id="_configuring_transparency_in_kitty_conf">Configuring Transparency in kitty.conf</h3> <div class="paragraph"> <p>Open your configuration file`~/.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>Add or modify the following lines:</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>This parameter accepts values between:</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ opaque (no transparency),</p> </li> <li> <p><code>0.0</code>→ completely transparent (unusable),</p> </li> <li> <p>intermediate values such as`0.90`, <code>0.75</code>, etc.</p> </li> </ul> </div> <div class="paragraph"> <p>A good visual compromise is generally between`0.85` et <code>0.95</code>.</p> </div> </div> <div class="sect2"> <h3 id="_restart_kitty">Restart Kitty</h3> <div class="paragraph"> <p>Close all Kitty instances, then launch a new window for the changes to take effect:</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="_possible_additions">Possible Additions</h3> <div class="paragraph"> <p>If you use a custom terminal background, you can also define a background color with transparency (in 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>The last component (<code>ff</code>) indicates the opacity (from`00` à <code>ff</code>).</p> </div> </div> <div class="sect2"> <h3 id="_sequence_diagram_kitty_initialization_with_transparency">Sequence Diagram - Kitty Initialization with Transparency</h3> <div class="imageblock"> <div class="content"> <img src="./images/transparency-sequence.png" alt="transparency sequence" width="775" height="422"> </div> </div> </div> <div class="sect2"> <h3 id="_known_limitations">Known Limitations</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>Translucency does not work if: - the XFCE compositor is disabled, - an incompatible window manager is used, - you are using Kitty in a <strong>tmux</strong> background mode without transparency support.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_disabling_the_audible_bell">Disabling the Audible Bell</h2> <div class="sectionbody"> <div class="paragraph"> <p>By default, Kitty emits a <strong>beep</strong> sound when an erroneous command is entered or when a terminal event triggers it. This noise can quickly become annoying, especially in an intensive development environment.</p> </div> <div class="paragraph"> <p>To disable this behavior, add the following directive to the`~/.config/kitty/kitty.conf`file:</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>You can also enable a <strong>visual bell</strong> as a replacement for the audible beep with:</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="_updating_kitty">Updating Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Since Kitty is installed via a script and not a package manager, the update is done by relaunching the official installation script. This allows downloading the latest version and updating your existing installation in`~/.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>The`.app`suffix in the`~/.local/kitty.app`path is the Kitty installation convention on Linux via its official script, and in no way indicates exclusive compatibility with 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>Before running the update command, ensure you are in your home directory (<code>~</code>).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Execute the following command from your home directory:</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>This script will:</p> </div> <div class="ulist"> <ul> <li> <p>Download the binaries of the new version.</p> </li> <li> <p>Extract the files into`~/.local/kitty.app`.</p> </li> <li> <p>Update symbolic links if necessary.</p> </li> </ul> </div> <div class="paragraph"> <p>After the update, it is recommended to close all Kitty instances and relaunch them to ensure that the new version is properly taken into account.</p> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="paragraph"> <p>If you wish to deepen your customization, consult the official documentation:</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>You now have:</p> </div> <div class="ulist"> <ul> <li> <p>a modern and high-performance terminal (Kitty)</p> </li> <li> <p>a powerful and customizable shell (Zsh)</p> </li> <li> <p>a clean configuration independent of system packages</p> </li> <li> <p>an aesthetic and functional terminal equipped with Oh My Zsh</p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_the_context_a_market_that_has_shifted">The Context: A Market That Has Shifted</a></li> <li><a href="#_the_options_panel">The Options Panel</a> <ul class="sectlevel2"> <li><a href="#_what_i_excluded_and_why">What I Excluded (and Why)</a></li> </ul> </li> <li><a href="#_simple_inference_the_death_of_local_hardware">Simple Inference: The Death of Local Hardware</a> <ul class="sectlevel2"> <li><a href="#_the_calculation">The Calculation</a></li> <li><a href="#_even_with_intensive_use">Even With Intensive Use</a></li> </ul> </li> <li><a href="#_fine_tuning_the_cloud_is_unbeatable">Fine-Tuning: The Cloud Is Unbeatable</a> <ul class="sectlevel2"> <li><a href="#_the_real_cost_of_a_fine_tune">The Real Cost of a Fine-Tune</a></li> <li><a href="#_specialized_players">Specialized Players</a></li> </ul> </li> <li><a href="#_the_only_real_reason_data_sovereignty">The Only Real Reason: Data Sovereignty</a> <ul class="sectlevel2"> <li><a href="#_the_real_calculation_of_confidentiality">The Real Calculation of Confidentiality</a></li> </ul> </li> <li><a href="#_synthesis_the_decision_matrix">Synthesis: The Decision Matrix</a></li> <li><a href="#_the_special_case_pro_subscription_vs_chinese_models">The Special Case: Pro Subscription vs. Chinese Models</a> <ul class="sectlevel2"> <li><a href="#_why_chinese_models_change_everything">Why Chinese Models Change Everything</a></li> <li><a href="#_what_this_means_for_hardware">What This Means for Hardware</a></li> </ul> </li> <li><a href="#_and_huawei">And Huawei?</a></li> <li><a href="#_conclusion_the_luxury_of_proximity">Conclusion: The Luxury of Proximity</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 14 minutes</div> <p>NVIDIA sells the DGX Spark as a "desktop AI supercomputer" for $4,699. Ollama offers its cloud models at $20/month. An H100 rents for $1.38/h at Vast.ai. And Chinese open-source models — DeepSeek, Qwen, GLM — are available everywhere, for free, without having to buy a card. So, what exactly is this Spark for? I did the math.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_context_a_market_that_has_shifted">The Context: A Market That Has Shifted</h2> <div class="sectionbody"> <div class="paragraph"> <p>In May 2026, the AI landscape has radically changed compared to the DGX Spark announcement at CES 2025. Three forces converged to make local hardware increasingly difficult to justify:</p> </div> <div class="ulist"> <ul> <li> <p><strong>The collapse of cloud GPU prices</strong>: an H100 rents for between $1.38 and $3/h, compared to $5-8/h 18 months ago</p> </li> <li> <p><strong>The explosion of Chinese open-source models</strong>: DeepSeek-V4, Qwen-3, GLM-5 are competitive with Western models and available for free</p> </li> <li> <p><strong>The rise of managed inference platforms</strong>: Ollama, Groq, Together AI offer APIs at aggressive rates, with generous free tiers</p> </li> </ul> </div> <div class="paragraph"> <p>The DGX Spark, announced at $2,999 and then raised to $4,699, arrives in a world that no longer needs it.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_options_panel">The Options Panel</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here are the solutions available in May 2026 for running LLMs, from the lightest to the heaviest:</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">Option</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cost</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / Capacity</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Accessible Models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Main Constraint</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Free</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/month</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Light cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All public models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Limited usage, 1 simultaneous model</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/month (~$240/year)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (Closed API)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude 4.x only</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Single model, no 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/month (~$200/year)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Medium cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All public models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 simultaneous models max</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/month (~$1,200/year)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Heavy cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All public models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">10 simultaneous models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cloud GPU (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">All models, fine-tuning</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Hourly billing, setup required</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 (purchase)</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">Slow (~10x slower than H100), fixed</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mac Studio M3 Ultra</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~$5 000+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">192 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <192 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No CUDA, MLX ecosystem</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>The cloud GPU prices mentioned are those of Vast.ai and RunPod in May 2026 — spot/on-demand, not reserved. Hyperscaler prices (AWS, GCP, Azure) remain 2-3x higher.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_what_i_excluded_and_why">What I Excluded (and Why)</h3> <div class="paragraph"> <p>I deliberately excluded the following options from this benchmark:</p> </div> <div class="ulist"> <ul> <li> <p><strong>OpenAI / Anthropic / Google APIs</strong>: the subject here is running <strong>open-source</strong> models that we can choose, fine-tune, and not be dependent on a single vendor</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="_simple_inference_the_death_of_local_hardware">Simple Inference: The Death of Local Hardware</h2> <div class="sectionbody"> <div class="paragraph"> <p>Let’s start with the most common use case: chatting with an LLM, doing code review, generating text. No fine-tuning, no batch processing, just interactive inference.</p> </div> <div class="sect2"> <h3 id="_the_calculation">The Calculation</h3> <div class="paragraph"> <p>A DGX Spark at $4,699. Let’s divide by the annual cost of each subscription:</p> </div> <div id="diag-breakeven" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-7447dcff18600cfcdb05c5212204ea1f.svg" alt="Seuil de rentabilité du DGX Spark vs abonnements" width="837" height="219"> </div> </div> <div class="paragraph"> <p>The verdict is brutal. For inference:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>: it would take you<strong>23 years</strong>to break even on a DGX Spark. The Spark will have been obsolete for 20 years.</p> </li> <li> <p><strong>Ollama Max</strong>:<strong>4 years</strong>— provided you use the Spark 24/7, which no one does</p> </li> <li> <p><strong>Claude Pro</strong>: same problem,<strong>20 years</strong>for a closed single-model</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ The promise of the "desktop AI supercomputer" hits a basic accounting reality: $4,699 / $20 per month = never profitable for individual use. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_even_with_intensive_use">Even With Intensive Use</h3> <div class="paragraph"> <p>Let’s take the worst-case scenario for the cloud: you run an H100 8h/day, 5 days/week, 52 weeks/year.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2,080 hours/year</p> </li> <li> <p>2,080 × $2/h (average H100 spot price) =<strong>$4,160/year</strong></p> </li> </ul> </div> <div class="paragraph"> <p>The Spark ($4,699) is paid off in<strong>13 months</strong>. Except that:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The H100 is<strong>~10x faster</strong>than the Spark’s GB10. You do in 1h what the Spark does in 10h. For the same volume of work, the H100 costs you $416/year, not $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>Comparing 1h of H100 to 1h of Spark makes no sense. The H100 does the work 10x faster. The true cloud cost for a given workload is therefore ~10x lower than the naive calculation based on hours.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fine_tuning_the_cloud_is_unbeatable">Fine-Tuning: The Cloud Is Unbeatable</h2> <div class="sectionbody"> <div class="paragraph"> <p>The classic argument from Spark defenders: "yes, but for fine-tuning, it’s different."</p> </div> <div class="paragraph"> <p>No, it isn’t.</p> </div> <div class="sect2"> <h3 id="_the_real_cost_of_a_fine_tune">The Real Cost of a Fine-Tune</h3> <div class="paragraph"> <p>A LoRA/QLoRA fine-tune on Unsloth of a 7B model:</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h on an H100 =<strong>$5 to $9</strong></p> </li> <li> <p>Same thing on the Spark =<strong>20-30h</strong>(10x slower), locks the machine</p> </li> </ul> </div> <div class="paragraph"> <p>With the $4,699 for the Spark, you can fund:</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500 to ~900 fine-tunes</strong>in H100 cloud</p> </li> <li> <p>Ou <strong>~23 years</strong>of Ollama Pro</p> </li> <li> <p>Ou <strong>~4 years</strong>of Ollama Max</p> </li> </ul> </div> <div class="paragraph"> <p>And for larger models (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>For full fine-tuning, you need multi-GPU anyway — the Spark is out of the race</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_specialized_players">Specialized Players</h3> <div class="paragraph"> <p>In 2026, platforms like Unsloth, Modal, Replicate, and Together AI offer serverless fine-tuning:</p> </div> <div class="ulist"> <ul> <li> <p>No GPU management</p> </li> <li> <p>No environment configuration</p> </li> <li> <p>Payment by the minute</p> </li> <li> <p>Built-in optimizations (flash attention, automatic quantization)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-00c27fa5b17d5b1836d28ea44e7aa323.svg" alt="Comparaison des coûts de fine-tuning" width="626" height="244"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_only_real_reason_data_sovereignty">The Only Real Reason: Data Sovereignty</h2> <div class="sectionbody"> <div class="paragraph"> <p>After eliminating inference, fine-tuning, and the value-for-money ratio — what’s left for the Spark?</p> </div> <div class="paragraph"> <p><strong>Absolute confidentiality.</strong></p> </div> <div class="paragraph"> <p>Not "I don’t want my prompts read by an OpenAI employee" confidentiality. That’s a non-issue in 2026: Ollama, Groq, and most respectable providers have zero-log and zero-retention policies.</p> </div> <div class="paragraph"> <p>True confidentiality is:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Regulatory air-gap</strong>: defense, diplomacy, health — data <strong>physically</strong> cannot leave the building</p> </li> <li> <p><strong>Critical proprietary data</strong>: source code of an unreleased product, industrial secrets, trading algorithms</p> </li> <li> <p><strong>Network resilience</strong>: AI must continue to function even if the Internet goes down</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>But let’s be honest: what percentage of DGX Spark buyers are actually in this situation? 1%? The rest is "nice to have" transformed into a $4,699 expense.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_the_real_calculation_of_confidentiality">The Real Calculation of Confidentiality</h3> <div class="paragraph"> <p>For individual use:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>($20/month) + Chinese open-source models = pragmatic solution</p> </li> <li> <p>If a prompt leaks at Ollama, it’s drowned in millions of daily requests. It’s a drop in the ocean.</p> </li> <li> <p>The real risk is not a prompt leak — it’s non-consensual training on your data. And serious providers prohibit that contractually.</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ The fear of "distilling one’s prompt into the LLM" is a level of personal information propagation so diluted that it’s more about anxiety than a real threat. At an industrial scale, it’s different. But at an individual scale, it’s noise. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_synthesis_the_decision_matrix">Synthesis: The Decision Matrix</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-06638fe7c7dbec3c1cf02043ac672e9a.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">Criterion</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Free</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">Cloud GPU H100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DGX Spark</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Inference</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Limited</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Comfortable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Overkill</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Slow</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fine-tuning</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">✅ Unbeatable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Possible but slow</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Annual Cost</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$200</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variable (~$416-2,080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4,699 upfront</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Confidentiality</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ US Cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ US Cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ US Cloud (variable)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Total</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Maintenance</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Single setup</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Electricity, updates</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Obsolescence</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5 years</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Software Ecosystem</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All open models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All open models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All open models</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA (but slow)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Verdict</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Occasional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Recommended</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pros/Research</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Air-gap only</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Variable depending on workload; with H100 speed ~10x > Spark, the effective cost for a given workload is low.</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_the_special_case_pro_subscription_vs_chinese_models">The Special Case: Pro Subscription vs. Chinese Models</h2> <div class="sectionbody"> <div class="paragraph"> <p>One point deserves highlighting: the combination of<strong>Ollama Pro at $20/month + Chinese open-source models</strong>is probably the best value-for-money ratio in the history of consumer AI.</p> </div> <div class="sect2"> <h3 id="_why_chinese_models_change_everything">Why Chinese Models Change Everything</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong>: 1.6T params, CSA+HCA, 1M context, competitive with Claude 4 and GPT-5 for code</p> </li> <li> <p><strong>Qwen-3</strong>: 235B, 256K context, excellent in French and reasoning</p> </li> <li> <p><strong>GLM-5.1</strong>: 744B, MLA+DSA, 200K context, built for agentic use</p> </li> </ul> </div> <div class="paragraph"> <p>All available on Ollama. All open-source (permissive licenses). All usable without restriction via a $20/month subscription.</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>With Ollama Pro, you have access to ~5 "frontier" open-source models for the price of a single closed model (Claude Pro). The value is so asymmetrical that it becomes almost absurd.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_what_this_means_for_hardware">What This Means for Hardware</h3> <div class="paragraph"> <p>If the best value-for-money is a $20/month cloud subscription, local hardware becomes a choice of <strong>comfort</strong> or <strong>principle</strong> — not an economic choice.</p> </div> <div class="paragraph"> <p>A DGX Spark at $4,699 is the equivalent of:</p> </div> <div class="ulist"> <ul> <li> <p>235 months of Ollama Pro</p> </li> <li> <p>23 AAA games on release day</p> </li> <li> <p>4 MacBook Air M4s</p> </li> <li> <p>One year of rent for a T2 in Lyon</p> </li> </ul> </div> <div class="paragraph"> <p>For computation. Slow.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_and_huawei">And Huawei?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Since the question was asked during my research: no, Huawei does not market an equivalent to the DGX Spark.</p> </div> <div class="paragraph"> <p>What exists:</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="_conclusion_the_luxury_of_proximity">Conclusion: The Luxury of Proximity</h2> <div class="sectionbody"> <div class="paragraph"> <p>The DGX Spark is not a bad product. It’s a bad investment for 99% of potential buyers.</p> </div> <div id="diag-verdict" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-e8d62f731ea78fcb4f2978a3515b59c2.svg" alt="Verdict final — quel modèle économique domine en 2026" width="476" height="617"> </div> </div> <div class="paragraph"> <p><em><em>_ Buying a DGX Spark in 2026 is like buying a mail server in 2010: technically possible, philosophically satisfying, economically absurd for an individual. </em>_</em></p> </div> <div class="paragraph"> <p>The math is simple, and it doesn’t lie:</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong>to chat with DeepSeek on Ollama Free</p> </li> <li> <p><strong>$200/year</strong>to work seriously with Ollama Pro</p> </li> <li> <p><strong>$5-9</strong>for a one-off fine-tune on cloud GPU</p> </li> <li> <p><strong>$4,699</strong>for…​ the experience of having an NVIDIA box on your desk?</p> </li> </ul> </div> <div class="paragraph"> <p>The market has decided. Cloud subscriptions and Chinese open-source models have won the price battle. Local hardware survives in regulatory niches, not in developers' offices.</p> </div> <div class="paragraph"> <p><em><em>_ The DGX Spark is not a profitable tool. It’s a statement. "I want my AI at home, not in someone else’s cloud." That’s respectable. But in 2026, when Ollama gives you DeepSeek-V4-Pro in the cloud for $20/month, it’s mostly a statement that costs a lot of money. </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>This article is based on a conversation with my AI agent on the economic relevance of the DGX Spark, cross-referenced with market monitoring of cloud GPU prices (Vast.ai, RunPod), Ollama/Claude pricing grids, and the Chinese open-source model ecosystem. The prices quoted are from May 2026 — they will likely have dropped further by the time you read these lines.</strong></p> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_prompt_engineering_is_a_sandcastle">The Problem: Prompt Engineering is a Sandcastle</a></li> <li><a href="#_my_response_the_44_matrix">My Response: The 4×4 Matrix</a> <ul class="sectlevel2"> <li><a href="#_each_zone_of_the_workspace_has_a_gdpr_level_that_determines_where_the_file_can">Each zone of the workspace has a GDPR level that determines <strong>where</strong> the file can</a></li> <li><a href="#_the_spatial_dimension_says_where_to_route_but_there_is_a_second_perpendicular_axis">The spatial dimension says <strong>where</strong> to route. But there is a second, perpendicular axis:</a></li> </ul> </li> <li><a href="#_here_is_what_the_llm_receives_at_each_session">Here is what the LLM receives at each session:</a></li> <li><a href="#_not_hoped_for">not hoped for.</a></li> <li><a href="#_pourquoi_cest_un_manifeste_pas_juste_une_spec">Pourquoi C’est un Manifeste, Pas Juste une Spec</a></li> <li><a href="#_procontra">Pro/Contra</a></li> <li><a href="#_non_testable_did_the_llm_follow_the_rule_is_an_open_question"><strong>Non-testable</strong> — "did the LLM follow the rule?" is an open question</a></li> <li><a href="#_what_makes_it_robust_is_that_it_asks_nothing_of_the_llm_it_does_not">What makes it robust is that it asks nothing of the LLM. It does not</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 14 minutes</div> <p>For months, I stacked agent governance rules. EAGER files, LAZY checklists, six-step session-end protocols. And yet, one question remained: <strong>how does the LLM know what it is allowed to do with a file?</strong></p> </div> <div class="paragraph"> <p>The answer is not in a prompt. It is in the file system.</p> </div> <div class="paragraph"> <p>Here is the architecture specification that makes the answer actionable — la <strong>the LLM governance matrix.</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_prompt_engineering_is_a_sandcastle">The Problem: Prompt Engineering is a Sandcastle</h2> <div class="sectionbody"> <div class="paragraph"> <p>When you give a file to an LLM, you give it everything. The content, yes — but also the absence of safeguards. The LLM doesn’t know if this file contains a secret, a speculative opinion, or closed-source code. It will index it, summarize it, quote it, mix it with other data — and potentially publish it in a public embedding or a user response.</p> </div> <div class="paragraph"> <p>The classic workaround is the 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>This prompt has three problems:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>It relies on the LLM’s goodwill.</strong> A model large enough to</p> </li> </ol> </div> <div class="paragraph"> <p>solve complex bugs is large enough to bypass a security instruction drowned in 200k tokens of context.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>It is contextual, not structural.</strong> Change the prompt, change the LLM,</p> </li> </ol> </div> <div class="paragraph"> <p>change the session — and the rule disappears.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>It doesn’t scale.</strong> Every new file type, every new confidentiality level</p> </li> </ol> </div> <div class="paragraph"> <p>requires a new clause. Your prompt becomes a regulatory text that nobody reads in full.</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 system’s security must never depend on an instruction that can be forgotten, bypassed, or not loaded. It must depend on a barrier that cannot be crossed without explicitly wanting to.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_my_response_the_44_matrix">My Response: The 4×4 Matrix</h2> <div class="sectionbody"> <div class="paragraph"> <p>The solution I implemented in my workspace is a <strong>zone × LLM access right matrix</strong>. It doesn’t ask the LLM to be cautious. It makes imprudence structurally impossible. The Five Zones (Spatial Dimension — GDPR)</p> </div> <div id="diag-matrix-overview" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-ff423528a76bb0bbfad06b9abbd23331.svg" alt="Vue d’ensemble de la matrice de gouvernance LLM — 5 zones × 4 droits d’accès" width="469" height="800"> </div> </div> <div class="sect2"> <h3 id="_each_zone_of_the_workspace_has_a_gdpr_level_that_determines_where_the_file_can">Each zone of the workspace has a GDPR level that determines <strong>where</strong> the file can</h3> <div class="paragraph"> <p>be routed: Zone</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">GDPR Level</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Content</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Public RAG Access Right</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Root</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0 — Intimate</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Brain dumps, LLM conversations</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FORBIDDEN</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>— never indexed</strong>1 — Proprietary Restricted</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">Secrets, tokens, API keys</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FORBIDDEN</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>— never indexed</strong>2 — Collaborative Restricted</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">Editorial data, scoping, training</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FILTERED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>— Vision only</strong>3 — Conditional Open</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">Closed source code, non-public SaaS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FORBIDDEN</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>— private dataset exclusively</strong>4 — Native Public</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">Apache 2.0 code, published plugins</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">FREE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>— full indexing</strong>The rule is simple: <strong>the file path determines what the LLM can do with it.</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>No metadata to maintain, no tags to add in the frontmatter, no manual classification at every commit. The file is in ?`OSS/`It is public. It is in ? It is untouchable.`configuration/`Epistemic Classification (Second Dimension)</p> </div> </div> <div class="sect2"> <h3 id="_the_spatial_dimension_says_where_to_route_but_there_is_a_second_perpendicular_axis">The spatial dimension says <strong>where</strong> to route. But there is a second, perpendicular axis:</h3> <div class="paragraph"> <p><strong>what</strong> to route. Some files in an authorized zone contain information that should not be diluted as is: The epistemic classification grid, engraved as Rule 2bis of my agent governance:</p> </div> <div id="diag-epistemic-filter" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-768538851f5f36f6e05c445dd02dc3ed.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>| Status | Definition | LLM Signal | Destination | | VISION | Stabilized architecture, tested pattern | Declarative language, session/test references | Full dilution + Blog |</p> </div> <div class="paragraph"> <p>| STRATEGY | Business positioning, pricing | Market vocabulary, competition | Root docs only | | OPINION | Speculation, unvalidated hypothesis | Hypothetical language, intuition | Circle 0 Confinement | The combination of the two dimensions — physical zone × epistemic classification — forms the</p> </div> <div class="paragraph"> <p>complete matrix :<strong>How the LLM Consumes This Matrix</strong>The matrix is not a document that the LLM reads. It is an <strong>implicit constraint</strong> encoded in the composite context vector (EPIC 9 — currently being implemented).</p> </div> <div id="diag-full-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-f6f9959b0f07e3bff0bf64c8e1c20ea4.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="_here_is_what_the_llm_receives_at_each_session">Here is what the LLM receives at each session:</h2> <div class="sectionbody"> <div class="paragraph"> <p>Concretely, when the LLM tells me: The zone metadata answers before the LLM even finishes its sentence: is in</p> </div> <div class="paragraph"> <p>, level 3 →</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>access forbidden to public knowledge graph.</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>The RAG doesn’t see it. The graph doesn’t touch it. The user response doesn’t `edster/`quote it.`CSS/`The spatial ontology works like a<strong>Unix permission</strong> for LLMs. You don’t ask a process to be careful with</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>—<strong>you deny it read access. Same principle.</strong>Implementation: Typed Gradle Tasks The matrix is not a philosophy. It’s code. Here is the Gradle task contract that implements it:`/etc/shadow`The task is <strong>testable</strong>. You can write a test that verifies: 380 tests, 380 PASS. Just like for plantuml-gradle — security is tested,</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_not_hoped_for">not hoped for.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Why This Is a Manifesto, Not Just a Spec This document is an architecture specification because it defines:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class ZoneAwareIndexer @Inject constructor( private val rootDir: DirectoryProperty, private val configServer: ConfigServerProperty // → configuration/ ) : DefaultTask() { @Input val zoneFilter: SetProperty<Zone> = project.objects.setProperty(Zone::class.java) @OutputFile val ragIndex: RegularFileProperty = project.objects.fileProperty() @TaskAction fun index() { val allowedPaths = zoneFilter.get().flatMap { it.resolve(rootDir.get()) } val forbiddenPaths = Zone.RESTRICTED.resolve(rootDir.get()) + Zone.INTIMATE.resolve(rootDir.get()) // Le RAG ne voit jamais configuration/ ni la racine // CSS/ alimente un index privé, pas celui-ci // office/ est filtré par le classifieur Vision/Opinion } } enum class Zone { INTIMATE, // Cercle 0 — racine RESTRICTED, // Cercle 1 — configuration/ EDITORIAL, // Cercle 2 — office/ CLOSED_SOURCE, // Cercle 3 — foundry/private/ OPEN_SOURCE // Cercle 3 — foundry/public/ }</code></pre> </div> </div> <div class="paragraph"> <p>La tâche est <strong>testable</strong>. Vous pouvez écrire un test qui vérifie :</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>dimensions (spatial, epistemic)</p> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_cest_un_manifeste_pas_juste_une_spec">Pourquoi C’est un Manifeste, Pas Juste une Spec</h2> <div class="sectionbody"> <div class="paragraph"> <p>deterministic rules</p> </div> <div class="ulist"> <ul> <li> <p>(zone → access right)<strong>task contract</strong>(Typed Gradle, testable)</p> </li> <li> <p>A<strong>reference implementation</strong>(my workspace)</p> </li> <li> <p>Un <strong>But it is also a</strong>manifesto</p> </li> <li> <p>because it takes a position on a<strong>broader debate: *how to govern an LLM’s access to data?</strong>*The industry answer is prompt engineering + guardrails</p> </li> </ul> </div> <div class="paragraph"> <p>and post-hoc classifiers. My answer is: <strong>put your files in</strong>the right folders.<strong> The rest is automatic.</strong>This manifesto does not say "LLMs must be aligned." It says: "an LLM’s alignment with your security rules is a consequence of your file system, not your prompt."</p> </div> <div class="paragraph"> <p>The Full Cascade — from Brain Dump to Blog Post<br> To illustrate the complete cycle, here is how this matrix idea was born and diluted:</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>What started as an observation during a session ("hey, the RAG doesn’t know that edster is closed source") became an architecture specification published in less than one session. This is the STIMULUS pattern in action.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_procontra">Pro/Contra</h2> <div class="sectionbody"> <div class="paragraph"> <p>This Approach (Spatial Ontology + Matrix) The Classical Approach (Prompt + Guardrails)</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><strong>Mechanical</strong> — the file system blocks access, not the LLM <strong>Declarative</strong> — the prompt asks the LLM to be cautious <strong>Testable</strong> — the Gradle task contract is verified by 380+ tests</p> </div> </div> </div> <div class="sect1"> <h2 id="_non_testable_did_the_llm_follow_the_rule_is_an_open_question"><strong>Non-testable</strong> — "did the LLM follow the rule?" is an open question</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"><strong>LLM-Independent</strong> — change the model, the folders remain</th> <th class="tableblock halign-left valign-top"><strong>LLM-Dependent</strong> — each model interprets the prompt differently</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Scalable</strong> — new data type = new folder, zero code change</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non-scalable</strong> — new data type = new prompt clause, new regression risk</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Auditable</strong> — the file system is the audit trail</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non-auditable</strong> — the prompt has no history, no diff, no blame</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Constraint</strong>: requires initial organizational discipline</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Constraint</strong>: requires prompt drafting discipline at each session</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Conclusion: Organize Your Files, Not Your Prompts</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The LLM governance matrix I just described is not a product.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">It is an</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">architecture specification</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">— and that’s why it is</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">publishable.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_what_makes_it_robust_is_that_it_asks_nothing_of_the_llm_it_does_not">What makes it robust is that it asks nothing of the LLM. It does not</h2> <div class="sectionbody"> <div class="paragraph"> <p>trust it. It does not rely on its alignment, its understanding of French, or its goodwill. It relies on the file system —<strong>the lowest, most stable, most tested layer of the entire stack.</strong>When I tell my LLM "you can index everything in , nothing in</p> </div> <div class="paragraph"> <p>only if it is classified as Vision" — it’s not an instruction. It’s a <strong>filter</strong> — implemented in Kotlin, verified by 380 tests, executed before the LLM even sees the data. It’s the difference between telling someone "don’t look in this drawer"</p> </div> <div class="paragraph"> <p>and locking the drawer with a key. The agent governance I’ve been building for`OSS/<code>months is the key. The matrix is the furniture blueprint. `configuration/</code>, et `office/`References <a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — Automated Epistemic Compartmentalization</a> <a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — Trust Circles and Spatial Ontology</a></p> </div> <div class="paragraph"> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Governing an AI Agent with AsciiDoc</a> Article 0115 — The Anonymizer MVP0 des mois est la clé. La matrice est le plan du meuble.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — Le Compartimentage Épistémique Automatisé</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — Les Cercles de Confiance et l’Ontologie Spatiale</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Gouverner un Agent IA avec du AsciiDoc</a></p> </li> <li> <p><a href="../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html">Article 0115 — L’Anonymiseur MVP0</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_the_accident_waiting_to_happen">The Accident Waiting to Happen</a> <ul class="sectlevel2"> <li><a href="#_the_real_question">The Real Question</a></li> </ul> </li> <li><a href="#_the_solution_oss_and_css">The Solution: OSS/ and CSS/</a></li> <li><a href="#_why_oss_and_css_and_not_public_and_private">Why "OSS" and "CSS" and Not "Public" and "Private"</a> <ul class="sectlevel2"> <li><a href="#_the_complete_tree_four_zones_not_three">The Complete Tree — Four Zones, Not Three</a></li> </ul> </li> <li><a href="#_the_special_case_cheroliv_com">The Special Case: cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_and_thats_the_beauty_of_it_the">And that’s the beauty of it. The</a></li> </ul> </li> <li><a href="#_osscss_granularization_modifies_agent_governance_on_three_points">OSS/CSS granularization modifies agent governance on three points:</a></li> <li><a href="#_before_flat_folder">Before (flat folder)</a></li> <li><a href="#_what_i_did_this_afternoon_was_replace_an_invisible_convention">What I did this afternoon was replace an invisible convention</a></li> <li><a href="#_article_0117_the_llm_governance_matrix">Article 0117 — The LLM Governance Matrix</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p>reading time: 10 minutes</p> </li> </ol> </div> <div class="paragraph"> <p><code>foundry/</code>— the functional area that hosts the code of my workspace — contains 18 projects. Eight are open source under Apache 2.0. Only one is closed source — the Edster SaaS. For months, these nine projects cohabited in the same folder, separated only by…​ nothing. Their public/private status was information in my head, not in the file system.</p> </div> <div class="paragraph"> <p>And then I wanted to hook up a RAG. And that’s when everything collapsed.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_accident_waiting_to_happen">The Accident Waiting to Happen</h2> <div class="sectionbody"> <div class="paragraph"> <p>In April 2026, I started implementing pgvector RAG for slider-gradle. The principle: index all repositories in`foundry/`, produce embeddings, and inject them into the LLM’s context so that it has a "perception" of the`foundry/`folder.</p> </div> <div class="paragraph"> <p>The pipeline was simple:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val repos = fileTree(rootDir) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val chunks = repos.map { chunk(it) } val embeddings = chunks.map { embed(it) } pgvector.insert(embeddings)</code></pre> </div> </div> <div class="paragraph"> <p>Simple. Effective. And<strong>dangerous</strong>.</p> </div> <div class="paragraph"> <p>Because this`fileTree`does not differentiate between`plantuml-gradle/` (Apache 2.0, public) and`edster/`(closed source, private). It swallows everything. And if one day I publish these embeddings — on a dashboard, in an LLM response, in a training dataset — Edster’s proprietary code leaks.</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>The problem isn’t an LLM reading closed source code. The problem is that this code ends up in a <strong>public</strong> vector embedding — irreversible, non-deletable, non-auditable.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_the_real_question">The Real Question</h3> <div class="paragraph"> <p>It’s not "how to prevent the LLM from leaking code?". It’s "how to make the leak structurally impossible?"</p> </div> <div class="paragraph"> <p>The answer is not a prompt. The answer is to split the folder in two.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_oss_and_css">The Solution: OSS/ and CSS/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before:</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>After:</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`becomes:</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>The public RAG never sees`CSS/`. The closed source code feeds a private fine-tuning dataset — an internal model that never leaves my house. The separation is mechanical, not declarative.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_why_oss_and_css_and_not_public_and_private">Why "OSS" and "CSS" and Not "Public" and "Private"</h2> <div class="sectionbody"> <div class="paragraph"> <p>The choice of acronyms OSS (Open Source Software) and CSS (Closed Source Software) is deliberate:</p> </div> <div class="ulist"> <ul> <li> <p>"Public"/"Private" describes the<strong>visibility</strong>(what GitHub sees)</p> </li> <li> <p>"OSS"/"CSS" describes the<strong>nature</strong>of the code (what the LLM needs to know)</p> </li> </ul> </div> <div class="paragraph"> <p>GitHub visibility is metadata of the remote repo. The nature of the code is a property of the content. The LLM does not have access to the GitHub API — but it has access to the file system.<code>CSS/`tells it "careful, this code is not under a free license" without needing to read a`LICENSE`or parse a`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>The folder name is the most robust metadata you can give to an LLM. It cannot be misparsed, ignored, or misinterpreted. The LLM sees`CSS/edster/`in the file path — it knows.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_the_complete_tree_four_zones_not_three">The Complete Tree — Four Zones, Not Three</h3> <div class="paragraph"> <p>OSS/CSS granularization completes the three-zone ontology. The `foundry/`zone goes from 1 to 2 functional sub-zones:</p> </div> <div id="diag-four-zone-workspace" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-69dfc4d88e57c2bbc80fff055ca536cd.svg" alt="L’organisation de foundry/ en deux sous-zones OSS et CSS" width="2182" height="190"> </div> </div> <div class="paragraph"> <p>| Zone | GDPR | Public RAG Indexing | Fine-tuning Dataset | | Root | Level 0 — Intimate | ✗ | ✗ | |<code>configuration/</code>| Level 1 — Restricted | ✗ | ✗ | |<code>office/</code>| Level 2 — Collaborative | ✓ Filtered | ✓ Filtered | |<code>foundry/private/</code>| Level 3 — Conditional Open | ✗ | ✓ Private | |<code>foundry/public/</code>| Level 4 — Native Public | ✓ Free | ✓ Public |</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_special_case_cheroliv_com">The Special Case: cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>While I was at it, I corrected another inconsistency. My site <code>cheroliv.com`lived in`foundry/`as a full-fledged software project — with its own Gradle build, its own CI, its own governance .</code>.agents/`But blog posts are not code. They are <strong>editorial data</strong></p> </div> <div class="paragraph"> <p>of Circle 2 — just like the framings of or the training of`office/pilotage/` .`office/formations/`What changes:</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>Articles are in</p> </div> <div class="ulist"> <ul> <li> <p>→ Circle 2 confidentiality`office/`The</p> </li> <li> <p>task becomes a capability of`publishSite`via`engine`</p> </li> </ul> </div> <div class="paragraph"> <p>— the plugin receives an`bakery-gradle`, it doesn’t know`FileTree`that the articles come from One single CI, one single governance — zero duplication`office/`</p> </div> <div class="ulist"> <ul> <li> <p>The Vision/Opinion classifier (Rule 2bis) applies automatically:</p> </li> <li> <p>articles in</p> </li> </ul> </div> <div class="paragraph"> <p>are filtered before publication`office/`bakery-gradle Doesn’t Care</p> </div> <div class="sect2"> <h3 id="_and_thats_the_beauty_of_it_the">And that’s the beauty of it. The</h3> <div class="paragraph"> <p>plugin was not modified.<code>bakery-gradle`It receives an AsciiDoc content directory, it generates HTML, it pushes to GitHub Pages. Whether this directory is called — the plugin doesn’t care.`site/jbake/content/</code> ou `office/sites/cheroliv/`The interface contract is a Gradle task. Not a REST API. Not a webhook.</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>A task — typed, testable, executable locally and in the CI. Impact on Agent Governance</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_osscss_granularization_modifies_agent_governance_on_three_points">OSS/CSS granularization modifies agent governance on three points:</h2> <div class="sectionbody"> <div class="paragraph"> <p><strong>Public RAG</strong> : the indexing perimeter changes from</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>+<code>foundry/**</code></p> </li> </ol> </div> <div class="paragraph"> <p>à <code>foundry/public/<strong></code>. Closed source code`office/Vision/</strong>`is excluded from the index by task configuration, not by prompt. <strong>Knowledge Graph</strong> : graphify-gradle produces two graphs:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>*</p> </li> </ol> </div> <div class="paragraph"> <p>(public) — relations between OSS artifacts + office/Vision`office/graph.json`* (gitignored, private) — relations between`configuration/graph_private.json`CSS artifacts, never published <strong>Fine-tuning Dataset</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>now has two sources:`codebase-gradle`*</p> </li> </ol> </div> <div class="paragraph"> <p>→ public datasets (community models, benchmarks)<code>OSS/</code>* → private datasets (internal model, proprietary fine-tuning)`CSS/`What is Gained (And What is Lost)</p> </div> </div> </div> <div class="sect1"> <h2 id="_before_flat_folder">Before (flat folder)</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">After (OSS/CSS + office/sites)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">→ public/private mix</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/</code>→ everything is publishable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`ls foundry/public/`RAG indexes everything without discrimination</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">+`OSS/`exclusively`office/Vision`Impossible to know if a project is open source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">says it`OSS/` ou `CSS/`cheroliv.com has its own CI, its own governance</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI and governance are shared in engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Blog posts are in a "code" repository</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Blog posts are in</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">— data, not code`office/sites/`Risk of closed source code leaking into public embeddings</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Structurally impossible —</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">out of RAG scope`CSS/`The only cost: a</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>global across 17 OSS repos + a refactor of the`git mv`. It’s a cold migration — <code>build.gradle.kts</code> de `engine`no data in flight, no users impacted. Conclusion: Physical Signal Beats Software Signal</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_i_did_this_afternoon_was_replace_an_invisible_convention">What I did this afternoon was replace an invisible convention</h2> <div class="sectionbody"> <div class="paragraph"> <p>with a visible separation in the zone. Before, you had to`foundry/`<strong>know</strong> that was closed source. Now, you <strong>see</strong> it —`edster/`the folder is called .`CSS/`It’s the same principle as Unix permissions, network VLANs, or</p> </div> <div class="paragraph"> <p>firewall compartments in a database. Security should not be information you have to remember. It must be a physical property <strong>of the system.</strong>OSS/CSS granularization is the translation of this principle into the domain</p> </div> <div class="paragraph"> <p>of LLM governance. The LLM doesn’t need to know that Edster is confidential. It needs to be incapable of indexing it. And that is exactly what</p> </div> <div class="paragraph"> <p>guarantees.`CSS/`References</p> </div> </div> </div> <div class="sect1"> <h2 id="_article_0117_the_llm_governance_matrix"><a href="0118_matrice_gouvernance_llm_zone_acces_workspace_post.html">Article 0117 — The LLM Governance Matrix</a></h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — The Circles of Trust</a></p> </li> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — Automated Epistemic Compartmentalization</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Governing an AI Agent with AsciiDoc</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Gouverner un Agent IA avec du AsciiDoc</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_thinking_freely_without_publishing_just_anything">The Problem: Thinking Freely without Publishing Just Anything</a></li> <li><a href="#_the_stimulus_pattern_born_fixed_diluted_died">The STIMULUS Pattern — Born, Fixed, Diluted, Died</a></li> <li><a href="#_delegation_to_the_llm_why_the_llm_is_the_one_filtering">Delegation to the LLM: Why the LLM is the one Filtering</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time : 10 minutes</div> <p>My LLM doesn’t just execute my Gradle tasks. It is the guardian of the boundary between my private thought and my public expression. Every idea is classified — Vision, Opinion, Strategy — before being routed. Here is how this automated epistemic compartmentalization protects my mental garden without silencing me.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_thinking_freely_without_publishing_just_anything">The Problem: Thinking Freely without Publishing Just Anything</h2> <div class="sectionbody"> <div class="paragraph"> <p>When a solo developer documents their thought process with an LLM, they encounter a paradox:</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>Between these two extremes, there is a<strong>filter</strong>. The question is: who does it? A tired human at the end of a session? A naive regex script? Or the LLM itself, which has already read everything?</p> </div> <div class="paragraph"> <p>My answer: the LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_stimulus_pattern_born_fixed_diluted_died">The STIMULUS Pattern — Born, Fixed, Diluted, Died</h2> <div class="sectionbody"> <div class="paragraph"> <p>A STIMULUS is a`.adoc`temporary file at the root of the workspace (Circle 0). Its name follows an evocative convention —<code>PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code>— which captures the exploratory intention of the moment.</p> </div> <div class="paragraph"> <p>Its life cycle is ruthless:</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>A stimulus that survives more than 2 sessions without dilution is an anti-pattern. Either the information is too important to rot in a temporary file (→ dilute), or it is too vague to deserve existence (→ delete).</p> </div> </div> </div> <div class="sect1"> <h2 id="_delegation_to_the_llm_why_the_llm_is_the_one_filtering">Delegation to the LLM: Why the LLM is the one Filtering</h2> <div class="sectionbody"> <div class="paragraph"> <p>I don’t hardcode the Vision/Opinion classification in Kotlin. I inject it into the<strong>system prompt</strong>of the 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 ---- The LLM reads this directive**before**processing the session. It is in its immediate context, not in a separate file. This is *deterministic prompt engineering*: the behavior emerges from the injected text, not from an external classifier. === Why It Works — and Why It's Counter-Intuitive The standard reaction: "You entrust classification to the AI? What if it's wrong?" Answer: humans don't do any better at 2 AM. The difference is that the LLM reads EVERYTHING. It has the full context of the session and the target documents. It knows that`VPS ECO-16 12€ HT`is an infrastructure decision (VISION) while`« le TTS ElevenLabs sonne plus naturel que Coqui »`is an opinion not verified by a benchmark. The human, at the end of a session, skims and does their best. The LLM reads exhaustively and applies a systematic grid. The result is**more reliable**, not less. And for the 20% of ambiguous cases — the gray zone where even the LLM hesitates — the answer is not "add more code." The answer is**LangGraph4j**(EPIC 13): a state graph that, for ambiguous cases, activates a Human-in-the-Loop node and escalates to the human for a decision. But for the 80% of clear cases, the LLM is sufficient. == The Complete Pipeline: from Brain Dump to Blog Post Here is the complete flow — from raw idea to published article — with the LLM as the sole filter: [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 ---- The developer doesn't write the article. They challenge, proofread, validate. The LLM writes. The loop is: 1. Free brain dump → no censorship 2. Epistemic classification by the LLM → no leaks 3. Drafting by the LLM → no procrastination 4. Human review → no errors The historical bottleneck — "I don't have time to write" — is eliminated. The LLM does the bulk of the work. The human does what only a human can do: judge. == The Three Root Documents — How Information Finds Its Place Each target document has a precise role in the dilution cascade: [cols="1,3,2"] |=== |Document |What it receives |Content type |`WORKSPACE_AS_PRODUCT.adoc` |Architectural decisions, technical stack, roadmap, business model |VISION + STRATEGY |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |Patterns, lessons, anti-patterns, ontology, formal rules |VISION (tested patterns) |`WORKSPACE_VISION.adoc` |Session context, decision history, infrastructure points |VISION + STRATEGY (context) |`AGENT_GOVERNANCE.adoc` |Governance rules, project portfolio, procedures |VISION (governance) |**Blog cheroliv.com** |Public articles, value for the external reader |VISION only |=== A single stimulus can feed all 4 documents + the blog — each destination receives the portion that concerns it, without redundancy, without contradiction. This is what happened for`PICTURE_ME_ROLLIN.adoc`(May 3, 2026): | Information | Classification | Destinations | | Inventory of 13+ foundry/ projects | VISION | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 8.49€/month | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | | "The African market is ready for mobile money" | STRATEGY | WORKSPACE_AS_PRODUCT (business section) | | "DeepSeek > Kimi > GLM for long context" | OPINION → VISION | Confined then promoted after benchmark (article 0112) | | Synthetic Employee as final product | STRATEGY | WORKSPACE_AS_PRODUCT (no blog) | == The Baby-Step + TestContainer + Living Doc Pattern — Code that Tests Itself The STIMULUS/Dilution pattern manages thought. Its equivalent for code is the Baby-Step/TestContainer/Living Doc pattern, validated by plantuml-gradle (380/380 tests PASS, 137 sessions without Docker leaks): [cols="1,3"] |=== |Principle |Rule |**Baby-step** |Never more than 3 pts per US. If a US is intimidating, break it down. A 1 pt US that passes > an 8 pt US that drags on. |**TestContainer first** |Before business code, the container. Infra test passes → stable environment guaranteed. |**Committed dataset** |Minimal but representative subset in`src/test/resources/`, without PII. Clonable, runnable. |**Living documentation** |Each Cucumber test = one sentence in natural language. The source code IS the executable spec. Zero Markdown docs to maintain. |**Automatic cleanup** |Zero resource leaks. Orphaned containers,`/tmp/gradle-test-*`: everything is cleaned up. |=== This pattern is the reason why plantuml-gradle has never had a Docker regression in 138 sessions. It ensures that code talking to an external infra (PostgreSQL, Redis, Kafka) is always tested in an environment identical to production — versioned, reproducible, runnable in one command. == Conclusion: The Freedom to Think without the Fear of Publishing Automated epistemic compartmentalization is not a tool for censorship. It is a**liberator**. It allows for thinking freely, speculating without a filter, brain-dumping everything that comes to mind — without ever fearing that an embryonic idea ends up on the blog. The LLM is the guardian of this boundary. It reads everything. It classifies. It dilutes what deserves to survive. It confines what must remain private. It drafts what is publishable. And the developer keeps the final word: proofread, challenge, validate. Judge. This is the division of labor that was missing for the solo developer: a synthetic employee who handles the mental paperwork, so that the human can focus on what they do best — design, architect, decide. == References * Article on Eager/Lazy agent governance:link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governing an AI Agent with AsciiDoc] * Article on spatial ontology and trust circles:link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[Spatial Ontology as an Alignment Mechanism] * Article on the MVP0 Anonymizer:link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Our First Hire: the Dataset Anonymizer] * Article on long-context LLM comparison:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * Article on the agent backup mechanism:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window and Cold Wave]</code></pre> </div> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_that_scares_everyone_away">The Problem that Scares Everyone Away</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time : 12 minutes</div> <p>I’m not hiring an LLM. I’m hiring an anonymizer. Before doing pgvector RAG, before fine-tuning CDA/FPA experts, before provisioning client workspaces — someone has to clean the data toilets. This employee is the anonymization expert (MVP0, EPIC 2 of codebase-gradle). And it is this person who makes the product marketable.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_that_scares_everyone_away">The Problem that Scares Everyone Away</h2> <div class="sectionbody"> <div class="paragraph"> <p>Every AI startup handling training data hits the same wall:</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 ---- Result: either you do RAG on dirty data (PII hallucinations, GDPR non-compliance, legal risk), or you do nothing (no product). The third way — cleaning by hand — is not scalable. My response: do not bypass the problem.**automate it**. == MVP0: the Anonymizer, First Hire on Probation The MVP0 is not a feature. It is a**commodity expert**— an employee who does the dull, dirty work that no one wants to talk about in pitch decks. What it does: [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 ---- It detects the most obvious patterns first (emails`.*@.*`, tokens`sk-*`, `ghp_*`, IPs), then it learns. The probation period is exactly that: we validate that it doesn't let false negatives slip through before making it permanent. == What this MVP Unlocks (and it's not just Compliance) Anonymization as MVP0 is not the GDPR toll booth before the highway. It is the highway itself. Here is what it opens: === Present: Augmented Reality in 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 ---- RAG doesn't search through dirty data — it searches in a space**clean by construction**. This changes everything for response quality: the LLM doesn't spend its time bypassing PII that it recognizes but must not mention. === Future: Fine-Tuning on Healthy Data [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) ---- Fine-tuning on raw data is a legal catastrophe waiting to happen. On clean data, it is a**reproducible method**. Each client accumulates their cleaned datasets, each client can fine-tune their business experts on their data — without ever exposing personal data. == Why It's Marketable It's not "a GDPR compliance tool." It is a**reproducible method that transforms a universal problem into an asset**: 1. *Every training company has dirty data* — that's the problem 2. *None have an automated multi-source cleaning pipeline* — that's the market 3. *The loop: anonymization → RAG → fine-tuning is proprietary* — that's the barrier The Edster SaaS (MVP3) will not sell "a Gradle workspace." It will sell this closed loop. And the MVP0 is the entry point. == SQL Format as the Third Way of Context Importing structured data is not just an exchange format. The SQL schema (DDL) carries the**entity-relationship model of the domain**: [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é ); ---- This DDL, once anonymized (line 4), becomes a context source for the LLM. Not text — a**business model**. RAG provides the content (vector similarity), Graphify provides the relations (exact structure), and the SQL schema provides the**implicit Domain-Driven Design**: bounded contexts, aggregates, value objects. The LLM understands the business because it reads its schema. == The Roadmap: from MVP0 to 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 ---- Each MVP depends on the previous one. None can be delivered without MVP0. This is why the Anonymizer is not "P0" in the backlog — it is**MVP0**. It is the first commercial deliverable, and everything else is contingent on its success. == Conclusion: the Invisible Work that Makes Everything Possible In a typical startup, data cleaning is outsourced, manual, or ignored. In this architecture, it is the**heart of the product**. The Anonymizer is the first employee because without it, nothing works: * Without MVP0 → no legal RAG (MVP1) * Without MVP0 → no fine-tuning without data leaks (EPIC 5) * Without MVP0 → no credible SaaS (MVP3) * Without MVP0 → no augmented reality in prompt * Without MVP0 → no third way of context (SQL DDD) It does the dirty work. It will never be mentioned in pitches. But it's the one that runs the factory. And that's why we hire it first. == References * Article on spatial ontology and trust circles:link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[Spatial Ontology as an Alignment Mechanism] * Article on Eager/Lazy agent governance:link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governing an AI Agent with AsciiDoc] * Article on the Hot/Warm/Cold mechanism:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window and Cold Wave] * Article on the comparison of the three 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/en/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="#_the_observation_prompt_engineering_is_a_sandcastle">The Observation: Prompt Engineering is a Sandcastle</a></li> <li><a href="#_the_four_circles_of_trust_a_spatial_ontology">The Four Circles of Trust: a Spatial Ontology</a> <ul class="sectlevel2"> <li><a href="#_the_secret_garden_out_of_cvs_space">The Secret Garden: Out-of-CVS Space</a> <ul class="sectlevel3"> <li><a href="#_gitignore_as_governance_configuration"><code>.gitignore</code> as Governance Configuration</a></li> <li><a href="#_the_snapshot_mechanism">The Snapshot Mechanism</a></li> </ul> </li> <li><a href="#_the_vault_configuration_as_spring_cloud_config">The Vault: <code>configuration/</code> as Spring Cloud Config</a></li> <li><a href="#_the_library_office_as_consumable_data">The Library: <code>office/</code> as Consumable Data</a></li> <li><a href="#_the_forges_foundry_as_implementation">The Forges: <code>foundry/</code> as Implementation</a></li> </ul> </li> <li><a href="#_procontra_spatial_alignment_vs_prompt_alignment">Pro/Contra: Spatial Alignment vs Prompt Alignment</a> <ul class="sectlevel2"> <li><a href="#_classical_approach_pre_prompt_alignment">Classical Approach: Pre-Prompt Alignment</a></li> <li><a href="#_this_approach_spatial_ontology_alignment">This Approach: Spatial Ontology Alignment</a></li> </ul> </li> <li><a href="#_the_relational_algebra_of_the_workspace_and_the_observable_delta">The Relational Algebra of the Workspace and the Observable Delta</a></li> <li><a href="#_the_composite_context_vector_rag_pgvector_graphify">The Composite Context Vector: RAG + pgvector + Graphify</a> <ul class="sectlevel2"> <li><a href="#_component_1_rag_langchain4j_postgresql_pgvector">Component 1 — RAG LangChain4j + PostgreSQL pgvector</a></li> <li><a href="#_component_2_knowledge_graph_graphify">Component 2 — Knowledge Graph Graphify</a></li> <li><a href="#_component_3_incremental_graphify_sparse_aggregatable_consumable">Component 3 — Incremental Graphify: Sparse, Aggregatable, Consumable</a></li> </ul> </li> <li><a href="#_automatic_gdpr_classification_the_llm_as_router">Automatic GDPR Classification: the LLM as Router</a></li> <li><a href="#_roadmap_from_asciidoc_to_langgraph4j">Roadmap: from AsciiDoc to LangGraph4j</a></li> <li><a href="#_what_this_architecture_solves_and_what_it_doesnt_solve">What This Architecture Solves (and what it doesn’t Solve)</a></li> <li><a href="#_conclusion_architecture_as_discourse">Conclusion: Architecture as Discourse</a></li> <li><a href="#_references">References</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 20 minutes</div> <p>Prompt engineering is fragile. At 80,000 tokens, your alignment rules are drowned in noise, and the LLM forgets what you asked at the beginning of the conversation. My solution? Do not align by text, but by<strong>space</strong>. I structured my development workspace into four concentric circles of trust — from the intimate secret garden to the public forges — and each circle is a physical zone of the file system. The LLM doesn’t need to be reminded of the rules: the file path contains them. Here is how it works, and why this spatial alignment architecture is more resilient than a`system prompt`of 500 lines.</p> </div> <div class="paragraph"> <p>This is a long article.<br> Get comfortable.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_observation_prompt_engineering_is_a_sandcastle">The Observation: Prompt Engineering is a Sandcastle</h2> <div class="sectionbody"> <div class="paragraph"> <p>For three weeks, I developed Gradle plugins with Opencode, using three different LLMs — Kimi K2.6, GLM-5.1, and DeepSeek-V4-Pro (the only survivor, but that’s another story<a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Already covered here.</a>). My agent governance method<a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">I documented it in detail in a previous article.</a> relies on AsciiDoc files —<code>AGENT.adoc</code>, <code>INDEX.adoc</code>, <code>PROMPT_REPRISE.adoc</code>— which load ~30,000 tokens of rules, backlog, and history at the start of every session.</p> </div> <div class="paragraph"> <p>And despite this documentary infrastructure, two things struck me:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>The LLM forgets.</strong> Even with absolute rules at the top of every EAGER file, beyond 60,000 cumulative tokens (initial context + conversation), Kimi K2.6 began suggesting`Write`overwriting configuration files. GLM-5.1 confused a Firebase token with a placeholder to be replaced. The rules were written — the LLM no longer <strong>saw</strong> them.</p> </li> <li> <p><strong>Governance itself becomes a problem.</strong> After implementing the Hot/Warm/Cold mechanism<a href="0110_mecanisme_backup_contexte_agent_post.html">Article on backup rotation.</a> to avoid context explosion, my EAGER files still weighed 1414 lines<a href="0111_audit_contexte_agent_post.html">I documented this audit here.</a>. Governance — designed to protect the LLM from saturation — was saturating the LLM.</p> </li> </ol> </div> <div class="paragraph"> <p>I needed an alignment mechanism that did not depend on the number of tokens in the prompt.</p> </div> <div class="paragraph"> <p>The answer: stop aligning by text, and start aligning by<strong>space</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_four_circles_of_trust_a_spatial_ontology">The Four Circles of Trust: a Spatial Ontology</h2> <div class="sectionbody"> <div class="paragraph"> <p>My`workspace/<code>folder (in</code>~/workspace/`) is <strong>not</strong> a Git repository. It is the root of all my work — code, documentation, training, infrastructure. And it is structured into four zones that are not just storage conventions, but<strong>concentric circles of trust</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">Level</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">Physical Zone</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">Visibility</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>Secret Garden</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`workspace/`root</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">None</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Intimate — free thought, no commit, no publication</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>Vault</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">Private Git (solo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secrets, tokens, vision archive. One single person.</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>Library</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">Private Git (extended)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pedagogical data, SPG/SPD, JSON schemas. Identified circle of trust.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Forges (public)</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">Public Git (Apache 2.0)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Source code, plugins, tests, technical documentation.</p></td> </tr> </tbody> </table> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> There is no level 3 in the table. Level 3 is a <strong>transitory</strong> level: it is content from`office/`that has been anonymized and is ready to be published as open data. It has no physical zone of its own — it is a state of the data, not a location. </td> </tr> </table> </div> <div class="paragraph"> <p>Each level answers a specific question:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Where to put an idea that is not yet ready to be shared, even with a restricted circle?</strong> → The secret garden. No Git. No pressure.</p> </li> <li> <p><strong>Where to store an API token without it leaking?</strong> → The vault (<code>configuration/</code>). Physically isolated. No other repository can reference it by mistake.</p> </li> <li> <p><strong>Where to co-construct a training catalog with a pilot training center?</strong> → The library (<code>office/</code>). Versioned, collaborative, but private.</p> </li> <li> <p><strong>Where to industrialize an open source Gradle plugin?</strong> → The forges (<code>foundry/</code>). Public, forkable, tested in CI.</p> </li> </ul> </div> <div class="paragraph"> <p>This ontology is<strong>consumable by an LLM</strong>. When it reads a file in`foundry/plantuml-gradle/src/`, it knows implicitly: "I am in circle 4 — public code, mandatory tests, no secrets, no pedagogical data". It does not need a prompt to remind it.</p> </div> <div class="sect2"> <h3 id="_the_secret_garden_out_of_cvs_space">The Secret Garden: Out-of-CVS Space</h3> <div class="paragraph"> <p>This is the most important — and most counter-intuitive — concept.</p> </div> <div class="paragraph"> <p>The`workspace/<code>root has no</code>.git/<code>. The documents that live there (`WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>— and the one you are reading right now, which originated from it) are not intended to be versioned, shared, or even reread by anyone other than me. They are<strong>germinating thoughts</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>The secret garden is <strong>out-of-CVS</strong> by nature. The absence of versioning is the condition for freedom of thought. One does not write there to be read — one writes to clarify one’s own vision.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>But this freedom has a cost: one accidental`rm`and months of strategic reflection disappear. The solution is not to version the garden (that would destroy it) — it is to<strong>mirror it</strong>into the most restricted circle.</p> </div> <div class="sect3"> <h4 id="_gitignore_as_governance_configuration"><code>.gitignore</code> as Governance Configuration</h4> <div class="paragraph"> <p>At the root of`workspace/<code>, a minimal</code>.gitignore`file declares the<strong>history policy</strong>for the secret garden files:</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`has no classic Git function (there is no</code>.git/`at the root). It acts as a<strong>governance configuration file</strong>that answers a specific question: <strong>which artifacts from the secret garden deserve to be historized, and which are purely transitory?</strong></p> </div> <div class="ulist"> <ul> <li> <p>Files listed in`.gitignore`—<code>.goosehints</code>, <code>.goose</code>— are ephemeral artifacts generated by agents. No strategic value. No history.</p> </li> <li> <p>Files`.adoc`of the root —<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>— are<strong>not</strong>in the`.gitignore`. These are the artifacts to be historized.</p> </li> </ul> </div> <div class="paragraph"> <p>Le `.gitignore`is the<strong>governance schema</strong>: everything not listed there is a candidate for a snapshot. And the LLM, by reading this file, knows exactly what must be archived and what can be ignored — without needing to be reminded in a prompt.</p> </div> </div> <div class="sect3"> <h4 id="_the_snapshot_mechanism">The Snapshot Mechanism</h4> <div class="paragraph"> <p>I created`configuration/vision-archive/<code>: dated snapshots of all</code>.adoc`of the root, committed to the private repository`configuration/`. Each brainstorming session produces a 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>The procedure is triggered at the end of the session by the LLM itself, which executes this global routing task. Each snapshot captures the complete state of strategic thought at time T.</p> </div> <div class="paragraph"> <p>The Git history of`configuration/`becomes the<strong>biography of my strategic thought</strong>. I can do a`git log — vision-archive/`and see the evolution of my vision, session by session, date by date.</p> </div> <div class="paragraph"> <p>Real example of the history after a day of work:</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>Five snapshots in one day. Each is a restoration point. Each is a milestone in the genesis of the strategy.</p> </div> <div class="paragraph"> <p>The`configuration/vision-archive/latest/`folder permanently contains a<strong>working copy</strong>of the last snapshot, serving as a quick reference without having to navigate the Git history.</p> </div> <div class="paragraph"> <p>And for the LLM, it is a<strong>coherence oracle</strong>: when it observes a contradiction between the current implementation and the vision archived at an earlier date, it can signal it.</p> </div> </div> </div> <div class="sect2"> <h3 id="_the_vault_configuration_as_spring_cloud_config">The Vault: <code>configuration/</code> as Spring Cloud Config</h3> <div class="paragraph"> <p>`configuration/`does not only contain the vision archive. Its primary — and future — function is to be a<strong>Spring Cloud Config server</strong>. All secrets, tokens, credentials, and infrastructure descriptors live here, in a private Git repository accessible only to the owner.</p> </div> <div class="paragraph"> <p>Why a separate repository rather than a`.env`file in each project?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Accidental secret push</strong>: impossible. Secrets are in a private repository that public projects cannot reference by mistake.</p> </li> <li> <p><strong>Audit</strong>: the Git history provides the trail for every configuration change. Who changed what, when, with which SHA hash.</p> </li> <li> <p><strong>Rollback</strong>:`git revert`on a broken configuration. Instantaneous, without manual backup.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_the_library_office_as_consumable_data">The Library: <code>office/</code> as Consumable Data</h3> <div class="paragraph"> <p>`office/`is the documentary counterpart to the development work. It contains blog articles, technical specifications, training materials (38 course directories for FPA, SPG/SPD, JSON schemas, Bloom/Harrow/Krathwohl taxonomies) — everything that constitutes the<strong>pedagogical material</strong>.</p> </div> <div class="paragraph"> <p>But`office/`is not just a doc drawer. It is a<strong>structured data source</strong>that the Gradle plugins of`foundry/`consume. A blog article in`office/`is an entry that a plugin will transform into HTML. An AsciiDoc SPG in`office/metiers/FPA/`is an artifact that an orchestrator will parse to generate slides, quizzes, and video capsules.</p> </div> <div class="paragraph"> <p>Et le `build.gradle.kts`at the root of`office/`is not business code — it is a<strong>consumption script for the plugin ecosystem</strong>. It says: "here are the Gradle plugins I use, here is the context of my workspace".</p> </div> </div> <div class="sect2"> <h3 id="_the_forges_foundry_as_implementation">The Forges: <code>foundry/</code> as Implementation</h3> <div class="paragraph"> <p><code>foundry/`contains the<strong>industrialized code</strong>. 54 Git repositories, 7 of which are currently governed by</code>.agents/`. This is where the vision becomes executable — Gradle plugins, CI/CD, JUnit5 + Cucumber tests.</p> </div> <div class="paragraph"> <p>The relationship with`office/`is bidirectional:</p> </div> <div class="ulist"> <ul> <li> <p><code>office/</code>→<code>foundry/</code>: pedagogical data is the raw material that plugins consume.</p> </li> <li> <p><code>foundry/</code>→<code>office/</code>: plugins produce data that enriches`office/` — le `graph.json`of graphify-gradle, compiled slider decks, build reports.</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_procontra_spatial_alignment_vs_prompt_alignment">Pro/Contra: Spatial Alignment vs Prompt Alignment</h2> <div class="sectionbody"> <div class="paragraph"> <p>Let’s compare the two approaches.</p> </div> <div class="sect2"> <h3 id="_classical_approach_pre_prompt_alignment">Classical Approach: Pre-Prompt Alignment</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">Simple to implement. A block of text in the system prompt.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fragile in long context</strong>: the rule is drowned out after 80K tokens.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Works for general rules (tone, format).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non-verifiable</strong>: nothing prevents the LLM from violating the rule.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No need to rethink project architecture.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non-transferable</strong>: each repo redeclares the rules.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Purely declarative</strong>: the LLM knows it <strong>should</strong>, but nothing stops it.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_this_approach_spatial_ontology_alignment">This Approach: Spatial Ontology Alignment</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>Resilient in long context</strong>: the rule is in the file path, not in a distant prompt.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Initial infrastructure cost</strong>: structuring the workspace into circles takes time.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mechanically verifiable</strong>: a secret in`foundry/<code>is detectable by`git check-ignore</code>.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Requires discipline</strong>: a new contributor must understand the circles.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Transferable</strong>: a standard`AGENT.adoc`exposes the circles to any new project.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Only covers spatial constraints</strong> — code style remains in the prompt.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Security by design</strong>: a`git push`from`foundry/<code>cannot expose`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>Consumable by non-LLM agents</strong>: a Gradle orchestrator can route according to the circle.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>The main gain is not defensive (security, visibility) — it is<strong>creative</strong>. When the LLM works in a space structured by an ontology, it can do what no prompt allows it to: <strong>observe the delta</strong>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_relational_algebra_of_the_workspace_and_the_observable_delta">The Relational Algebra of the Workspace and the Observable Delta</h2> <div class="sectionbody"> <div class="paragraph"> <p>When the LLM traverses`foundry/<code>, it has a<strong>structured data lattice</strong>: nodes (plugins, files, tests, dependencies), typed edges (`import</code>, <code>depends_on</code>, <code>generates</code>, <code>tests</code>), composition and order relations (`training-gradle`extracts the repository →`slider-gradle`generates the slides →`capsule-gradle`assembles the video).</p> </div> <div class="paragraph"> <p>This algebra is written nowhere in plain text — but it is <strong>observable</strong>. Every`build.gradle.kts`exposes dependencies. Every`INDEX.adoc`exposes cross-references.</p> </div> <div class="paragraph"> <p>The LLM observes this algebra and detects the<strong>delta</strong>: the gap between what the system already knows how to produce and what the vision describes.</p> </div> <div class="paragraph"> <p>From this delta, it can define<strong>business expert mappings</strong>— CDA (Application Designer Developer, Kotlin/Gradle/JHipster) and FPA (Adult Professional Trainer, Pedagogy/Qualiopi/Bloom) — and identify what is missing for each expert.</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>The LLM does not need to be told what to do. The delta emerges from the structure.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_composite_context_vector_rag_pgvector_graphify">The Composite Context Vector: RAG + pgvector + Graphify</h2> <div class="sectionbody"> <div class="paragraph"> <p>Relational algebra is not a theoretical construction. It is <strong>materialized</strong> by three components that form a<strong>composite context vector</strong>for the LLM.</p> </div> <div class="sect2"> <h3 id="_component_1_rag_langchain4j_postgresql_pgvector">Component 1 — RAG LangChain4j + PostgreSQL pgvector</h3> <div class="paragraph"> <p>I already have LangChain4j in production in two plugins:`slider-gradle`(4 LLM providers) and`plantuml-gradle`(7 providers). ONNX embeddings (AllMiniLmL6V2) index the data from`office/`and the source code of`foundry/`in PostgreSQL + pgvector.</p> </div> <div class="paragraph"> <p>This RAG operates on two dimensions:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Data dimension</strong>: the`office/`documents (SPG, articles, training, JSON schemas)</p> </li> <li> <p><strong>Code dimension</strong>: the`foundry/`codebases (Kotlin sources, Cucumber tests, AGENT.adoc)</p> </li> </ul> </div> <div class="paragraph"> <p>The intersection covers both the <strong>what</strong> (the business domain) and the <strong>how</strong> (the implementation).</p> </div> </div> <div class="sect2"> <h3 id="_component_2_knowledge_graph_graphify">Component 2 — Knowledge Graph Graphify</h3> <div class="paragraph"> <p>Graphify is integrated into`plantuml-gradle`(109 tests, 380/380 PASS) and produces a`graph.json`— a structured knowledge graph with nodes, edges, and automatically detected communities.</p> </div> <div class="paragraph"> <p>Unlike RAG, which operates via vector similarity (fuzzy), the knowledge graph operates via<strong>exact relations</strong>(deterministic):`graphify query`for semantic queries (~50 tokens),`graphify path`for navigation,`graphify explain`for explanation.</p> </div> </div> <div class="sect2"> <h3 id="_component_3_incremental_graphify_sparse_aggregatable_consumable">Component 3 — Incremental Graphify: Sparse, Aggregatable, Consumable</h3> <div class="paragraph"> <p>This is the key architectural decision.</p> </div> <div class="paragraph"> <p>Graphify must not live in a single repository. It must live in a<strong>sparse</strong>manner across each plugin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Each plugin</strong> carries a Gradle task`updateKnowledgeGraph`that calls Graphify<strong>on its own scope</strong>and produces a`graph.json`local.</p> </li> <li> <p><strong>The build script of`office/<code></strong> consumes`graphify-gradle`with`rootDir = /home/cheroliv/workspace`and produces a`graph.json</code> <strong>global</strong>that aggregates the local graphs.</p> </li> <li> <p><strong>The RAG of each plugin</strong> injects the`graph.json`global as a<strong>context filter</strong>for LLM queries.</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>Result: the LLM does not search in a vacuum — it navigates in a space structured by the knowledge graph. A query on "generate a diagram" knows how to reach the relevant nodes of the graph.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_automatic_gdpr_classification_the_llm_as_router">Automatic GDPR Classification: the LLM as Router</h2> <div class="sectionbody"> <div class="paragraph"> <p>Spatial ontology doesn’t just align the LLM — it gives it a<strong>GDPR classification grid</strong>to route each piece of data to its legitimate zone.</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">Criterion</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LLM Detection</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Action</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Max Level</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Personal data (name, email, IP)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pattern`@`, IP, proper names</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonymize →`[OF_PILOTE]`or route level 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 / Secret / Credential</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pattern`sk-…​<code>, `ghp_…​</code>, <code>ya29…​</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Route →<code>configuration/</code>. Reference by`${VAR}`in code.</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">Internal URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contains`localhost`, private IP</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonymize →<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">Pedagogical data (SPG, course)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bloom/Qualiopi structure</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Route →<code>office/</code>(level 2). Double version if export.</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">Source code / test</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extension`.kt`, <code>.kts`in`foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Route →<code>foundry/</code>. Verify absence of secrets.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>At the end of a session, the LLM executes a<strong>global task</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Read the`.gitignore`root to identify ephemeral artifacts (to exclude from snapshot) vs strategic artifacts (to historize)</p> </li> <li> <p>Inventory of all`.adoc`files of the root`workspace/`</p> </li> <li> <p>Filtering: exclusion of files listed in`.gitignore`, inclusion of all others</p> </li> <li> <p>Copy to`configuration/vision-archive/$DATE/<code>and update the symlink`latest/</code></p> </li> <li> <p>Commit to the`configuration/`repository with a structured message</p> </li> <li> <p>Automatic GDPR classification of each modified file (all circles)</p> </li> <li> <p>Routing:`office/<code>data → private commit,`foundry/`code →</code>./gradlew check`, configuration → commit</p> </li> <li> <p>Structured report with GDPR alerts and archiving confirmation</p> </li> </ol> </div> <div class="paragraph"> <p>Le `.gitignore`root is not a Git configuration file — it is a<strong>history governance file</strong>. It defines the schema that the LLM consumes to decide which secret garden files enter the strategic biography and which are disposable.</p> </div> <div class="paragraph"> <p>The LLM is no longer a simple text generator. It is the<strong>information manager</strong>of the ecosystem — producer, classifier, router.</p> </div> </div> </div> <div class="sect1"> <h2 id="_roadmap_from_asciidoc_to_langgraph4j">Roadmap: from AsciiDoc to LangGraph4j</h2> <div class="sectionbody"> <div class="paragraph"> <p>Today, this governance is <strong>deterministic</strong>: the LLM applies a procedure described in AsciiDoc files. This is<strong>phase 1</strong>— prompt engineering with LLM memory.</p> </div> <div class="paragraph"> <p>La <strong>phase 2</strong>will extract each step of the procedure into a<strong>typed Gradle task</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>phase 3</strong>will model the end-of-session process as a<strong>state graph</strong>withhttps://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>This graph will be versioned in CI/CD, executed by Gradle, and configured via plugin GitHub Secrets. The LLM will no longer have to decide the routing — the graph will do it.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_this_architecture_solves_and_what_it_doesnt_solve">What This Architecture Solves (and what it doesn’t Solve)</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>Spatial ontology doesn’t cover everything. Code style conventions, naming, architectural design choices — all that remains in the prompt. What spatial ontology solves is the<strong>security and visibility layer</strong>: where every byte must live, and who can see it.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Here is what it brings concretely:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>No accidental`git push`of a secret</strong>: secrets are in`configuration/<code>(circle 1). Public projects are in`foundry/</code>(circle 4). No path crosses both.</p> </li> <li> <p><strong>No business code in data</strong>:`office/<code>contains</code>.adoc`, YAMLs, JSON Schemas — but no`.kt`. Le `build.gradle.kts`that lives there is a consumption script, not business code.</p> </li> <li> <p><strong>No exposed strategic thought</strong>: vision documents live in the secret garden (out-of-CVS root). Snapshots are in`configuration/`(private vault). No one, even in the extended circle of trust, reads the genesis of the strategy.</p> </li> <li> <p><strong>Auto-prioritization</strong>: the LLM observes the delta between the relational algebra (what exists) and the expert mappings (what is necessary). The next development task emerges from this delta.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_architecture_as_discourse">Conclusion: Architecture as Discourse</h2> <div class="sectionbody"> <div class="paragraph"> <p>I don’t put a political manifesto in my site’s footer. I don’t put ethical rules in my prompts. Alignment is not in the text — it is in the<strong>file system</strong>.</p> </div> <div class="paragraph"> <p>When an LLM works in this space, it cannot leak a secret (the path prevents it). It cannot confuse pedagogical data with source code (the physical zone is different). It cannot forget a security rule at 80,000 tokens — because the rule is not in the prompt, it is in the`workspace/<code>→`configuration/</code>→<code>office/</code>→`foundry/`that every file read reactivates.</p> </div> <div class="paragraph"> <p>This is the principle of <strong>secure by design</strong> applied to agent alignment: do not ask the LLM to remember the rules. Make the architecture render the error structurally impossible.</p> </div> <div class="paragraph"> <p>And in the process, it gives the LLM something no prompt can: the ability to<strong>perceive</strong>where it is, what exists, what is missing — and deduce what it must do.</p> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Article on Eager/Lazy agent governance:<a href="../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Governing an AI Agent with AsciiDoc</a></p> </li> <li> <p>Article on the Hot/Warm/Cold mechanism:<a href="../2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window and Cold Wave</a></p> </li> <li> <p>Article on context audit:<a href="../2026/0111_audit_contexte_agent_post.html">When Your Own Governance Becomes the Problem</a></p> </li> <li> <p>Article on the comparison of the three 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/en/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="#_the_scene_a_form_that_stores_nothing">The Scene: A Form That Stores Nothing</a> <ul class="sectlevel2"> <li><a href="#_the_supabase_legacy">The Supabase Legacy</a></li> <li><a href="#_the_phantom_double_submission">The Phantom Double Submission</a></li> </ul> </li> <li><a href="#_why_firebase_instead_of_supabase">Why Firebase instead of Supabase?</a></li> <li><a href="#_phase_1_creating_the_firebase_project">Phase 1: Creating the Firebase Project</a> <ul class="sectlevel2"> <li><a href="#_initialization">Initialization</a></li> <li><a href="#_firestore_security_rules">Firestore Security Rules</a></li> </ul> </li> <li><a href="#_phase_2_rewriting_the_submission_javascript">Phase 2: Rewriting the Submission JavaScript</a> <ul class="sectlevel2"> <li><a href="#_the_window_firebase_dependency">The <code>window.<em>FIREBASE</em></code> dependency</a></li> <li><a href="#_the_new_contact_js">The new <code>contact.js</code></a></li> </ul> </li> <li><a href="#_phase_3_cleaning_up_dead_supabase_code">Phase 3: Cleaning up dead Supabase code</a></li> <li><a href="#_remains_intact">remains intact:</a></li> <li><a href="#_not_the_api_key_do_not_put_it_in_a">, not the API key. Do not put it in a</a></li> <li><a href="#_loaded_server_side_it_is_intended_to_be_exposed_to_the_browser">loaded server-side — it is intended to be exposed to the browser.</a> <ul class="sectlevel2"> <li><a href="#_the_fact_of_having_dragged_a_mock_for_months_entire_sessions_where_the_form_lied_silently_made_me_realize_something_the_backlog_of_a_personal_static_site_is_never_finished_there_is_always_a_priority_us_always_a_draft_article_always_a_commented_out_section_in_a_template_discipline_is_not_about_finishing_everything_its_about_finishing_what_is_visible_to_the_user">The fact of having dragged a mock for months (entire sessions where the form lied silently) made me realize something: the backlog of a personal static site is never "finished". There is always a priority US, always a draft article, always a commented-out section in a template. Discipline is not about finishing everything — it’s about finishing what is visible to the user.</a></li> </ul> </li> <li><a href="#_replacement_of_placeholder_config_real_values">Replacement of placeholder config → real values</a></li> <li><a href="#_a_playwright_test_that_submits_the_form_and_verifies_that_the_document_appears_in_firestore_for_now_i_test_manually_via">: A Playwright test that submits the form and verifies that the document appears in Firestore. For now, I test manually via</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 12 minutes</div> <p>For months, this site’s contact form ran on a JavaScript mock — a promise with an 85% success rate, a fake Firestore, zero stored data. The initial plan involved a Supabase backend with Google Apps Script for email notifications. Abandoned. Today, I describe the migration to Firebase Firestore: project creation, security rules, rewriting the JS, cleaning up dead Supabase code. And why this choice says something broader about development philosophy.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_a_form_that_stores_nothing">The Scene: A Form That Stores Nothing</h2> <div class="sectionbody"> <div class="paragraph"> <p>This site is generated by JBake, my Gradle plugin`bakery`. It is 100% static — no backend, no database. Except that I have a contact form. The page`contact.html`exists, the HTML is ready (name, email, phone, subject, message fields, HTML5 validation, anti-spam honeypot), and the Bootstrap styles are in place. Visually, everything is perfect.</p> </div> <div class="paragraph"> <p>Except that upon submission, nothing happens.</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>A mock. A promise that pretends. The user sees a spinner, then a "Message sent successfully!" message. But the data goes into a void. No message is stored anywhere.</p> </div> <div class="paragraph"> <p>The situation is worse than a broken form — it is a form that lies.</p> </div> <div class="sect2"> <h3 id="_the_supabase_legacy">The Supabase Legacy</h3> <div class="paragraph"> <p>The initial plan, documented in`content/draft/integration_formulaire_contact_supabase.adoc`, provided for:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>A Supabase database with a`contacts`table and Row Level Security</p> </li> <li> <p>A server-side`handle_contact_form`RPC</p> </li> <li> <p>A SQL trigger calling a Google Apps Script webhook</p> </li> <li> <p>Google Apps Script that sends a Gmail notification email</p> </li> </ol> </div> <div class="paragraph"> <p>The corresponding JavaScript code still exists in`script.js`. There is a`SupabaseManager`class that initializes a Supabase client with`SUPABASE_URL` et <code>SUPABASE_KEY`global variables, and a`ContactFormHandler`class that listens for the form submit event and calls`SupabaseManager.submitContactForm()</code>.</p> </div> <div class="paragraph"> <p>Problem: these global variables are no longer injected into the footer. The`<script src="supabase-js">`has been removed. The code calls`supabase.createClient()`on a`supabase`variable that no longer exists. Therefore:</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>Not only is the data not stored, but the submission code is dead.</p> </div> </div> <div class="sect2"> <h3 id="_the_phantom_double_submission">The Phantom Double Submission</h3> <div class="paragraph"> <p>To make matters worse, there is a<strong>silent competition</strong>between two handlers on the same form:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>`contact.js`listens for submit, calls the Firebase mock</p> </li> <li> <p><code>script.js</code>— via`ContactFormHandler`— also listens for submit, calls`SupabaseManager`</p> </li> </ol> </div> <div class="paragraph"> <p>Both perform`event.preventDefault() + event.stopPropagation()<code>. Since`contact.js`is loaded first in`footer.thyme</code>, its handler is attached first. It blocks propagation.`ContactFormHandler`will never be triggered.</p> </div> <div class="paragraph"> <p>This isn’t even an active bug — it’s a zombie. Code that never gets the chance to execute.</p> </div> <div id="diag-before" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1dca60606b3e7ccf37af78f090e4df27.svg" alt="État initial — double handler et mock" width="1972" height="215"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_firebase_instead_of_supabase">Why Firebase instead of Supabase?</h2> <div class="sectionbody"> <div class="paragraph"> <p>The migration decision is documented in`AGENT.adoc`:</p> </div> <div class="paragraph"> <p>Firebase is now chosen for the following reasons: better free plan, native Firestore, integrated Cloud Functions, more suitable Google ecosystem. The existing Supabase implementation is marked "⚠️ Abandoned".</p> </div> <div class="paragraph"> <p>Beyond the free plan, there is an architectural reason. This site lives in the Google ecosystem: the target repository is`cheroliv.github.io`, the CNAME points to GitHub Pages, the Gradle build pushes to GitHub via JGit. Adding a Google service (Firebase) rather than a third-party service (Supabase) reduces the dispersion surface.</p> </div> <div class="paragraph"> <p>Firestore in native mode (not Datastore mode) is also closer to the NoSQL document mental model I have in mind: collections, documents, typed fields, server timestamps, built-in security rules.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_1_creating_the_firebase_project">Phase 1: Creating the Firebase Project</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_initialization">Initialization</h3> <div class="paragraph"> <p>Since the Firebase CLI is not installed on my machine, I use the web console:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Go tohttps://console.firebase.google.com/[Firebase Console]</p> </li> <li> <p>Create a project`cheroliv-contact`(or reuse an existing project)</p> </li> <li> <p>Activate Firestore in native mode (not Datastore)</p> </li> <li> <p>Create a database in the`eur3`(Europe) region</p> </li> </ol> </div> <div class="paragraph"> <p>For a minimalist use case like ours (a single collection, public write), native mode is the right choice. No need for complex Datastore rules.</p> </div> </div> <div class="sect2"> <h3 id="_firestore_security_rules">Firestore Security Rules</h3> <div class="paragraph"> <p>The form is public — anyone can send a message. But I want to limit abuse:</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>Key points:</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code>— only authenticated users can read messages (me, via the Firebase console)</p> </li> <li> <p><code>allow create</code>— anyone can create a document, but with field validation</p> </li> <li> <p>Server-side validation: min/max sizes, email format,<code>created_at`must match`request.time</code>(anti-spoofing)</p> </li> <li> <p>`user_agent`is sent for traceability (not critical but useful)</p> </li> </ul> </div> <div class="paragraph"> <p>These rules are stricter than a simple`allow write: if true;`. They prevent an attacker from injecting huge payloads or malformed fields.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_rewriting_the_submission_javascript">Phase 2: Rewriting the Submission JavaScript</h2> <div class="sectionbody"> <div class="paragraph"> <p>The contract is simple:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Read form data</p> </li> <li> <p>Check the honeypot (field`hp_name`— if it is filled, it’s a bot; we simulate success without sending anything)</p> </li> <li> <p>Call`addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})`</p> </li> <li> <p>Display success or error</p> </li> </ol> </div> <div class="sect2"> <h3 id="_the_window_firebase_dependency">The <code>window.<em>FIREBASE</em></code> dependency</h3> <div class="paragraph"> <p>In`footer.thyme`, a module script initializes the Firebase SDK and exposes a global object:</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>Module scripts execute before`DOMContentLoaded`, so`window.<em>FIREBASE</em>`is guaranteed to be available when the`contact.js`handler triggers. As a precaution, I still add a 5-second polling in case the CDN is slow.</p> </div> </div> <div class="sect2"> <h3 id="_the_new_contact_js">The new <code>contact.js</code></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>Changes compared to the mock:</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code>— polling with timeout, robust even if the CDN is slow</p> </li> <li> <p><code>honeypot</code>— if the hidden field`hp_name`is filled, simulate success without a Firestore call. The bot thinks it succeeded, but nothing is stored</p> </li> <li> <p><code>addDoc(collection, {…​})</code>— real Firestore call with`serverTimestamp()` et <code>user_agent</code></p> </li> <li> <p>Error handling with`try/catch`asynchronous</p> </li> <li> <p>Cleanup of the`finally`(button restoration)</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>Why`user_agent`? It’s optional, but useful for diagnostics. If a strange message arrives, knowing if it comes from a desktop browser, mobile, or a curl script helps with sorting.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_3_cleaning_up_dead_supabase_code">Phase 3: Cleaning up dead Supabase code</h2> <div class="sectionbody"> <div class="paragraph"> <p>`script.js`contains 250 lines of dead code:</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code>(lines 417-481) — 65 lines</p> </li> <li> <p><code>ContactFormHandler</code>(lines 490-551) — 62 lines</p> </li> <li> <p>Initialization block (lines 645-654) — 10 lines</p> </li> </ul> </div> <div class="paragraph"> <p>Total: ~140 lines to delete.</p> </div> <div class="paragraph"> <p>The`DOMContentLoaded`block creates a`SupabaseManager`then a`ContactFormHandler`attached to the form. As explained above, this code never executes (blocked by`contact.js`), and even if it did, it would fail (no Supabase SDK loaded).</p> </div> <div class="paragraph"> <p>I delete:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The`SupabaseManager`</p> </li> <li> <p>class`ContactFormHandler`</p> </li> <li> <p>The`DOMContentLoaded`class</p> </li> </ol> </div> <div class="paragraph"> <p>Le reste de <code>script.js`The initialization block in`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>(lines 645-654)</p> </div> </div> </div> <div class="sect1"> <h2 id="_remains_intact">remains intact:</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>footer.thyme</code>.</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>Phase 4: Configuring the Footer<strong>already has the Firebase boilerplate but with placeholder values. I replace them:</strong>With the actual values retrieved from</p> </div> <div class="paragraph"> <p>Project Settings > General > Your apps > Web app`apiKey`in the Firebase console.<code>site.yml`The values are sensitive (</code>.gitignore`is public by design in Firebase, but I prefer not to commit them in plain text). I store them in`bakery`(already in</p> </div> <div class="paragraph"> <p>) and the`footer.thyme`plugin injects them into the template via logic to be added to the build side.<code>./gradlew serve`For now, I put them directly in`site.yml</code>— the</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`build will load them locally. Upon deployment, I will migrate the injection to<strong>or to a Gradle variable.</strong>Firebase API keys are<strong>not</strong>a secret. They are public by design. What protects your data are the`.env`Firestore security rules</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_not_the_api_key_do_not_put_it_in_a">, not the API key. Do not put it in a</h2> <div class="sectionbody"> <div id="diag-after" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-97da02b2e5039b13e18110950d9d0e1b.svg" alt="Architecture finale — Firebase Firestore" width="512" height="505"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_loaded_server_side_it_is_intended_to_be_exposed_to_the_browser">loaded server-side — it is intended to be exposed to the browser.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Phase 5: Final Architecture`bakery`What this migration says about dogfooding`AGENT.adoc`This site is generated by my own Gradle plugin`./gradlew serve`. The contact form lives inside the site. The Supabase → Firebase migration is documented in</p> </div> <div class="paragraph"> <p>, it is discussed in the backlog, it is tested via</p> </div> <div class="paragraph"> <p>, and it generates a blog post (the one you are reading).</p> </div> <div class="paragraph"> <p>This is pure dogfooding. The site is the product of the plugin, the plugin is the product of the developer, the developer documents the process within the site itself.</p> </div> <div class="paragraph"> <p>The loop is closed.</p> </div> <div class="sect2"> <h3 id="_the_fact_of_having_dragged_a_mock_for_months_entire_sessions_where_the_form_lied_silently_made_me_realize_something_the_backlog_of_a_personal_static_site_is_never_finished_there_is_always_a_priority_us_always_a_draft_article_always_a_commented_out_section_in_a_template_discipline_is_not_about_finishing_everything_its_about_finishing_what_is_visible_to_the_user">The fact of having dragged a mock for months (entire sessions where the form lied silently) made me realize something: the backlog of a personal static site is never "finished". There is always a priority US, always a draft article, always a commented-out section in a template. Discipline is not about finishing everything — it’s about finishing what is visible to the user.</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">A broken contact form is worse than no form at all. It is a broken promise.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Summary of changes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">File</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">Modification</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Impact</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">Article creation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentation</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">Rewriting (mock → real Firestore)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Functional</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">Removal of SupabaseManager + ContactFormHandler + init block</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cleanup</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_replacement_of_placeholder_config_real_values">Replacement of placeholder config → real values</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Configuration</strong>Next steps (backlog)<code>onCreate`Email notification`contact_messages</code>: A Cloud Function</p> </li> <li> <p><strong>on</strong>that sends an email via SendGrid. The form stores data, but I am not notified. Medium priority — messages are visible in the Firebase console.</p> </li> <li> <p><strong>Client-side rate limiting</strong>: Add a localStorage timestamp to prevent rapid multiple submissions. The honeypot blocks naive bots; a rate limiter would block slightly smarter bots.`./gradlew serve`Tests</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_a_playwright_test_that_submits_the_form_and_verifies_that_the_document_appears_in_firestore_for_now_i_test_manually_via">: A Playwright test that submits the form and verifies that the document appears in Firestore. For now, I test manually via</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://firebase.google.com/docs/firestore/security/get-started">.</a></p> </li> <li> <p><a href="https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document">References</a></p> </li> <li> <p><a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Firestore Security Rules Documentation</a></p> </li> <li> <p><a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Firestore addDoc Documentation — Modular Web v9</a></p> </li> <li> <p><a href="/blog/2026/0111_audit_contexte_agent_post.html">Agent Governance Series — Part 1: Eager/Lazy</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_context_not_a_test_bench_but_a_construction_site">Context: Not a test bench, but a construction site</a></li> <li><a href="#_my_test_environment">My test environment</a></li> <li><a href="#_the_evaluation_grid">The Evaluation Grid</a></li> <li><a href="#_round_1_kimi_k2_6_the_false_start">Round 1: Kimi K2.6 — The False Start</a> <ul class="sectlevel2"> <li><a href="#_session_9_the_honeymoon">Session 9: the honeymoon</a></li> <li><a href="#_session_10_the_silent_shipwreck">Session 10: the silent shipwreck</a></li> </ul> </li> <li><a href="#_round_2_glm_5_1_the_honorable_fighter">Round 2: GLM-5.1 — The Honorable Fighter</a> <ul class="sectlevel2"> <li><a href="#_architecture_dsa_vs_pure_mla">Architecture: DSA vs Pure MLA</a></li> <li><a href="#_sessions_11_13_solid_but_frustrating">Sessions 11-13: solid but frustrating</a></li> </ul> </li> <li><a href="#_round_3_deepseek_v4_pro_the_war_machine">Round 3: DeepSeek-V4-Pro — The War Machine</a> <ul class="sectlevel2"> <li><a href="#_architecture_csa_hca_the_double_safety_net">Architecture: CSA + HCA, the double safety net</a></li> <li><a href="#_sessions_1_8_the_relief">Sessions 1-8: the relief</a></li> <li><a href="#_the_decisive_test_refactoring_at_100k_tokens">The decisive test: refactoring at 100K tokens</a></li> </ul> </li> <li><a href="#_the_face_off_comparative_metrics">The Face-Off: Comparative Metrics</a></li> <li><a href="#_why_deepseek_v4_pro_wins_in_software_development">Why DeepSeek-V4-Pro Wins in Software Development</a> <ul class="sectlevel2"> <li><a href="#_1_the_csahca_architecture_is_tailored_for_code">1. The CSA+HCA architecture is tailored for code</a></li> <li><a href="#_2_eager_context_is_its_comfort_zone">2. EAGER context is its comfort zone</a></li> <li><a href="#_3_the_qualitylatency_ratio_is_optimal_for_flow">3. The quality/latency ratio is optimal for flow</a></li> </ul> </li> <li><a href="#_lessons_learned_how_to_choose_your_llm_for_vibe_coding">Lessons Learned: How to Choose Your LLM for Vibe Coding</a></li> <li><a href="#_and_what_about_agent_governance_in_all_this">And what about Agent Governance in all this?</a></li> <li><a href="#_technical_sources">Technical Sources</a></li> <li><a href="#_conclusion_the_artisans_choice">Conclusion: The Artisan’s Choice</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time : 18 minutes</div> <p>The LLM war is also fought in a developer’s terminal. Not on sterile academic benchmarks. In real life: a 30,000 token prompt, agent governance in AsciiDoc, Gradle Kotlin DSL plugins to debug, and sessions chaining over three weeks. I tested DeepSeek-V4-Pro, Kimi K2.6, and GLM-5.1 for you. Here is the verdict, with technical evidence.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_context_not_a_test_bench_but_a_construction_site">Context: Not a test bench, but a construction site</h2> <div class="sectionbody"> <div class="paragraph"> <p>Three weeks ago, I was working on`codebase-gradle`, my meta-build system that centralizes the YAML configuration of four projects: a PlantUML README generator, an AsciiDoc slide builder, a JBake static site, and an LLM chatbot. The Opencode agent, governed by my agent file methodology in AsciiDoc, loaded ~30K tokens of EAGER context at the start of each session — absolute rules, backlog, history of the last 10 sessions.</p> </div> <div class="paragraph"> <p>This is where I pitted three models against each other:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong>(Moonshot AI, 1T params / 32B activated, 256K max context, MLA) - <strong>GLM-5.1</strong>(Zhipu AI/Tsinghua, 744B params / DSA, 200K max context) - <strong>DeepSeek-V4-Pro</strong>(DeepSeek, 1.6T params / 49B activated, 1M max context, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>All served via Ollama on a cloud server, all in thinking mode (reflection phase enabled). The challenge: produce correct code, maintain consistency over long sessions, and not hallucinate when the context exceeds 80K tokens.</p> </div> </div> </div> <div class="sect1"> <h2 id="_my_test_environment">My test environment</h2> <div class="sectionbody"> <div id="diag-dev-env" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b1ac0f8f2064fca47d705e64ced8b52f.svg" alt="Environnement de développement — LLM + Opencode + Gradle" width="693" height="770"> </div> </div> <div class="paragraph"> <p>Each session started with approximately 30K tokens of EAGER context:`AGENT.adoc`(287 lines),<code>PROMPT_REPRISE.adoc</code>(51 lines),<code>.agents/INDEX.adoc</code>(218 lines),<code>LAZY_EAGER_ESSENTIALS.adoc</code>(50 lines). The context grew rapidly with exchanges — a typical 10-message session added 15-20K tokens to the cumulative prompt.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_evaluation_grid">The Evaluation Grid</h2> <div class="sectionbody"> <div class="paragraph"> <p>I evaluated each model on four critical axes for assisted software development:</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">Axis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Concrete Criterion</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Long-context consistency</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Does the agent remember conventions decided 40 messages ago?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Produced code quality</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Does the code compile on the first try? Does it respect existing patterns?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Architectural reasoning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Does the agent understand relations between modules without me re-explaining them?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Hallucination resistance</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">At how many tokens does the agent start inventing non-existent APIs or classes?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>And a home-made synthetic metric: the<strong>recovery coefficient</strong>(how much time I spend correcting the agent rather than coding with it).</p> </div> </div> </div> <div class="sect1"> <h2 id="_round_1_kimi_k2_6_the_false_start">Round 1: Kimi K2.6 — The False Start</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6 was my first choice. Its benchmarks on SWE-Bench Verified (80.2) and Terminal-Bench 2.0 (66.7) are excellent. Its MLA architecture promises good efficiency on long sequences.</p> </div> <div class="sect2"> <h3 id="_session_9_the_honeymoon">Session 9: the honeymoon</h3> <div class="paragraph"> <p>First session with Kimi. Task: implement the method`resolveActiveKey()<code>in`codebase.kt</code>— an API key resolution function with CLI fallback. Context is at 30K tokens, Kimi reasons quickly, produces clean code with key expiration management.</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>The code compiles. The 7 test cases pass. I am optimistic.</p> </div> </div> <div class="sect2"> <h3 id="_session_10_the_silent_shipwreck">Session 10: the silent shipwreck</h3> <div class="paragraph"> <p>Second session. Context climbs to ~90K tokens with exchanges. I ask Kimi to add an AsciiDoc snapshot mechanism that anonymizes secrets before writing.</p> </div> <div class="paragraph"> <p>This is where it goes wrong. Kimi starts inventing classes that don’t exist. He proposes`AnonymizedObjectMapper`— a fictitious class. He confuses`ReadmeYmlAnonymizer` et <code>CodebaseYmlAnonymizer</code>. He suggests importing`com.fasterxml.jackson.anonymize.*`— a package that never existed.</p> </div> <div class="paragraph"> <p>Worse: in its reflection phase, I see it building reasoning on false premises. It "remembers" that`GitConfig`has a field`anonymizedToken`— no, it’s`resolvedToken()<code>. It attributes to`SiteYmlAnonymizer`a method`maskSupabaseCredentials()</code>— which does not exist.</p> </div> <div class="paragraph"> <p><em><em>_ This wasn’t a bug. It was a progressive dissolution of coherence. As if each token added to the context further diluted the memory of the first 30,000. </em>_</em></p> </div> <div class="paragraph"> <p>I stop Kimi after two sessions. The diagnosis is clear: MLA compresses the KV cache well, but without a fine-grained sparse selection mechanism, attention mechanically dilutes beyond 60K tokens. Each token "sees" the distant context less and less — and begins to fill the gaps with noise.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_2_glm_5_1_the_honorable_fighter">Round 2: GLM-5.1 — The Honorable Fighter</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1 arrives with a different architecture: MLA for the base model, then <strong>continued pre-training</strong> with DSA (DeepSeek Sparse Attention) — a lightweight indexer that dynamically selects the top-2048 relevant tokens from the entire history.</p> </div> <div class="sect2"> <h3 id="_architecture_dsa_vs_pure_mla">Architecture: DSA vs Pure MLA</h3> <div class="paragraph"> <p>The difference is fundamental. Where Kimi compresses history into a single latent space (and progressively loses the ability to discriminate relevant information), GLM grafts a post-training indexer that performs explicit sparse selection.</p> </div> <div id="diag-mla-vs-dsa" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-96552207a44b513333686c1c93d0cef9.svg" alt="Comparaison architecture MLA (Kimi) vs MLA+DSA (GLM)" width="1074" height="364"> </div> </div> <div class="paragraph"> <p>The technical report states explicitly: DSA is <em>"lossless by construction"</em> — unlike alternatives like SWA (pattern search), Gated DeltaNet, or SimpleGDN which lose up to 5.69 pts on RULER@128K.</p> </div> </div> <div class="sect2"> <h3 id="_sessions_11_13_solid_but_frustrating">Sessions 11-13: solid but frustrating</h3> <div class="paragraph"> <p>GLM-5.1 holds the distance better. In session 11 (~60K tokens), it remains coherent. It produces a`SnapshotManager`that is functional with correct management of the four anonymizers.</p> </div> <div class="paragraph"> <p>But latency is an issue. DSA reflection phases are heavier than pure MLA — the indexer must rescan history at each step. A response that took 8 seconds with Kimi takes 15 with GLM. Over a 30-message session, it’s noticeable.</p> </div> <div class="paragraph"> <p>And then there are the subtle errors. GLM doesn’t rave like Kimi — but it makes <strong>naming</strong> errors. It calls`toAnonymizedYaml()<code>the method that should be called`anonymize()</code>. It reverses`loadReadmeConfiguration()` et <code>loadCodebaseConfiguration()`in the`renderFileSection()</code>. These aren’t hallucinations, they are surface confusions — but in production, a surface confusion can break a build.</p> </div> <div class="paragraph"> <p>I lasted three sessions with GLM. It is undeniably better than Kimi. But three sessions of manual correction on naming details is wearing.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_3_deepseek_v4_pro_the_war_machine">Round 3: DeepSeek-V4-Pro — The War Machine</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro arrives with the most ambitious architecture of the three: a hybrid system combining two complementary attention mechanisms.</p> </div> <div class="sect2"> <h3 id="_architecture_csa_hca_the_double_safety_net">Architecture: CSA + HCA, the double safety net</h3> <div id="diag-csa-hca" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-aad75fde6f9e97e39f6617b3b9f836d7.svg" alt="Architecture hybride CSA+HCA de DeepSeek-V4-Pro" width="741" height="459"> </div> </div> <div class="paragraph"> <p>Two levels of compression, two granularities of attention:</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong>: compresses the KV cache every`m`tokens, then applies sparse attention (DeepSeek Sparse Attention) — only the top-k of the compressed entries is consulted. Precise, local, efficient. - <strong>HCA</strong>: extreme compression (factor`m'`much larger than`m`), but dense attention on the compressed residue — keeps global connections without quadratic explosion.</p> </li> </ul> </div> <div class="paragraph"> <p>Result: at 1M tokens, DeepSeek-V4-Pro consumes only<strong>27% of inference FLOPs</strong> et <strong>10% of KV cache size</strong>compared to DeepSeek-V3.2, the previous model.</p> </div> <div class="paragraph"> <p>And above all, the technical report (Figure 9) announces: <em>"Retrieval performance remains highly stable within a 128K context window."</em></p> </div> </div> <div class="sect2"> <h3 id="_sessions_1_8_the_relief">Sessions 1-8: the relief</h3> <div class="paragraph"> <p>I spent eight sessions with DeepSeek-V4-Pro on`codebase-gradle`. Eight sessions without a single hallucination, without a single invented class, without a single naming confusion.</p> </div> <div class="paragraph"> <p>Session 1: implementation of`CodebaseYmlConfig` et <code>CodebaseYmlAnonymizer</code>. 350 lines of Kotlin, inline tests, everything compiles. Session 4: addition of the`SnapshotManager`with tree view, file collection, AsciiDoc rendering per file. 279 lines, zero errors. Session 7: debug of the`renderFileSection()`which had to handle four different types of anonymizers without resolution ambiguity. Resolved in three messages.</p> </div> <div class="paragraph"> <p>Latency is higher than Kimi — about 10-12 seconds per response in thinking mode. But the correction rate is nearly zero. I don’t spend my time repairing the agent’s errors. I code <strong>with</strong> it.</p> </div> </div> <div class="sect2"> <h3 id="_the_decisive_test_refactoring_at_100k_tokens">The decisive test: refactoring at 100K tokens</h3> <div class="paragraph"> <p>At session 8, the cumulative context exceeds 100K tokens. I ask for a heavy refactoring: extract the four inline verification tasks from`build.gradle.kts`to JUnit5 test files in`buildSrc/src/test/`.</p> </div> <div class="paragraph"> <p>The agent proposes a plan in three phases:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Create test classes with migration of existing cases</p> </li> <li> <p>Add JUnit5 and Kotest dependencies in`buildSrc/build.gradle.kts`</p> </li> <li> <p>Remove inline code from`build.gradle.kts`</p> </li> </ol> </div> <div class="paragraph"> <p>The plan is correct. The execution is clean. It even identifies an edge case I had missed: duplicate Jackson dependencies between`buildscript {}` et `buildSrc/build.gradle.kts`that must be unified during migration.</p> </div> <div class="paragraph"> <p>100K tokens of context, and the agent remembers that`CodebaseYmlAnonymizer.TOKEN_MASK`is`"<strong>*</strong>"`, that`GitConfig.resolvedToken()<code>is an extension function defined in`readme.kt</code>, and that`SnapshotManager.PRUNED_DIRS`excludes`build`, <code>.gradle</code> et <code>.git</code>.</p> </div> <div class="paragraph"> <p>That is the difference.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_face_off_comparative_metrics">The Face-Off: Comparative Metrics</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">Criterion</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">Max Context</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">Attention Mechanism</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pure MLA</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 hybrid</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Total Parameters</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">Activated Parameters</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">not published</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">Observed Degradation Threshold</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~60K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~120K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~128K tokens</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Behavior Beyond</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Massive Hallucinations</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Surface Confusions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slow progressive degradation</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NIAH Stability</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">not published</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">stable up to 128K (Figure 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">not published</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">not published</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">superior to Gemini 3.1 Pro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sessions held before abandonment</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 (and continuing)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Correction time / coding time</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">Average latency (think mode)</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">Confidence Coefficient*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">6/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9/10</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Confidence Coefficient = subjective measure of my ability to take the agent’s code and commit it without line-by-line review.</em></p> </div> <div id="diag-radar" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1ac33bab88740dda58ef1579a97513c4.svg" alt="Radar comparatif — Kimi K2.6 vs GLM-5.1 vs DeepSeek-V4-Pro" width="1135" height="844"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_deepseek_v4_pro_wins_in_software_development">Why DeepSeek-V4-Pro Wins in Software Development</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro’s superiority is not due to a single factor — it’s a convergence:</p> </div> <div class="sect2"> <h3 id="_1_the_csahca_architecture_is_tailored_for_code">1. The CSA+HCA architecture is tailored for code</h3> <div class="paragraph"> <p>Assisted software development is an <strong>extreme</strong> use case for long-context attention. You need: - Local precision (what does this class inherit from? where is this method defined?) →<strong>CSA</strong> - Global vision (why does this module exist? how do the four anonymizers interact?) →<strong>HCA</strong></p> </div> <div class="paragraph"> <p>Kimi with MLA alone handles local precision but loses global vision beyond 60K. GLM with DSA improves global vision but remains single-level. DeepSeek combines both explicitly.</p> </div> </div> <div class="sect2"> <h3 id="_2_eager_context_is_its_comfort_zone">2. EAGER context is its comfort zone</h3> <div class="paragraph"> <p>My governance system loads ~30K tokens of rules and backlog at startup. With a stable window up to 128K, DeepSeek has ~100K tokens of margin for session exchanges. This is 3 to 4 times more than what Kimi can handle without degradation.</p> </div> <div class="paragraph"> <p><em><em>_ The 128K window of perfect stability corresponds exactly to my needs: 30K EAGER + 70K exchanges = a productive session of 20-30 messages without ever leaving the green zone. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_3_the_qualitylatency_ratio_is_optimal_for_flow">3. The quality/latency ratio is optimal for flow</h3> <div class="paragraph"> <p>Yes, DeepSeek-V4-Pro is slower than Kimi (11s vs 8s). But the <strong>total</strong> time for a task is much lower because I don’t spend 20 minutes correcting the agent’s hallucinations.</p> </div> <div class="paragraph"> <p>The developer doesn’t measure response latency. They measure the time between "I ask the question" and "the code is in my repo and it works". On this metric, DeepSeek-V4-Pro is the fastest of the three.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lessons_learned_how_to_choose_your_llm_for_vibe_coding">Lessons Learned: How to Choose Your LLM for Vibe Coding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Beyond the point-in-time ranking, this experience taught me to evaluate an LLM for assisted software development based on criteria not found in any benchmark:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Look at the architecture, not the announced context size</strong>— A model that announces 256K context but only has MLA will end up like Kimi: theoretically capable, practically unusable beyond 60K.</p> </li> <li> <p><strong>Test on YOUR context, not on a generic benchmark</strong>— My initial 30K token AsciiDoc prompt with absolute rules and backlog has nothing to do with HLE or AIME questions.</p> </li> <li> <p><strong>Latency is not the enemy if quality follows</strong>— A slow model that produces correct code is faster than a fast model that produces wrong code.</p> </li> <li> <p><strong>Beware of models without a public technical report</strong>— If the team doesn’t document its attention architecture, it’s because they don’t trust its performance in long context.</p> </li> </ol> </div> <div id="diag-decision-tree" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-764212652633dc337e38e51de5fc291e.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="_and_what_about_agent_governance_in_all_this">And what about Agent Governance in all this?</h2> <div class="sectionbody"> <div class="paragraph"> <p>This experience validates a point I’ve defended since my article on Eager/Lazy governance:<strong>the quality of the LLM and the quality of the governance are multiplicative, not additive</strong>.</p> </div> <div class="paragraph"> <p>With Kimi K2.6, my governance was impeccable — but the model diluted the information. Result: perfect governance × hallucination = zero.</p> </div> <div class="paragraph"> <p>With DeepSeek-V4-Pro, EAGER governance (30K tokens of rules) + LAZY (session archives, technical references) + Hot/Warm/Cold (rotating backup) forms an ecosystem where each layer amplifies the other. The agent has the rules in sight (EAGER), can consult the history (LAZY), and the context never saturates (backup rotation).</p> </div> <div class="paragraph"> <p><em><em>_ A good LLM without governance is a Ferrari engine without a steering wheel. Good governance without a good LLM is a steering wheel without an engine. DeepSeek-V4-Pro + my agent governance = the first time I feel like I’m driving. </em>_</em></p> </div> <div class="paragraph"> <p>The rotating backup mechanism (rotation every 10 sessions or >500 EAGER lines) makes full sense with a model that holds 128K context: the sliding window of 10 active sessions keeps the context fresh without ever exceeding the degradation zone.</p> </div> </div> </div> <div class="sect1"> <h2 id="_technical_sources">Technical Sources</h2> <div class="sectionbody"> <div class="paragraph"> <p>I cross-referenced my empirical experience with official technical reports to validate my observations:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>DeepSeek-V4 Technical Report</strong> — PDF retrieved fromhttps://huggingface.co/deepseek-ai/DeepSeek-V4-Flash[HuggingFace]. Figure 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." CSA+HCA architecture documented in section 2.3.</p> </li> <li> <p><strong>GLM-5 Technical Report</strong> —https://arxiv.org/abs/2602.15763[arXiv:2602.15763]. DSA introduced via continued pre-training, "lossless by construction". Max context 202,752 tokens. Tables 3/5/6 document long-context performance vs alternatives (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 max context. Discard-all strategy beyond the threshold on agentic tasks (implicitly confirming the practical limit of MLA in long context).</p> </li> <li> <p><strong>Kimi K2 Technical Report</strong> —https://arxiv.org/abs/2507.20534[arXiv:2507.20534]. MoE architecture, MuonClip optimizer, agentic performance (HLE, BrowseComp, Terminal-Bench).</p> </li> </ol> </div> <div class="paragraph"> <p>The most revealing point: in their own evaluation, Moonshot applies a <strong>discard-all</strong> strategy (deleting old context) as soon as the context window is exceeded. This confirms exactly what I observed: MLA alone cannot maintain coherence across the entire 256K window. The architecture does not follow.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_artisans_choice">Conclusion: The Artisan’s Choice</h2> <div class="sectionbody"> <div class="paragraph"> <p>After three weeks and thirteen real development sessions, the verdict is final:</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">Excellent under 60K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solid up to 120K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dominates everywhere</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Unusable beyond</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Surface confusions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stable up to 128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 sessions, abandoned</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 sessions, abandoned</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 sessions, adopted</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek-V4-Pro has become my default LLM for all assisted software development sessions with Opencode. Not because it is the newest. Not because it has the best academic benchmarks. But because in the real life of a developer pushing Gradle Kotlin DSL plugins with a 30K token agent context, it is the only one that doesn’t betray me as the context lengthens.</p> </div> <div class="paragraph"> <p>CSA+HCA is an architectural <strong>game changer</strong>. Double-level compression + sparsification is not an implementation detail — it’s what makes the difference between a code assistant and a reliable teammate.</p> </div> <div class="paragraph"> <p><em><em>_ I chose DeepSeek-V4-Pro because it is the only one of the three that transforms my agent governance from a defensive constraint ("how to prevent the agent from forgetting?") into an offensive advantage ("what can we build now that the agent remembers everything?"). </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>This article is the result of 13 real development sessions on project`codebase-gradle`, documented in`.agents/sessions/`according to my Eager/Lazy/Hot/Warm/Cold agent governance methodology. The technical sources cited are publicly accessible on HuggingFace and arXiv.</strong></p> </div> </div> </div> https://cheroliv.com/en/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="#_the_scene_session_051_something_is_wrong">The scene: session 051, something is wrong</a></li> <li><a href="#_the_audit_dissecting_the_627_lines">The audit: dissecting the 627 lines</a></li> <li><a href="#_the_fear_of_losing_engineering">The fear of losing engineering</a></li> <li><a href="#_the_solution_encyclopedic_split">The solution: encyclopedic split</a></li> <li><a href="#_the_contents_of_the_essentials_file">The contents of the ESSENTIALS file</a></li> <li><a href="#_the_result_50_eager_context">The result: -50% EAGER context</a></li> <li><a href="#_why_the_folder_is_called_encyclopedies">Why the folder is called <code>encyclopedies/</code></a></li> <li><a href="#_the_logical_next_step_in_the_series">The logical next step in the series</a></li> <li><a href="#_what_i_would_have_done_differently">What I would have done differently</a></li> <li><a href="#_the_guide_to_auditing_your_own_context">The guide to auditing your own context</a></li> <li><a href="#_a_living_governance">A living governance</a></li> <li><a href="#_links">Links</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time : 14 minutes</div> <p>You spent weeks building impeccable agent governance. Eager/Lazy, end-of-session procedures, rotating backups. The system is running. Then one day, the agent becomes slow. Responses are diluted. You measure: 1414 lines loaded automatically. And the worst part is that the culprit isn’t the code, nor the backlog, nor the session archives. The culprit is the file documenting your method.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_session_051_something_is_wrong">The scene: session 051, something is wrong</h2> <div class="sectionbody"> <div class="paragraph"> <p>April 30, 2026, 4:00 PM. I am in the middle of a session on`magic-stick`, my Linux live ISO build project. The Opencode agent automatically loaded my Eager files as usual —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Everything is normal.</p> </div> <div class="paragraph"> <p>Except the responses are sluggish. The agent takes two seconds longer to reason. It forgets a detail it had right in front of it three messages ago. It’s not a crash, not an error — it’s a slow degradation, the kind you don’t notice immediately.</p> </div> <div class="paragraph"> <p>I had already experienced this in session 048, when I discovered that the governance files totaled 5200 lines. I had then conceptualized the Hot/Warm/Cold mechanism with its 10-session sliding window, its identical cold waves, and its two-trigger sensor. The problem was solved. In theory.</p> </div> <div class="paragraph"> <p>But now, we are at session 051. The backup rotation took place — EAGER files went from 2087 to 500 lines. Yet, the context remains heavy. Something is escaping me.</p> </div> <div class="paragraph"> <p>I open a terminal and type:</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 lines. The backup rotation effectively trimmed INDEX, SESSIONS_HISTORY, and COMPLETED_TASKS — they are clean. But there is an elephant in the room I hadn’t seen:<strong>627 lines</strong>in a single file.<code>AGENT_MODUS_OPERANDI.adoc</code>.</p> </div> <div class="paragraph"> <p>This file is the one I wrote in session 1 to document the Eager/Lazy strategy. It’s the method manual. And it has become, on its own, 44% of the EAGER context.</p> </div> <div id="diag-before-audit" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-055a31fdef8c78e522a1ab22c6f74925.svg" alt="Répartition des 1414 lignes EAGER avant audit" width="721" height="200"> </div> </div> <div class="paragraph"> <p>The irony is complete. The file designed to <strong>save</strong> context has become the primary <strong>consumer</strong> of context. It’s as if your car’s owner’s manual weighed more than the engine.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_audit_dissecting_the_627_lines">The audit: dissecting the 627 lines</h2> <div class="sectionbody"> <div class="paragraph"> <p>I decide to do a section-by-section audit. Not to delete — but to <strong>understand</strong> what deserves to be in EAGER and what could live elsewhere without loss of knowledge.</p> </div> <div class="paragraph"> <p>Here is the exact structure of`AGENT_MODUS_OPERANDI.adoc`and what I find there:</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">Section</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lines</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Content</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Already present in…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — Overview</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">Problem solved, fundamental principles, dashboard vs manual analogy</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 — File Structure</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">Tree structure, loading policy, when to load what</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 — Absolute Rules</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 forbidden, destructive commands forbidden, secrets forbidden</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 — Session Lifecycle</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">Opening template, work rules, 6 end-of-session steps, checklist</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>§End session +<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — Metrics and Thresholds</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">Ideal session (15-30 min, 1-3 files), warning signs</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 — Session Types</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">Detection table, proposal format, exceptions</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 — Continuous Improvement</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">Tracking metrics, weekly review</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 — Startup Checklist</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">New project 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 — References</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">Reference files, external resources</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>(EAGER/LAZY files)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Appendices 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">Glossary, version history</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The verdict is unequivocal:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Full Duplicates</strong>(167 lines): P3, P4, P9 — everything is already in`AGENT.adoc` ou <code>INDEX.adoc</code>, often word for word</p> </li> <li> <p><strong>Never consulted in practice</strong>(215 lines): P5, P6, P7, P8, Appendices — meta-governance that has never been used in any session</p> </li> <li> <p><strong>Unique Knowledge</strong>(161 lines): P1 and P2 — the LAZY/EAGER vocabulary, the analogy, the loading policy</p> </li> </ul> </div> <div class="paragraph"> <p>Out of 627 lines,<strong>382 are noise</strong>. And these 382 lines are loaded <strong>at the start of every session</strong>, consumed by the agent, diluting its attention before I even say hello.</p> </div> <div id="diag-audit-result" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-e3ec2f50f58c8bbd108e7f63232946be.svg" alt="Résultat de l’audit — 627 lignes réparties en doublons, jamais consulté, connaissance unique" width="514" height="665"> </div> </div> <div class="paragraph"> <p>This diagram is the key to everything. The duplicates (yellow) are pure noise — the agent reads them twice, in two different files. The never-consulted (red) is dead documentation — carefully written, never used. Only the green contains knowledge the agent cannot find elsewhere.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_fear_of_losing_engineering">The fear of losing engineering</h2> <div class="sectionbody"> <div class="paragraph"> <p>At this stage, the evidence is before my eyes: I must reduce`AGENT_MODUS_OPERANDI.adoc`. But I hesitate.</p> </div> <div class="paragraph"> <p>I wrote this file by hand. Each section is the result of a lesson learned in a real session. Part P3 was born from an`rm -rf`accidental on`bakery-plugin`that cost me real Firebase tokens. Part P4 is the result of fifteen sessions where I forgot to archive and lost the thread. The 6-step procedure didn’t come from a book — it came from pain.</p> </div> <div class="paragraph"> <p>Deleting these sections would be throwing away the history of my own engineering. The lessons that produced them, the sessions during which I discovered them, the mistakes I never want to make again. This isn’t text — it’s crystallized experience.</p> </div> <div class="paragraph"> <p>That’s where I formulate the principle that will guide the solution:</p> </div> <div class="paragraph"> <p><em><em>_ <strong>Never delete. Always relocate.</strong>Knowledge does not have to disappear from the project. It just shouldn’t be loaded automatically when it is not necessary. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_encyclopedic_split">The solution: encyclopedic split</h2> <div class="sectionbody"> <div class="paragraph"> <p>The model I propose is simple and inspired by how Wikipedia grew: when an article becomes too long, you don’t cut it — you create a detailed article and keep a summary in the main article.</p> </div> <div class="paragraph"> <p>For`AGENT_MODUS_OPERANDI.adoc`, this means:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Extract</strong>the 161 lines of unique knowledge (P1 + P2) into a new file`LAZY_EAGER_ESSENTIALS.adoc`— compacted to ~50 lines, strictly EAGER</p> </li> <li> <p><strong>Rename</strong> <code>AGENT_MODUS_OPERANDI.adoc</code> en <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code>— the original 627-line file, preserved <strong>intact</strong>, in cold storage</p> </li> <li> <p><strong>Never load</strong>the encyclopedia file automatically — it is there for the human, for future distillation, for the agent we will summon in six months with a better model</p> </li> </ol> </div> <div id="diag-split-solution" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1ca7b1421a06e9049df1c3513a7924d2.svg" alt="Architecture du split encyclopédique — ESSENTIALS EAGER + ENCYCLOPEDIE cold storage" width="762" height="530"> </div> </div> <div class="paragraph"> <p>The name`encyclopedies/`is not accidental. An encyclopedia is not an archive folder — it is a collection of organized knowledge, consultable but not portable. You don’t read the Encyclopædia Universalis on the subway. You keep it in the library, and you go there when you have a specific question.</p> </div> <div class="paragraph"> <p>That is exactly the role of this folder: a cold, structured, exhaustive reference library — that the agent does not touch automatically.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_contents_of_the_essentials_file">The contents of the ESSENTIALS file</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is what the new`LAZY_EAGER_ESSENTIALS.adoc`file looks like in practice, extracted and compacted from P1 and 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>Fifty lines. That’s all the agent needs to understand the mechanics. Everything else — the history of lessons, detailed analogies, step-by-step procedures, appendices — lives in the encyclopedia.</p> </div> <div class="paragraph"> <p>And most importantly:<strong>nothing was deleted</strong>. The 627 lines of engineering are still there, in`.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`. They are just stored in the library rather than on the workbench.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_result_50_eager_context">The result: -50% EAGER context</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before the 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>After the 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="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-4ca8c26a5cbdc6d1078c3680e6b90bec.svg" alt="Répartition des 837 lignes EAGER après audit — gain de 41%" width="687" height="230"> </div> </div> <div class="paragraph"> <p>The biggest consumer (AGENT_MODUS_OPERANDI, 627 lines) was replaced by a 50-line file. The gain is immediate: 577 lines of context freed. The agent can breathe.</p> </div> <div class="paragraph"> <p>And in`.agents/encyclopedies/`, the original 627-line file waits. Intact. With all its sections — including those that are duplicates, including those that were never used. Because one day, a better model or a human data scientist will want to cross-reference these angles, these intentional redundancies, these lessons learned. And on that day, the raw material will be there.</p> </div> </div> </div> <div class="sect1"> <h2 id="_why_the_folder_is_called_encyclopedies">Why the folder is called <code>encyclopedies/</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The choice of name is not cosmetic. It encodes the philosophy of the mechanism.</p> </div> <div class="paragraph"> <p>An <strong>archive</strong> (<code>archives/</code>) contains historical data organized chronologically — like the monthly COMPLETED_TASKS. A <strong>backup</strong> (<code>backup/</code>) is a timestamped snapshot — a safety copy of a past state.</p> </div> <div class="paragraph"> <p>An <strong>encyclopedia</strong> is something else. It is a collection of thematic knowledge, structured by subject, exhaustive but non-linear. You don’t read an encyclopedia from beginning to end. You dive in to answer a specific question.</p> </div> <div class="paragraph"> <p>That is exactly the contract of this folder:</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">Folder</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Role</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Access</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Granularity</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">Historical data (tasks finished by month)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY, structured</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chronological</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">Cold snapshots (waves of 10 sessions)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, full copy</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chronological</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">Exhaustive thematic knowledge (methodology, patterns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, never auto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Thematic</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>This distinction avoids the catch-all. Each file knows where it should live based on <strong>what it contains</strong>, not <strong>when it was created</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_logical_next_step_in_the_series">The logical next step in the series</h2> <div class="sectionbody"> <div class="paragraph"> <p>If you have read the first two articles, here is how the three pieces fit together:</p> </div> <div id="diag-trilogie" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-7a93be1f2d7bbeab8cf9d47564547c7c.svg" alt="Les trois articles de la série gouvernance — progression logique" width="1216" height="493"> </div> </div> <div class="ulist"> <ul> <li> <p><strong>0108</strong>answers: "How to give the agent a memory between two sessions?"</p> </li> <li> <p><strong>0110</strong>answers: "How to prevent this memory from suffocating the agent?"</p> </li> <li> <p><strong>0111</strong>answers: "What if the problem isn’t the size of the archives, but what we <strong>chose</strong> to put in EAGER?"</p> </li> </ul> </div> <div class="paragraph"> <p>The first article built the structure. The second added the aging mechanism. The third audits the content — and discovers that the methodology itself has become the problem.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_i_would_have_done_differently">What I would have done differently</h2> <div class="sectionbody"> <div class="paragraph"> <p>In hindsight, I see the initial design error.`AGENT_MODUS_OPERANDI.adoc`was created as a single document — a manifesto. That was the right approach to formalize the thinking. But once the thinking was formalized, the document should have been split immediately: the essential in EAGER, the exhaustive in cold.</p> </div> <div class="paragraph"> <p>I didn’t do it because I was proud of the document. 627 lines of pure engineering, handwritten, each section the fruit of a session lesson. It was my work. And like any author, I struggled to cut it.</p> </div> <div class="paragraph"> <p>The lesson:<strong>just because a document is good doesn’t mean it should be loaded automatically</strong>. The quality of the content has nothing to do with its relevance to the agent’s immediate context.</p> </div> <div class="paragraph"> <p>Today, the rule is simple: any document over 100 lines in the EAGER context is a suspect. It deserves an audit. Not a condemnation — an audit. And the question is never "should it be deleted?" but "should it be loaded every session?"</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_guide_to_auditing_your_own_context">The guide to auditing your own context</h2> <div class="sectionbody"> <div class="paragraph"> <p>If you have followed the first two articles and set up your own Eager/Lazy governance, here is a five-step audit procedure:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Measure</strong>:`wc -l`on all your EAGER files. The total should be under 1000 lines.</p> </li> <li> <p><strong>Identify the largest</strong>: the file that accounts for more than 20% of the total is suspect number one.</p> </li> <li> <p><strong>Audit section by section</strong>: for each section, ask yourself "Is this information already elsewhere? Has the agent already read it in another file? Has it been useful in the last 5 sessions?"</p> </li> <li> <p><strong>Classify</strong>: duplicate, never used, unique knowledge.</p> </li> <li> <p><strong>Split or relocate</strong>: what is unique and critical → compacted ESSENTIALS. Everything else →<code>encyclopedies/</code>.</p> </li> </ol> </div> <div id="diag-audit-checklist" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-5bc9a34fb18adeac0f7da7af8a309acd.svg" alt="Procédure d’audit en 5 étapes" width="430" height="741"> </div> </div> <div class="paragraph"> <p>This procedure takes 15 minutes. Over a project of 50 sessions, it saves hundreds of tokens per future session. The ROI is immediate.</p> </div> </div> </div> <div class="sect1"> <h2 id="_a_living_governance">A living governance</h2> <div class="sectionbody"> <div class="paragraph"> <p>What this series of three articles has taught me is that agent governance is not a finished product. It is a<strong>living organism</strong>. It grows with the project. It catches growth diseases. It requires regular check-ups.</p> </div> <div class="paragraph"> <p>Session 048 revealed that archives swell. Session 051 revealed that the methodology itself swells. Session 060 will probably reveal something else. That’s normal. It’s healthy. A governance that never questions itself is a dead governance.</p> </div> <div class="paragraph"> <p>The three mechanisms put in place — Eager/Lazy, Hot/Warm/Cold, encyclopedic split — form a defense-in-depth system against context saturation. None are sufficient alone. Together, they complement each other:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Eager/Lazy</strong>structures information <strong>by availability</strong></p> </li> <li> <p><strong>Hot/Warm/Cold</strong>structures information <strong>by freshness</strong></p> </li> <li> <p><strong>Encyclopedic Audit</strong>structures information <strong>by density</strong></p> </li> </ul> </div> <div id="diag-defense-in-depth" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-c815b1bc714a7df30a365994ac557d7d.svg" alt="Les trois couches de défense contre la saturation du contexte" width="672" height="345"> </div> </div> <div class="paragraph"> <p>With these three layers, the agent context on`magic-stick`went from 2087 lines (before any optimization) to about 800 lines — a division by 2.6. Without having lost a single line of documentation, a single session archive, a single lesson learned.</p> </div> <div class="paragraph"> <p>Everything is there. Just better organized.</p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Article 0108 — Eager/Lazy Strategy:<a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Governing an AI Agent with AsciiDoc</a></p> </li> <li> <p>Article 0110 — Hot/Warm/Cold Mechanism:<a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window and Cold Wave</a></p> </li> <li> <p>My site: <a href="https://cheroliv.com" class="bare">https://cheroliv.com</a></p> </li> <li> <p>The`magic-stick`project: <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><strong>Knowledge does not have to disappear. It just shouldn’t be loaded when it is not necessary.</strong></p> </div> </div> </div> https://cheroliv.com/en/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="_summary">Summary</h2> <div class="sectionbody"> <div class="paragraph"> <p>After 48 sessions on a single project and 150+ in total, the Eager/Lazy governance system I had carefully built began to choke. The agent files, meant to be light, weighed 5200 cumulative lines. The auto-loaded context was growing faster than my ability to control it. This article tells how I conceptualized a backup mechanism — between a sliding window and an identical cold wave — to maintain a light active context without ever losing anything.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_signal_5200_lines">The Signal: 5200 Lines</h2> <div class="sectionbody"> <div class="paragraph"> <p>I am in the middle of session 048 on`magic-stick`, my project to build a live Linux ISO. Opencode is watching me. As always, it automatically loaded my Eager files at the start of the session —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Nothing unusual.</p> </div> <div class="paragraph"> <p>Except that something is wrong. The responses are slower. The reasoning is more diluted. The agent forgets details that were right in front of it two messages ago.</p> </div> <div class="paragraph"> <p>I open a terminal and type:</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 lines for INDEX. 55 for SESSIONS_HISTORY.<strong>1756 for COMPLETED_TASKS_ARCHIVE</strong>.</p> </div> <div class="paragraph"> <p>The`sessions/`folder adds another ~3200 lines. Total:<strong>5200 lines</strong>of context loading, one way or another, into the agent’s temporary brain.</p> </div> <div class="paragraph"> <p>The Eager/Lazy strategy I theorized in the previous article works — but it has a birth defect I hadn’t anticipated: it has<strong>no aging mechanism</strong>. Every session adds a line to INDEX, a paragraph to COMPLETED_TASKS, a file in sessions/. Nothing ever leaves. The context is a snowball that grows with every new session.</p> </div> <div id="diag-growth" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-95c83a721c5c943661137fb4c7f9bc23.svg" alt="Courbe de croissance des fichiers agents — de la session 1 à 48" width="427" height="591"> </div> </div> <div class="paragraph"> <p>This is not a bug; it is a direct consequence of the end-of-session procedure that meticulously archives every detail. The system is a victim of its own success.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_diagnosis_triple_redundancy">The Diagnosis: Triple Redundancy</h2> <div class="sectionbody"> <div class="paragraph"> <p>I ask the agent to diagnose the problem. Its response is immediate and surgical.</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">File</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lines</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Role</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problem</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 (auto-loaded)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Table of all sessions since 001 —<strong>+1 line per session</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">Summary table —<strong>redundancy with INDEX</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1756</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (implicit)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Full details of all April sessions</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 (supposed)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Individual archives, but<strong>not used</strong>because everything is already in COMPLETED_TASKS</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The agent identifies four root causes:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE absorbs everything</strong>— Instead of pointing to the`.sessions/`archives, it fully copies each session.</p> </li> <li> <p><strong>INDEX.adoc acts as a full history</strong>— The "Recent Sessions" table contains 30+ entries.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc is redundant</strong>— Same info as INDEX, different format.</p> </li> <li> <p><strong>The LAZY rule is not respected</strong>— COMPLETED_TASKS is implicitly EAGER because it contains everything.</p> </li> </ol> </div> <div class="paragraph"> <p>Its proposal is radical: limit INDEX to 10 sessions, empty COMPLETED_TASKS, move SESSIONS_HISTORY to pure LAZY. Immediate gain:<strong>~1900 lines saved</strong>.</p> </div> <div class="paragraph"> <p>It’s clean, efficient, logical. But I have a problem with this approach.</p> </div> </div> </div> <div class="sect1"> <h2 id="_why_i_refused_the_obvious_solution">Why I Refused the Obvious Solution</h2> <div class="sectionbody"> <div class="paragraph"> <p>The agent’s solution is that of an engineer optimizing a cache. Limit. Truncate. Remove redundancies.</p> </div> <div class="paragraph"> <p>But these "redundancies" are not redundancies. Each governance file captures a<strong>different angle</strong>on the same reality:</p> </div> <div class="ulist"> <ul> <li> <p><strong>INDEX</strong>= macro view, executive dashboard</p> </li> <li> <p><strong>SESSIONS_HISTORY</strong>= linear chronological table, scored</p> </li> <li> <p><strong>COMPLETED_TASKS_ARCHIVE</strong>= detailed narrative with metrics</p> </li> <li> <p><strong>sessions/*.adoc</strong> = individual archives, full context</p> </li> </ul> </div> <div class="paragraph"> <p>This is not mindless duplication. This is<strong>structured multiple perspective</strong>. This is exactly what is needed for distillation — so that later, a human (or a future better-trained LLM) can cross-reference angles and extract patterns.</p> </div> <div class="paragraph"> <p>Imagine a data scientist telling you: "Let’s delete 3 out of 6 columns, they are correlated." What do you tell them? That correlation is not redundancy when each column captures a different dimension of the same phenomenon. That this dimensional richness is precisely what makes the dataset exploitable.</p> </div> <div class="paragraph"> <p>This is my intuition. And I defend it against the agent’s cold rationality.</p> </div> <div class="paragraph"> <p><em><em>_ I don’t see a silent "catch-all" in my idea. We aren’t throwing everything in; we are moving the structured result of the end-of-session procedure — each file with its angle, its redundancies which are actually an enrichment. This multidimensional material will be better for distillation. </em>_</em></p> </div> <div class="paragraph"> <p>The agent takes the hit. And corrects itself.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_proposal_identical_cold_wave">The Proposal: Identical Cold Wave</h2> <div class="sectionbody"> <div class="paragraph"> <p>The agent then proposes a finer mechanism, which respects my intuition of a rich dataset while solving the technical problem of exploding context.</p> </div> <div class="paragraph"> <p>The principle is simple and directly inspired by the<strong>Hot/Warm/Cold Storage</strong>pattern applied to archive management:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Hot (EAGER)</strong>= last 10 sessions in INDEX, PROMPT_REPRISE of session N+1, last 2 session files</p> </li> <li> <p><strong>Warm (LAZY)</strong>= recent SESSIONS_HISTORY, SCRIPT_VERIFICATION, all reference documentation</p> </li> <li> <p><strong>Cold (backup/)</strong>= everything else, moved<strong>intact</strong>, without transformation, without re-indexing</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... ---- The key to the mechanism:**the backup is not a central index, it is a faithful copy of the past wave**. When we exceed the 10-active-session horizon, we delete nothing. We re-index nothing. We merge nothing. We take the packet of agent files as they were at session N-10, and we move them to`backup/`. The active files, however, are truncated: * INDEX: only the last 10 lines (sliding window) * SESSIONS_HISTORY: same * COMPLETED_TASKS_ARCHIVE: new file for the current period * sessions/: only the last 2 sessions [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 Architecture Hot / Warm / Cold du Contexte Agent package "HOT (EAGER)\nChargé automatiquement\n~300 lignes" as HOT #FFCDD2 { file "INDEX.adoc\n(10 sessions)" as IDX_HOT file "PROMPT_REPRISE\n(session N+1)" as PRO_HOT file "AGENT.adoc\n(règles absolues)" as AG_HOT } package "WARM (LAZY)\nChargé sur demande\n~500 lignes" as WARM #FFF9C4 { file "SESSIONS_HISTORY\n(10 dernières)" as HIS_WARM file "SCRIPT_VERIFICATION\n(dernière)" as VER_WARM file "PROCEDURES.adoc\n(templates)" as PRO_WARM file "*_REFERENCE.adoc\n(doc technique)" as REF_WARM } package "COLD (backup/)\nJamais chargé\nLecture humaine uniquement" as COLD #BBDEFB { folder "Y2026-001-039/" as WAVE { file "INDEX (complet)" as IDX_COLD file "SESSIONS_HISTORY\n(complet)" as HIS_COLD file "COMPLETED_TASKS\n(complet)" as ARCH_COLD folder "sessions/ (001-039)" as SESS_COLD } folder "Y2026-040-???\n(future)" as FUTURE } HOT --> WARM : "Agent remonte\nsi besoin" WARM --> COLD : "Jamais automatique\nL'humain y va seul" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- The immediate gain is massive: the EAGER context goes from**~5200 lines to ~300 lines**. A division by 17. Without having lost a single line of historical data. == Why This Is Not a Catch-All The agent, in its first iteration, feared that`backup/`would become a black box — a folder where files are thrown and never read again. This is a legitimate fear. But it is based on a confusion. A catch-all is when you throw files**without structure, without convention, without grouping logic**. Here, the backup is structured by period (Y2026-001-039), and each backup folder contains**the same structure**as the`.agents/`active folder: INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/. This is not a catch-all. It is a**timestamped snapshot**. One could even say it is a simplified versioning mechanism — with the caveat that it doesn't version files individually, but the entire governance packet at time T. When you want to find old information, you don't need a central index. You have two options: 1. **Targeted `grep`**:`grep -r "zsh" backup/Y2026-001-039/`— and you find everything that mentions zsh in that period, regardless of the angle (INDEX, SESSIONS_HISTORY, session archive). 2. **Manual reintegration**: you temporarily copy the backup folder into the active context, and you ask the agent to analyze that specific period. The index is implicit. It is in the very structure of the files — each being already an index from its own angle. == The Shelving Metaphor To make the mechanism intuitive, I conceptualized it as three shelves: * **Shelf 1 (EAGER)**— the workbench. What I need *now*. Recent INDEX, PROMPT_REPRISE, absolute rules. Light, immediate, critical. * **Shelf 2 (LAZY)**— the reference library. What I can go look for on demand. Technical references, recent history, procedures. More voluminous, but not loaded into memory. * **Basement (backup/)**— the cold archives. Everything that is past but that I don't want to throw away. The agent never enters. The human goes down when they want to distill. The agent initially proposed a fourth shelf — a`index-backup.adoc`that would be LAZY and contain a table of contents for the entire backup. I refused. That would be one more redundancy in a system already suffering from linear growth. The structure of the archived files is already an index. == The Two-Trigger Sensor The conceptualization was solid, but one blind spot remained:**when exactly to trigger the rotation?**The initial article identified this as an open question. Two days later, the answer is codified in the governance files of six projects: a two-trigger sensor. === The Automatic Trigger — `N % 10 == 0` The first trigger is mathematical. When the session number is a multiple of 10 — session 10, 20, 30, 40 — the backup rotation executes automatically within the end-of-session procedure, just after step 6. Why 10? It is the compromise between two opposing forces: a window too short (5 sessions) loses the context necessary for continuity; a window too long (20 sessions) does not solve the context bloating problem. Ten sessions, at a rate of one to two sessions per day, cover about a week of work — enough for the agent to remember recent decisions, not enough for the context to explode. === The Threshold Trigger — 500 EAGER Lines The second trigger is dynamic. Regardless of the session number, if the cumulative EAGER files exceed**500 lines**, the rotation triggers. This threshold protects against the scenario where sessions are exceptionally productive — a lot of content written in few sessions. A session producing 120 lines of editorial content makes COMPLETED_TASKS_ARCHIVE grow much faster than a debug session correcting two lines. The 500-line threshold, measured via`wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, captures this asymmetry. === The Manual Trigger — "rotation backup" Finally, the human keeps control. The keywords`rotation backup`, `backup rotation` ou `lance la rotation backup`trigger the procedure on demand, regardless of the end of the session. Useful when you feel the context is becoming heavy but you aren't yet at a multiple of 10, or when you want to archive a work phase before starting a new one. [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 Capteur de Rotation Backup — Les Trois Déclencheurs start :Procédure de fin de session; note right: Mots-clés "fin de session"\nou "on arrête là" :É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 ---- This diagram shows the exact insertion of the sensor into the end-of-session procedure. Step 7 is optional — it only executes if one of the two conditions is true — but it is systematically *checked*. The final checklist includes`[✅] 7. Backup roté (si applicable)`. === The Closed Loop This sensor closes the loop opened by the previous article. Eager/Lazy governance solved the agent memory problem between two sessions. The Hot/Warm/Cold mechanism solved the problem of growing memory. The two-trigger sensor solves the *when* problem — removing the mental load of monitoring context size from the human. [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 Les Trois Couches de la Gouvernance Agent left to right direction package "Couche 1 — Mémoire\n(Article 0108)" as C1 #E8F5E9 { rectangle "**EAGER**\nTableau de bord\nChargé auto" as EAG rectangle "**LAZY**\nManuel propriétaire\nChargé sur demande" as LAZ EAG -[hidden]right-> LAZ } package "Couche 2 — Vieillissement\n(Article 0110)" as C2 #FFF9C4 { rectangle "**HOT**\n10 sessions actives\n~300 lignes" as HOT rectangle "**WARM**\nRéférences\nProcédures" as WRM rectangle "**COLD**\nbackup/\nVague froide" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "Couche 3 — Déclencheur\n(Aujourd'hui)" as C3 #BBDEFB { rectangle "**Auto**\nN % 10 == 0" as AUTO rectangle "**Seuil**\n> 500 lignes" as SEUIL rectangle "**Manuel**\nrotation backup" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "La mémoire grandit\n→ il faut un mécanisme\nde vieillissement" C2 --> C3 : "Le vieillissement\n→ il faut un déclencheur\npour l'exécuter" 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 ---- The three layers stack logically. The first gives the agent a memory. The second prevents this memory from choking the agent. The third automates the maintenance of this memory so the human doesn't have to think about it. === Effective Migration on cheroliv.com The mechanism did not remain theoretical. On`cheroliv.com`, the first backup rotation was executed on April 29, 2026 — sessions -6 to 2 migrated to`.agents/backup/Y2026-sessions-neg6-a-002/`: |=== |File |Before rotation |After rotation |Gain |`.agents/INDEX.adoc` |19 sessions listed |10 sessions (3-12) |-9 entries |`.agents/SESSIONS_HISTORY.adoc` |18 sessions |10 sessions |-8 entries |`COMPLETED_TASKS_ARCHIVE` |161 lines (sessions 1-12) |135 lines (sessions 3-12) |-26 lines |`sessions/` |20 files |10 files |-10 files |**backup/** |Non-existent |1 cold wave (10 sessions archived) |+1 cold packet |=== The line gain was modest — the project is young, 12 sessions — but the important thing is that the**mechanism is in place**. The next automatic rotation will trigger at session 20, or sooner if 500 EAGER lines are reached. == The Human-Agent Lesson This session 048 taught me something fundamental about collaborating with an AI agent. The agent has a natural bias: it seeks to**optimize**, à **simplify**, à **eliminate redundancies**. This is the bias of a system trained to produce clean and concise responses. Faced with a rich and multidimensional dataset, its first reflex is to reduce it to its simplest expression. The human, however, has a different intuition: they sense that structured redundancy is an**asset**, not a flaw. That the diversity of angles on the same reality is precisely what will allow high-quality distillation later. It's not that the agent is wrong. It's that its "optimum" is not mine. The agent optimizes for the**present**— the immediate context, the quick answer to the question asked. The human optimizes for the**future**— the ability to retrieve, cross-reference, and distill in three months or three years. ____ What I want is the raw material. Your reflections, your hesitations, your answers to my questions. Not your synthesis. I know how to synthesize better than you. I want the raw matter. ____ This sentence I said to it at the end of the session summarizes everything. The agent is a production tool. The human is the distillation tool. Governance is not made so the agent understands everything on its own — it is made so the human can, later, work the produced material. The identical cold wave is the architectural translation of this philosophy: we throw nothing away, we merge nothing, we re-index nothing. We move the packet intact. Distillation will come later, by hand, by the human. == The Logical Sequel to the Previous Article If you have readlink:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[the article on the Eager/Lazy strategy], you will recognize the natural progression: 1. **Article 0108**— Eager/Lazy governance: *how* to structure agent context into two levels of availability 2. **This article 0110**— The backup mechanism: *how* to age this context without losing it when it becomes too voluminous The first article answered the question: "The agent remembers nothing between two sessions, how do we give it a memory?" This one answers the question that inevitably follows the first: "The memory grows every session, how do we prevent it from choking the agent without erasing it?" The answer lies in one pattern:**Hot/Warm/Cold**, applied to governance files. And in one principle:**never lose anything, always relocate everything**. == Links * Previous article:link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governing an AI Agent with AsciiDoc] * My site: https://cheroliv.com * The`magic-stick`project: https://github.com/cheroliv/magic-stick --- *A good governance system never deletes data. It organizes it.*</code></pre> </div> </div> </div> </div> https://cheroliv.com/en/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="#_the_scene_a_jhipster_project_a_build_that_no_longer_loads">The scene: a JHipster project, a build that no longer loads</a></li> <li><a href="#_error_1_the_phantom_variable_reportsdir">Error 1: the phantom variable <code>reportsDir</code></a></li> <li><a href="#_error_2_main_no_longer_exists_under_gradle_9">Error 2: <code>main = "…​"</code> no longer exists under Gradle 9</a></li> <li><a href="#_error_3_sourcecompatibility_is_no_longer_a_project_property">Error 3: <code>sourceCompatibility</code> is no longer a project property</a></li> <li><a href="#_error_4_the_three_operand_groovy_assertion">Error 4: the three-operand Groovy assertion</a></li> <li><a href="#_error_5_the_implicit_dependency_compilekotlin_openapigenerate">Error 5: the implicit dependency <code>compileKotlin</code> → <code>openApiGenerate</code></a></li> <li><a href="#_error_6_generategitproperties_breaks_on_filteroutputstream_write">Error 6: <code>generateGitProperties</code> breaks on <code>FilterOutputStream.write()</code></a></li> <li><a href="#_finally_testcontainers_enters_the_scene">Finally: Testcontainers enters the scene</a></li> <li><a href="#_phase_1_the_docker_java_lead">Phase 1: the docker-java lead</a></li> <li><a href="#_phase_2_web_search_and_github_breadcrumbs">Phase 2: web search and GitHub breadcrumbs</a></li> <li><a href="#_phase_3_the_trap_of_renamed_artifacts">Phase 3: the trap of renamed artifacts</a></li> <li><a href="#_phase_4_forcing_the_resolution">Phase 4: forcing the resolution</a></li> <li><a href="#_final_result">Final result</a></li> <li><a href="#_summary_table_of_corrections">Summary table of corrections</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 15 minutes</div> <p>Have you ever had that moment where a simple`./gradlew build`that you run a hundred times a day suddenly starts crashing with an error you’ve never seen? Multiply that by eleven successive errors, add a healthy dose of Docker Engine 29 incompatibility, sprinkle in some Gradle 9 making APIs you’ve used for ten years disappear. Here is the complete log.</p> </div> <hr> <div class="paragraph"> <div class="title">Diagram 1 — Gradle 9 Migration (error chain)</div> <p>Goal: show the series of incompatibilities.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-6215da1a3f4f27918205b5c8ff34a48c.png" alt="Diagram" width="579" height="106"> </div> <div class="title">Figure 1. 👉 Clear, focused on Gradle.</div> </div> <hr> <div class="paragraph"> <div class="title">Diagram 2 — Incompatible JHipster Plugins</div> <p>Goal: isolate the broken plugins.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-07ed01d932957e366cd8fed4b8aee2a3.png" alt="Diagram" width="569" height="123"> </div> <div class="title">Figure 2. 👉 Clean view of dependencies.</div> </div> <hr> <div class="paragraph"> <div class="title">Diagram 3 — Docker 29 / Testcontainers</div> <p>Goal: runtime problem.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-544e3a93289a5db5b898714292d384f4.png" alt="Diagram" width="788" height="123"> </div> <div class="title">Figure 3. 👉 Clear history of the runtime.</div> </div> <hr> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-5d4d1754844f7121ef284aa0cc588011.png" alt="Diagram" width="1072" height="193"> </div> <div class="title">Figure 4. another way to represent it</div> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_a_jhipster_project_a_build_that_no_longer_loads">The scene: a JHipster project, a build that no longer loads</h2> <div class="sectionbody"> <div class="paragraph"> <p>The project`edster`is a JHipster application generated in 2024. The root build script`build.gradle`remained stable for months. Then we decided to upgrade:</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">Component</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Target Version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9.4.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21.0.11-tem (Eclipse Temurin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JHipster</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8.x (framework`tech.jhipster:jhipster-framework:8.11.0`)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spring Boot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3.4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.3.0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Docker Engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29.4.1 (API 1.54)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The Java version change is handled 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>First run:</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>We don’t even get past the build script loading. The problem is in`buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_1_the_phantom_variable_reportsdir">Error 1: the phantom variable <code>reportsDir</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The script`jhipster.cucumber-conventions.gradle`contains:</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>The defined variable is`cucumberReportsDir`. The one used is`reportsDir`-- which is not defined anywhere.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>:`outputs.dir(cucumberReportsDir)`</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_2_main_no_longer_exists_under_gradle_9">Error 2: <code>main = "…​"</code> no longer exists under Gradle 9</h2> <div class="sectionbody"> <div class="paragraph"> <p>Immediate restart:</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 removes the property`main`in favor of`mainClass`on`JavaExec`tasks.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>:`mainClass = "org.junit.platform.console.ConsoleLauncher"`</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_3_sourcecompatibility_is_no_longer_a_project_property">Error 3: <code>sourceCompatibility</code> is no longer a project property</h2> <div class="sectionbody"> <div class="paragraph"> <p>New error:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'sourceCompatibility' for root project 'edster' of type org.gradle.api.Project.</code></pre> </div> </div> <div class="paragraph"> <p>The root script had:</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 removes these properties at the root level. They must reside in a`java`block.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">java { sourceCompatibility = JavaVersion.VERSION_21 targetCompatibility = JavaVersion.VERSION_21 }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_error_4_the_three_operand_groovy_assertion">Error 4: the three-operand Groovy assertion</h2> <div class="sectionbody"> <div class="paragraph"> <p>The old script contained:</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>In Groovy,<code>"21"</code> et <code>"24"`are truthy strings. The expression resolves to</code>(…​ == "17") || true || true`, which is always true — but the syntax is invalid for the desired strict assertion.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] in ["17", "21", "23", "24"]</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_error_5_the_implicit_dependency_compilekotlin_openapigenerate">Error 5: the implicit dependency <code>compileKotlin</code> → <code>openApiGenerate</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The build progresses. Kotlin compilation successful. Then:</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 refuses implicit dependencies between tasks. Since`compileKotlin`reads the sources generated by`openApiGenerate`, the link must be declared.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>in`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`is necessary because`openApiGenerate`is an extension (openAPI Generator plugin) and not a task directly accessible during the configuration phase.</p> </div> </div> </div> <div class="sect1"> <h2 id="_error_6_generategitproperties_breaks_on_filteroutputstream_write">Error 6: <code>generateGitProperties</code> breaks on <code>FilterOutputStream.write()</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>Java compilation passes. Resources are processed. Then:</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>The`gradle-git-properties`plugin version 2.5.0 is incompatible with Java 21 / Gradle 9. An internal bug attempts to call`write(int)`via Groovy on a stream that has been closed.</p> </div> <div class="paragraph"> <p><strong>Correction</strong>in`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="_finally_testcontainers_enters_the_scene">Finally: Testcontainers enters the scene</h2> <div class="sectionbody"> <div class="paragraph"> <p>Until now, it was pure "build script debugging." Each error was a Gradle 9 or Java 21 incompatibility in the build scripts. After the six corrections above, the`./gradlew assemble`passes successfully.</p> </div> <div class="paragraph"> <p>But`./gradlew build`also executes tests, and Cucumber tests use Testcontainers to launch an ephemeral PostgreSQL.</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 is unable to communicate with Docker. Two different strategies (environment variables + Unix socket) fail with the same error.</p> </div> <div id="diag-docker-handshake" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-f31d9e10795d818ce3068413fb5fdd1e.svg" alt="Handshake Docker API refusé par le daemon" width="731" height="616"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_1_the_docker_java_lead">Phase 1: the docker-java lead</h2> <div class="sectionbody"> <div class="paragraph"> <p>First reflex: the Java Docker client used by Testcontainers sends API version`1.32`in its HTTP handshake, but Docker Engine 29.4.1 requires a minimum of`1.40`. The problem is at the client level, not the daemon.</p> </div> <div class="paragraph"> <p>Verification of the docker-java version resolved by 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, dating from Testcontainers 1.20.6. The latest public version of docker-java is 3.5.1. Let’s try to force the version upgrade via`resolutionStrategy`in the`configurations` de `build.gradle`block:</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>Rerunning the build. Same error:`client version 1.32 is too old`.</p> </div> <div class="paragraph"> <p>Verifying the Gradle cache: the JARs were indeed re-downloaded, but the error persists. docker-java 3.5.1 still sends`1.32`. This version is therefore NOT sufficient for Docker Engine 29.4.1.</p> </div> <div class="paragraph"> <p><strong>Purification action</strong>: completely clear the Gradle cache, just to be sure:</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>Complete restart after purge. Same error.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_web_search_and_github_breadcrumbs">Phase 2: web search and GitHub breadcrumbs</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1 is insufficient. Nothing left but to search if someone has encountered this exact problem.</p> </div> <div class="paragraph"> <p>Targeted search on testcontainers-java and docker-java issues:</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>Immediate first results:</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>The breadcrumbs are clear: Docker Engine 29.x raised its minimum API version from`1.24`(former default) to`1.40`. Testcontainers 1.20.x uses docker-java 3.4.x which negotiates the API version by sending`1.32`. The daemon politely but firmly refuses.</p> </div> <div class="paragraph"> <p>In issue #11491, a maintainer responds:</p> </div> <div class="paragraph"> <p><em><em>_ Hi, I have a project running with version 2.0.3 on a GH runner with engine 29.1 and it works. Can you all please check there is no version conflict? Please, remember all modules were prefixed with`testcontainers-<code>. So, starting with version 2.x we went from`postgresql</code> to <code>testcontainers-postgresql</code> </em>_</em></p> </div> <div class="paragraph"> <p>This response contains<strong>two critical pieces of information</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+ resolves the problem</p> </li> <li> <p>The modules have been<strong>renamed with the <code>testcontainers-</code> prefix</strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_phase_3_the_trap_of_renamed_artifacts">Phase 3: the trap of renamed artifacts</h2> <div class="sectionbody"> <div class="paragraph"> <p>The renaming is brutal. In Testcontainers 2.x, none of the old names work under that name anymore:</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">Old name (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">New name (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">unchanged</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>First attempt: apply the Testcontainers 2.0.5 BOM and the new artifact names in`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>The testcontainers-bom BOM is not enough.</strong>Why? Because Spring Boot 3.4.5 exposes its own dependency management BOM (<code>spring-boot-dependencies</code>) which<strong>wins</strong>over the Testcontainers BOM in transitive resolution. Spring Boot fixes`testcontainers` à <code>1.20.6</code>, and thus all artifacts not explicitly in the Spring Boot BOM (like the new`testcontainers-*<code>) resolve to the old names`1.20.6</code>-- which no longer exist in this version.</p> </div> <div class="paragraph"> <p>Inspecting the`dependencies --configuration testRuntimeClasspath`, we find:</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>→`indicates the substitution: Testcontainers 2.0.5 is <strong>requested</strong>, but Spring Boot forces`1.20.6</code>.</p> </div> <div id="diag-bom-war" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-714056a094f875d4bd0cf8db572918d3.svg" alt="Conflit entre le BOM Spring Boot et le BOM Testcontainers" width="1111" height="321"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_4_forcing_the_resolution">Phase 4: forcing the resolution</h2> <div class="sectionbody"> <div class="paragraph"> <p>The strategy becomes twofold:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Force docker-java to its 3.7.1 version (tested as compatible with Docker Engine 29)</p> </li> <li> <p>Force Testcontainers core to 2.0.5 by bypassing the Spring Boot BOM</p> </li> </ol> </div> <div id="diag-resolution-override" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-0e6edf1a58135d9df65ae14483179ddf.svg" alt="resolutionStrategy.eachDependency court-circuite le BOM Spring Boot" width="1103" height="468"> </div> </div> <div class="paragraph"> <p><strong>Final correction</strong>in`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`is the only way to override the`spring-boot-dependencies`BOM managed by the Spring Boot plugin. The equality test on`details.requested.name == "testcontainers"`is intentionally restrictive: we only force the core module. The`testcontainers-*`modules follow the Testcontainers 2.0.5 BOM that we explicitly declared.</p> </div> </div> </div> <div class="sect1"> <h2 id="_final_result">Final result</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 finally manage to create their PostgreSQL containers via Docker Engine 29.4.1. The final business error (HTTP 500 on the Cucumber test) is an application problem totally independent of the build script.</p> </div> </div> </div> <div class="sect1"> <h2 id="_summary_table_of_corrections">Summary table of corrections</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">File</th> <th class="tableblock halign-left valign-top">Problem</th> <th class="tableblock halign-left valign-top">Correction</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">Non-existent`reportsDir`variable</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`Gradle 9 deprecated</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 forbidden Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bloc <code>java { sourceCompatibility = JavaVersion.VERSION_21 }</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"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Syntactically invalid Groovy assertion</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">Implicit dependency`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`Java 21 incompatible</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">Gradle cache</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 tested, resolved but insufficient</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Purge + move to docker-java 3.7.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Testcontainers 1.20.6 incompatible with Docker Engine 29</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Force Testcontainers 2.0.5 + prefix`testcontainers-*`+ resolutionStrategy vs Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>If your JHipster/Gradle build crashes after upgrading to Gradle 9 + Docker Engine 29, the errors fall into two categories:</p> </div> <div class="paragraph"> <p><strong>Build script errors</strong>(the first 6): Gradle 9 removes properties and syntaxes that had worked for years (<code>sourceCompatibility=</code>, <code>main =</code>, <code>reportsDir</code>). These are mechanical migrations once you know the new API.</p> </div> <div class="paragraph"> <p><strong>Docker runtime errors</strong>(the last 2): Docker Engine 29.4.1 rejects API clients < 1.40. Testcontainers 1.20.6 (imposed by Spring Boot 3.4.5) uses docker-java 3.4.1 which sends 1.32. Only Testcontainers 2.0.5 + docker-java 3.7.1 resolves the problem, with artifact renaming and version forcing via`resolutionStrategy.eachDependency`as the only way to bypass the implicit Spring Boot BOM.</p> </div> <div class="paragraph"> <p>The Gradle build script at the project root is now clean.`./gradlew build`passes on Java 21, Gradle 9.4.1, Spring Boot 3.4.5, and Docker Engine 29.4.1.</p> </div> </div> </div> https://cheroliv.com/en/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="_summary">Summary</h2> <div class="sectionbody"> <div class="paragraph"> <p>When working with an AI agent like Opencode on complex projects across multiple sessions, one faces a fundamental problem:<strong>context leak</strong>. The agent does not remember the previous session. Everything we explained — the architecture, the conventions, the backlog state — is lost. Rebuilding this context every session is costly, slow, and a source of error.</p> </div> <div class="paragraph"> <p>This article presents the handcrafted strategy I built to solve this problem: a persistent governance system based on AsciiDoc files, with a<strong>Eager/Lazy</strong>dichotomy to optimize context token consumption, and an<strong>essential end-of-session procedure</strong>to ensure continuity.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_monday_april_21_900_am">The Scene: Monday, April 21, 9:00 AM</h2> <div class="sectionbody"> <div class="paragraph"> <p>I reopen Opencode to resume my Gradle plugin`plantuml-plugin`. Last night, I spent three hours discussing the API key pool architecture with the agent — round-robin rotation, quota management, automatic fallback. This morning, the agent looks at me with goldfish eyes.</p> </div> <div class="paragraph"> <p><em><em>_ — Hello, I am your Opencode assistant. How can I help you today? </em>_</em></p> </div> <div class="paragraph"> <p>No — Oh right, the API key pool, we were at the YAML structure. No — Careful,<code>PlantumlManager`is a Kotlin singleton object, not a class. No — No, we decided yesterday that`SyntaxValidationResult`remained a sealed class nested in`PlantumlService</code>.</p> </div> <div class="paragraph"> <p>Everything has to be redone. Or rather: everything has to be re-explained. I’m going to spend the first twenty minutes of my session reconstructing a context that the agent already had in its hands yesterday. Twenty minutes of burned tokens. Twenty minutes where I could be coding, but instead, I’m doing mandatory pedagogy.</p> </div> <div class="paragraph"> <p>This isn’t an Opencode bug. It is the very nature of conversational LLMs: between two sessions, the working memory is<strong>completely erased</strong>. The agent doesn’t remember the previous mission, the decisions made, the traps identified, or the code we wrote together.</p> </div> <div class="paragraph"> <p>I’ve experienced this dozens of times. Across four simultaneous projects. With sessions stretching over weeks. I calculated: on average,<strong>30 to 40% of session time</strong>was spent re-contextualizing the agent. By session 87 of project`plantuml-plugin`, I snapped. I could no longer afford to explain for the tenth time that`AttemptEntry`is a top-level data class in`DiagramProcessor.kt`.</p> </div> <div class="paragraph"> <p>I needed a system. Not a hack. Real governance.</p> </div> </div> </div> <div class="sect1"> <h2 id="_genesis_from_chaos_to_method">Genesis: From Chaos to Method</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_first_sessions_the_dark_ages">The First Sessions: The Dark Ages</h3> <div class="paragraph"> <p>My first project with Opencode,<code>plantuml-plugin</code>, started without any governance. I ask a question, the agent answers, we iterate, the session ends, and the next day we start from scratch. It was session 1, then 2, then 3…​ until session 62, where I realized I had lost cumulative hours re-explaining the same architecture.</p> </div> <div class="paragraph"> <p>At session 62, the numbers are there:<strong>198 unit tests passing</strong>, <strong>42 functional tests validated</strong>, the plugin works. But the cognitive cost is unbearable. Every new session begins with a twenty-minute monologue on the project structure.</p> </div> </div> <div class="sect2"> <h3 id="_the_case_of_the_destroyed_site_yml_session_2_bakery_plugin">The Case of the Destroyed site.yml (Session 2, bakery-plugin)</h3> <div class="paragraph"> <p>The method was also born from a catastrophe. On the`bakery-gradle`project, at session 2, I ask the agent to modify the`site.yml`file. The agent, without checking if the file is versioned, performs a`Write`complete overwrite that wipes the content. Result: real tokens (Firebase API keys, deployment secrets) are replaced by fake placeholders. The file wasn’t in git — it was in`.gitignore`to protect secrets.</p> </div> <div class="paragraph"> <p>No backup. No`git restore`possible. I’m stuck. I have to manually rebuild the configuration file, find the tokens in my password managers, and piece everything back together.</p> </div> <div class="paragraph"> <p>From this frustration was born<strong>Absolute Rule 1b</strong>:</p> </div> <div class="paragraph"> <p><em><em>_ <strong>NEVER overwrite</strong>a config file with a`Write`complete overwrite when a`Edit`partial one suffices.<strong>NEVER replace</strong>sensitive values with fake values.<strong>Verify <code>git check-ignore</code> and <code>git ls-files</code></strong>before any modification. </em>_</em></p> </div> <div class="paragraph"> <p>This rule, now etched in stone in all my`AGENT.adoc` et `INDEX.adoc`files across four projects, was born from a real error that cost me an hour of manual work.</p> </div> </div> <div class="sect2"> <h3 id="_the_markdown_asciidoc_migration_session_1_cheroliv_com">The Markdown → AsciiDoc Migration (Session 1, cheroliv.com)</h3> <div class="paragraph"> <p>On April 25, 2026, on`cheroliv.com`, I make a radical decision: convert the entire governance from Markdown to AsciiDoc. It’s not about aesthetics. It’s functional. AsciiDoc offers a semantic structure that LLMs read better: hierarchical sections, typed tables, admonitions (<code>NOTE</code>, <code>WARNING</code>, <code>CAUTION</code>), and machine-readable document attributes.</p> </div> <div class="paragraph"> <p>Session 1 of`cheroliv.com`formalizes the structure:</p> </div> <div class="ulist"> <ul> <li> <p>Conversion of`AGENTS.md` en <code>AGENT.adoc</code></p> </li> <li> <p>Creation of specialized agents:`CODER.adoc`, <code>SCRUM_MASTER.adoc</code>, <code>PLANTUML_DESIGNER.adoc</code></p> </li> <li> <p>Creation of the Eager/Lazy structure:`INDEX.adoc`, <code>SESSIONS_HISTORY.adoc</code>, <code>AGENT_SESSION_MANAGER.adoc</code>, <code>SESSION_CHECKLIST.adoc</code>, <code>PROCEDURES.adoc</code></p> </li> </ul> </div> <div class="paragraph"> <p>A single commit:`90975e9 refactor: migrate agent governance from Markdown to AsciiDoc`. And the site continues to function.</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>The timeline above illustrates the actual progression. The tipping point is session 87: that’s when the frustration of repeated re-contextualization exceeds the tolerance threshold, and the Eager/Lazy method stops being an idea and becomes an obligation.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_strategy_eagerlazy_in_depth">The Strategy: Eager/Lazy In-Depth</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_philosophy_computer_cache_applied_to_cognition">Philosophy: Computer Cache Applied to Cognition</h3> <div class="paragraph"> <p>My approach is directly inspired by computer cache management. Everything that is<strong>critical and frequently used</strong>must be immediately accessible (<strong>Eager</strong>). Everything that is<strong>contextual or voluminous</strong>must be loaded on demand (<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 (Dashboard)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lazy (Owner’s Manual)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Size</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">< 100 lines, < 10k tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Unlimited, detailed</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Loading</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto, at session start</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">On agent request</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Content</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Absolute rules, current mission, critical state</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Session archives, full history, detailed procedures, technical references</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Role</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Immediately orient the agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Answer deep context questions</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_eager_files_the_dashboard">Eager Files: The Dashboard</h3> <div class="paragraph"> <p>These files live at the root of each project and are automatically loaded by the agent at the start of each session. They form the<strong>dashboard</strong>-- critical information, immediately 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="2181" height="426"> </div> </div> <div class="paragraph"> <p><strong><code>AGENT.adoc</code></strong>-- The master file. On`cheroliv.com`, it is 200 lines long and contains:</p> </div> <div class="ulist"> <ul> <li> <p>The project’s absolute rules (no commits without permission, no`rm`without confirmation)</p> </li> <li> <p>Project structure and code conventions</p> </li> <li> <p>Essential commands (<code>./gradlew serve</code>, <code>./gradlew test</code>)</p> </li> <li> <p>Epics and product backlog (prioritized user stories)</p> </li> <li> <p>Cross-cutting quality criteria (accessibility, responsive, compatibility)</p> </li> </ul> </div> <div class="paragraph"> <p>On`bakery-plugin`, Rule 0 is different:<strong><code>./gradlew -q publishToMavenLocal</code> is mandatory after every source code modification</strong>. Because testing the plugin without republishing the local JAR cost me an hour debugging code that hadn’t been packaged yet.</p> </div> <div class="paragraph"> <p><strong><code>PROMPT_REPRISE.adoc</code></strong>-- The mission for the current session. Updated at the end of each session, it contains:</p> </div> <div class="ulist"> <ul> <li> <p>The session number and priority mission</p> </li> <li> <p>Summary of the previous session (what was done, what remains)</p> </li> <li> <p>Acceptance criteria for the current session</p> </li> <li> <p>Specific technical reminders</p> </li> </ul> </div> <div class="paragraph"> <p><strong><code>.agents/INDEX.adoc</code></strong>-- The entry point. It summarizes absolute rules, recent sessions, and above all, the<strong>project portfolio</strong>managed with the same methodology. To date, five projects are listed:</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`** -- A recent addition (Session 109, plantuml-plugin) to further optimize Eager context. Instead of loading 200 lines of business context on the API key pool, I load 50 lines of essentials, and the other 150 lines remain LAZY in`*_REFERENCE.adoc`. Measured result: move from**~25k EAGER tokens to ~10k tokens**(60% gain). The agent no longer needs energy-consuming reminders. ==== The Missing Link: `opencode.json` I must confess something I almost forgot to document. Above all these .adoc files, there is a tiny JSON file without which nothing works. It's called`opencode.json`and it is six lines long. Literally six lines. [source,json] ---- { "$schema": "https://opencode.ai/config.json", "instructions": [ "AGENT.adoc" ] } ---- This file tells Opencode: "At startup, load`AGENT.adoc`automatically." Without it, the agent is a blank page, exactly as I described at the beginning of the article. With it, the agent already has the absolute rules, the project architecture, and the essential commands in hand — before I even say hello. I discovered the importance of this file by chance. On`bakery-plugin`, it didn't exist. I wondered why the agent was consistently more "lost" on this project than on others. The absolute rules were indeed in`AGENT.adoc`— but`AGENT.adoc`was never loaded. The agent only read what I told it to read, manually, every session. It was session 11 of`bakery-plugin`when I realized the`opencode.json`was missing. I created it — and session 12 started like the others. This file is so obvious to me now that I didn't even think of it. A classic developer's error of knowing the tool too well. Today, I systematically create it *before*`AGENT.adoc`. It is the first stone. ==== The Duality of `INDEX.adoc` Another subtlety that deserves explanation:`INDEX.adoc`lives in`.agents/`— a folder I presented as LAZY. Yet, I list it as EAGER in all my tables. There is an apparent tension here. Field reality:`.agents/INDEX.adoc`files are indeed loaded automatically at the start of the session, just like`AGENT.adoc` et `PROMPT_REPRISE.adoc`. They are in`.agents/`for organizational reasons — not to clutter the root — but their behavior is EAGER. On`plantuml-plugin`, `INDEX.adoc`is 200 lines and contains *complete* absolute rules with their history (lessons from past sessions), EPICs with scores, and the project portfolio. It is the document the agent consults to know "where we stand." On`bakery-plugin`, it is 150 lines with the roadmap and recent sessions. The intentional redundancy between`AGENT.adoc` et `INDEX.adoc`might be surprising. Absolute rules are present in both. Why? Because they fulfill two different roles: in`AGENT.adoc`, they are *explanatory* (the storytelling of the rule, the lesson learned); in`INDEX.adoc`, they are *executive* (the bare rule, without justification, for quick consultation). The agent reads`AGENT.adoc`once to *understand*; it re-reads`INDEX.adoc`every session to *apply*. Two uses, two 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 ---- This assumed redundancy is a design choice. It consumes ~50 additional lines of EAGER tokens — but it guarantees the agent always has the rules before its eyes, including in the concise format that facilitates immediate obedience. === LAZY Files: The Owner's Manual These files live in`.agents/`and are only read when the agent needs them. They constitute the true wealth of the method, as they accumulate project knowledge without polluting the current context. [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 ---- The tree above shows the actual structure of the`.agents/`folder on`plantuml-plugin`, the most mature project. Note the three-layer depth: root files (metadata),`sessions/`folder (chronological archives), and`archives/`folder (aggregations and summaries). This depth transforms governance from a simple TODO file into a**complete organizational memory**. **`.agents/sessions/{N}-{title}.adoc`**-- Detailed archives of each session. Currently: * `plantuml-plugin`:**133 archived sessions**(from session 1 to 133) * `bakery-plugin`:**11 sessions** * `magic-stick`:**23 sessions** * `cheroliv.com`:**9 formal sessions**+ 7 pre-system sessions retroactively reconstructed Each archive contains the full context of the session, decisions made, problems encountered and their resolution, commands executed and their output. **`.agents/SESSIONS_HISTORY.adoc`**-- A summary table of all sessions with a score. Example on`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_{month}.adoc</code></strong>-- Completed tasks archived by month, so as not to overload the active backlog. When a user story is finished, it migrates here. The backlog remains readable: maximum 10 active items.</p> </div> <div class="paragraph"> <p><strong><code>.agents/PROCEDURES.adoc</code></strong>-- Detailed templates of the end-of-session procedure. Long, but read only once by the agent when it learns the method. Afterwards, the procedure becomes mechanical.</p> </div> <div class="paragraph"> <p><strong><code>.agents/AGENT_MODUS_OPERANDI.adoc</code></strong>-- Complete strategic documentation. On`plantuml-plugin`, this file is<strong>900+ lines</strong>and is actually named`AGENT_METHODOLOGIES.adoc`— I changed the name between writing this article and the effective implementation. This kind of naming divergence is inevitable in a handcrafted system that evolves. The important thing is the naming convention: if the file documents the <strong>method</strong>, it starts with`AGENT_`or an explicit prefix. It documents the Eager/Lazy methodology, patterns to follow, and anti-patterns to avoid. It is LAZY because an agent doesn’t need to re-read the whole strategy every session, only when there is ambiguity.</p> </div> <div class="paragraph"> <p><strong><code>*_REFERENCE.adoc</code></strong> — Project-specific technical references. On`magic-stick`, two dense LAZY files:</p> </div> <div class="ulist"> <ul> <li> <p><code>AB_PARTITION_REFERENCE.adoc</code>(147 lines) — GPT A/B partition architecture,`update-system.sh`scripts, estimated sizes, rollback mechanism</p> </li> <li> <p><code>BOOT_TEST_REFERENCE.adoc</code>(144 lines) — QEMU + VNC procedure to test ISO boot without physical hardware, BIOS/UEFI checklist, CI/CD limitations</p> </li> </ul> </div> <div class="paragraph"> <p>On`plantuml-plugin`:</p> </div> <div class="ulist"> <ul> <li> <p><code>ARCHITECTURE.adoc</code>(134 lines) — Structure of the 11 data classes, points of attention (traps to avoid), optimized test commands</p> </li> <li> <p><code>API_KEY_POOL_REFERENCE.adoc</code>-- Complete details of the key pool (LAZY while`ESSENTIALS`is EAGER)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_specialized_agents_a_virtual_team">Specialized Agents: A Virtual Team</h2> <div class="sectionbody"> <div class="paragraph"> <p>Governance is not limited to passive files. I’ve formalized<strong>specialized agent roles</strong>in dedicated LAZY files, which define the expected workflow according to the task type.</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">File</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Role</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Project</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">FTL/CSS/JS implementation, semantic tags, accessibility criteria</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">US planning, breakdown into sub-tasks, dependency detection</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">Diagram creation, PUML syntax, JBake integration</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The file`CODER.adoc`on`cheroliv.com`contains concrete rules: <em>Only one`<h1>`per page</em>, <em>Prefix paths with`${content.rootpath}`</em>, <em>Declare language`<html lang="${content.lang!"fr"}">`</em>. These conventions, written once, have been automatically respected by the agent since session 1.</p> </div> <div class="paragraph"> <p>The file`SCRUM_MASTER.adoc`imposes a deliverable structure:<strong>Objective</strong>, <strong>Tasks</strong>(ordered with assignment),<strong>Acceptance Criteria</strong>, <strong>Risks</strong>. When I ask for an action plan, the agent produces this structure without me asking for it. Governance<strong>programs</strong>the agent.</p> </div> <div class="sect3"> <h4 id="_when_specialized_agents_become_indispensable">When Specialized Agents Become Indispensable</h4> <div class="paragraph"> <p>The creation of specialized agents follows a natural curve. At the start of a project, you don’t need them —`AGENT.adoc`is largely sufficient. But when the project grows (say, beyond 20 sessions), two signals should alert you:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The agent mixes conventions from two distinct domains (e.g., PlantUML syntax and CSS rules)</p> </li> <li> <p>You spend more time correcting the agent on conventions you’ve already explained 5 times</p> </li> </ol> </div> <div class="paragraph"> <p>On`cheroliv.com`, it happened at session…​ 1. Yes, from the start. Because this project is a website with three languages (FTL, CSS, JS), AsciiDoc content, and PlantUML diagrams — three domains that have nothing to do with each other. The CODER agent needs to know font sizes and media queries; the PLANTUML_DESIGNER agent needs to know the`@startuml`syntax. Without separation, the CODER agent suggested diagrams to me, and vice versa. Chaos.</p> </div> <div class="paragraph"> <p>On`jhipster-gradle-plugins`, I created two specialized agents adapted to Gradle plugin development:`PLUGIN_DEVELOPER.adoc` et <code>BACKLOG_MANAGER.adoc</code>. The first encodes all Kotlin/Gradle conventions (no`!!<code>, data classes for models,</code>@TaskAction`for tasks). The second knows that`persistence`must be stable before`assistant`starts its development — a critical dependency in a mono-repo.</p> </div> <div class="paragraph"> <p>The mistake to avoid: creating too many agents too early.<code>plantuml-plugin`waited until session 108 before formalizing a specialized agent for the API key pool. Before that, the business context fit in`AGENT.adoc</code>. The empirical rule: a specialized agent is justified when its business domain exceeds 100 lines of documentation.</p> </div> </div> <div class="sect3"> <h4 id="_session_naming_convention">Session Naming Convention</h4> <div class="paragraph"> <p>A detail that seems futile but becomes critical when reaching 100 sessions. How to name archive files?</p> </div> <div class="paragraph"> <p>I learned the hard way that a convention is necessary — four projects, four different formats at the start, and I couldn’t find anything. Today, the convention I’ve stabilized is:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- {N}-{type}-{sujet-kebab-case}.adoc ---- Concrete examples: * `1-chore-migration-gouvernance-agent.adoc`— session 1, type chore * `10-solidification-tests.adoc`— session 10, without explicit type (subject suffices) * `036-debug-graphify-symlink-epic9.adoc`— session 36 with 3-digit number for sorting The session number is the primary sorting criterion. Projects using 3-digit numbers (001, 036, 133) avoid lexicographical sorting issues when exceeding 99. This is what I now use on`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`. The type is optional and derived from session keywords (debug, feature, refactor, docs, chore, test). The subject in kebab-case is the most important part: it must allow finding a session without opening the file. If you wonder "which session was it where we fixed the integration test timeout?", the answer is`124-fix-timeout-integration-test.adoc`. For reconstructed historical sessions (projects born before governance), I use negative numbers. On`cheroliv.com`, sessions -6 to 0 cover the entire pre-governance history of the project. And for "undocumented" or lost sessions, I create an entry in`SESSIONS_HISTORY.adoc`without a corresponding archive, with a score`?`. It's more honest than pretending. [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` — Step 5 Dissected Step 5 of the end-of-session procedure is the most mysterious. It says "Update`TEST_COVERAGE_ANALYSIS.adoc`if tests were added or modified." But what does this file look like? On`plantuml-plugin`, it evolved from a few lines to a complete structure. Here is its stabilized form: [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% |=== ---- The value is not in the file itself — it's the obligation to *note* what changed. Without this step, after 50 sessions, you no longer know which tests cover what. Neither does the agent. The file becomes the single source of truth for the project's test coverage. For projects without traditional tests (like`magic-stick`which tests bash scripts), step 5 is replaced by`SCRIPT_VERIFICATION.adoc`. The mechanism is the same: a file that tracks the validation state of scripts. Adapt step 5 to your project, but never skip it. It is the safety net that prevents silent regression. If your project has *no* tests — neither unit, nor functional, nor script — create the empty file anyway with a section "To do: define a test strategy." It's a bookmark that will remind your future self that this subject hasn't been addressed. [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 ---- The diagram above shows the complete life cycle of a session. The key point is the bifurcation after EAGER loading: either the mission is clear enough to execute directly (80% of cases), or the agent loads LAZY data to resolve an ambiguity (20% of cases). This discrimination is what saves tokens. == End-of-Session Procedure: The Golden Rule === Why It Is Essential Without this procedure, the Eager/Lazy strategy is useless. This is what transforms the session's work into persistent information. It is executed**upon the user's explicit request**(keywords: "end of session", "I'm leaving", etc.), and it is**mandatory**-- no exceptions, no omissions. The file`SESSION_CHECKLIST.adoc`defines metrics for an ideal session: * Duration: 15-30 minutes * Modified files: 1-3 maximum * LLM exchanges: 5-10 messages * Context tokens: < 50k And signs that it's time to change sessions: _The LLM repeats errors already corrected_, _More than 3 files modified in parallel_, _Conversation > 50 messages_. The golden rule:**Better 5 sessions of 20 minutes than one session of 2 hours with debugging chaos.** === The 6-Step Flow (Silently) [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 ---- === Results of 150+ Sessions Here is what this procedure, applied systematically across my four projects, yielded: **plantuml-plugin**: * **133 sessions**since the project start * **240/240 tests PASS**(100% coverage) -- EPICs 1-7 completed * **57 Cucumber BDD scenarios**validated * Safety rule on config files born from a real error (Session 2 bakery-plugin) **bakery-plugin**: * **11 sessions**in two weeks * Supabase → Firebase migration completed (9 tests corrected) * EPIC 6 (publishProfile) functional in production * Rule 0 created:`publishToMavenLocal`mandatory after each mod **magic-stick**: * **23 sessions**to build a live Xubuntu system with A/B partition * First ISO generated at session 10 * QEMU + VNC boot tests formalized (144-line LAZY documentation) * SourceForge CI/CD functional **cheroliv.com**: * **9 formal sessions**+ reconstruction of 7 pre-system sessions * Article 0101 (OpenCode PATH) published * Article 0108 (this one) rewritten after analyzing its gaps * Complete governance migrated from Markdown to AsciiDoc === The Final Checklist After silent execution of the 6 steps, the agent must display a confirmation checklist:</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>Absolute rule</strong>: no step can be marked`[✅]`if the file has not been effectively modified and verified.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_bootstrap_guide_day_1_session_0">The Bootstrap Guide: Day 1, Session 0</h2> <div class="sectionbody"> <div class="paragraph"> <p>You are convinced by the method. You want to apply it to a new project. Where to start?</p> </div> <div class="paragraph"> <p>I experienced this moment on April 28, 2026. I open Opencode on`jhipster-gradle-plugins`, my mono-repo of two JHipster Gradle plugins. It’s a project that already exists — the code is there, the Gradle tasks work. But agent governance? Zero. Blank page. Like`plantuml-plugin`at its session 1, months ago.</p> </div> <div class="paragraph"> <p>Here is the exact procedure I followed, and will follow for every new project. Note the order carefully — it is 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="1752" height="2939"> </div> </div> <div class="sect2"> <h3 id="_step_0_create_opencode_json">Step 0: Create <code>opencode.json</code></h3> <div class="paragraph"> <p>This is the first file. Not`AGENT.adoc`, not`INDEX.adoc`.<code>opencode.json`first, for one simple reason: if you create`AGENT.adoc`first, you will forget to create the bridge that loads it automatically. I did it on`bakery-plugin</code>, I know what I’m talking about.</p> </div> </div> <div class="sect2"> <h3 id="_step_1_create_folders">Step 1: Create Folders</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>Two empty folders.`sessions/`will receive the archives of each session.`archives/`will receive the monthly COMPLETED_TASKS_ARCHIVE. These folders must exist <strong>before</strong> the agent needs to write to them. An agent that has to create the folder AND the file at the same time is an agent that might fail silently.</p> </div> </div> <div class="sect2"> <h3 id="_step_2_create_agent_adoc_the_master_file">Step 2: Create <code>AGENT.adoc</code> — The Master File</h3> <div class="paragraph"> <p>Minimal structure for the first version (it will grow):</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>MANDATORY STOP</strong>before rm, Write, deletion:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>READ the file in full</p> </li> <li> <p>VERIFY git ls-files</p> </li> <li> <p>ASK for confirmation</p> </li> <li> <p>WAIT for "yes"</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_project">Project</h2> <div class="sectionbody"> <div class="paragraph"> <p><strong>Name</strong>: …​ <strong>Stack</strong>: …​ <strong>Documentation</strong>: AsciiDoc</p> </div> </div> </div> <div class="sect1"> <h2 id="_absolute_rules">Absolute Rules</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_0_dev_environment">0. DEV ENVIRONMENT</h3> <div class="paragraph"> <p>Essential commands…​</p> </div> </div> <div class="sect2"> <h3 id="_1_commitsgit">1. COMMITS/GIT</h3> <div class="paragraph"> <p>Formal prohibition…​</p> </div> </div> <div class="sect2"> <h3 id="_1b_configuration_files_absolute_safety_rule">1b. CONFIGURATION FILES — ABSOLUTE SAFETY RULE</h3> <div class="paragraph"> <p>Never overwrite…​</p> </div> </div> <div class="sect2"> <h3 id="_2_end_of_session_tests">2. END-OF-SESSION TESTS</h3> <div class="paragraph"> <p>Formal prohibition…​</p> </div> </div> <div class="sect2"> <h3 id="_3_end_of_session_procedure">3. END-OF-SESSION PROCEDURE</h3> <div class="paragraph"> <p>The 6 mandatory steps…​</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_context_management_lazyeager">Context Management — LAZY/EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>EAGER files / LAZY files…​</p> </div> <div class="paragraph"> <p>This minimal template allows the agent to start. The rich version — with project structure, key components, EPICs, backlog — will come at session 1, when the agent already has the basic rules in hand and can help you enrich the document.</p> </div> <div class="sect2"> <h3 id="_step_3_create_prompt_reprise_adoc_session_1_mission">Step 3: Create <code>PROMPT_REPRISE.adoc</code> — Session 1 Mission</h3> <div class="paragraph"> <p>A file that explicitly says: "This is session 1, mission to be defined." Maximum 70 lines, with a Session 0 section (bootstrap summary) and a Session 1 section (priorities to be defined with the user).</p> </div> </div> <div class="sect2"> <h3 id="_step_4_create_agentsindex_adoc_the_entry_point">Step 4: Create <code>.agents/INDEX.adoc</code> — The Entry Point</h3> <div class="paragraph"> <p>The file that will contain the absolute rules (executive version) and the session table. For the bootstrap, it lists rules 0 to 3 in their concise format, the project portfolio (including the new project with a 🆕 emoji), and the empty roadmap ready to be filled.</p> </div> </div> <div class="sect2"> <h3 id="_step_5_create_structuring_lazy_files">Step 5: Create Structuring LAZY Files</h3> <div class="paragraph"> <p>In order:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/SESSIONS_HISTORY.adoc</code>— a table with only session 0</p> </li> <li> <p><code>.agents/SESSION_CHECKLIST.adoc</code>— the "When to change session" template</p> </li> <li> <p><code>.agents/PROCEDURES.adoc</code>— the complete 6-step procedure + EAGER/LAZY</p> </li> <li> <p><code>.agents/AGENT_SESSION_MANAGER.adoc</code>— the archive template</p> </li> <li> <p><code>.agents/TEST_COVERAGE_ANALYSIS.adoc</code>— the test tracking table, empty at the start</p> </li> </ol> </div> <div class="paragraph"> <p>If your project has a complex business domain (like`jhipster-gradle-plugins`with its persistence/assistant mono-repo), create the specialized agents now:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/PLUGIN_DEVELOPER.adoc</code>— code conventions and dependency boundary (if plugin)</p> </li> <li> <p><code>.agents/BACKLOG_MANAGER.adoc</code>— planning structure and identified risks</p> </li> </ol> </div> <div class="paragraph"> <p>Do not create agents you will not use. An agent without concrete conventions to encode is a dead file that pollutes`.agents/`.</p> </div> </div> <div class="sect2"> <h3 id="_step_6_add_the_project_to_the_portfolio_of_all_projects">Step 6: Add the Project to the Portfolio of ALL Projects</h3> <div class="paragraph"> <p>This is the step that is systematically forgotten. Every`INDEX.adoc`of every project contains a "Project Portfolio" table that lists ALL projects using the same methodology. When you create a new project, you must:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Add a line to the new project’s portfolio (logical)</p> </li> <li> <p>Add a line to the portfolio of ALL existing projects — yes, all of them</p> </li> </ol> </div> <div class="paragraph"> <p>Across my four (now five) projects, this means opening the`INDEX.adoc` de <code>magic-stick</code>, <code>bakery-gradle</code>, <code>cheroliv.com</code>, <code>plantuml-gradle`and adding the line`jhipster-gradle-plugins | Session 1 | …​ | 2026-04-28 🆕</code>.</p> </div> <div class="paragraph"> <p>It’s tedious. It’s manual. It’s also the only way to guarantee that, regardless of the project you’re working on, the agent knows which other projects exist and their state. At session 012 of`magic-stick`, the agent detected two inconsistencies in the portfolio —`bakery-gradle`had its COMPLETED_TASKS_ARCHIVE lagging, and`plantuml-gradle`had a mismatch between its procedure documentation (5 steps) and its INDEX (6 steps). Without this transverse table, these inconsistencies would have remained invisible.</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>I can hear you now: "But that’s duplication!" Yes. It’s intentional duplication. Each`INDEX.adoc`is autonomous. If you open a session on`magic-stick`, the agent must know that`plantuml-gradle`is at session 133 without having to open a file in another directory. That is the price of independence between projects — and it is 5 lines per portfolio.</p> </div> </div> <div class="sect2"> <h3 id="_what_the_bootstrap_costs">What the Bootstrap Costs</h3> <div class="paragraph"> <p>All this takes 20 minutes. Twenty minutes once, so as to never lose twenty again at the start of every session. The ROI is immediate: from session 2 on, the agent picks up exactly where you left session 1.</p> </div> <div class="paragraph"> <p>On`jhipster-gradle-plugins`, this bootstrap took me exactly 18 minutes — from`mkdir .agents/<code>to the last`INDEX.adoc`updated in the`magic-stick`portfolio. Session 1, which follows, will start with an agent that already knows the mono-repo structure, Gradle commands, and the critical boundary between`persistence/</code>(lightweight) and`assistant/`(heavy). Twenty minutes well invested.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_now_5_projects_5_governances_1_method">4 (now 5) Projects, 5 Governances, 1 Method</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Eager/Lazy system is not a copy-paste boilerplate. Each project adapted the method to its specificities.</p> </div> <div class="sect2"> <h3 id="_cheroliv_com_the_personal_site">cheroliv.com: The Personal Site</h3> <div class="paragraph"> <p><strong>Specificity</strong>: Editorial content, WCAG 2.1 AA accessibility, static JBake. <strong>Adaptation</strong>: Six prioritized epics (P0-P4), specialized agents (CODER, SCRUM_MASTER, PLANTUML_DESIGNER), cross-cutting acceptance criteria on accessibility. <strong>Emblematic Rule</strong>:`./gradlew serve`mandatory, formal prohibition of external`jbake.sh`scripts.</p> </div> </div> <div class="sect2"> <h3 id="_bakery_gradle_the_multi_purpose_plugin">bakery-gradle: The Multi-Purpose Plugin</h3> <div class="paragraph"> <p><strong>Specificity</strong>: Gradle plugin with publishing tasks, Firebase code generation, YAML parsing. <strong>Adaptation</strong>: Rule 0 (publishToMavenLocal), safety rule on config files reinforced by the`site.yml`incident, EPIC 9 and 10 on multi-file configuration. <strong>Emblematic Rule</strong>:`publishToMavenLocal`after every plugin source code modification.</p> </div> </div> <div class="sect2"> <h3 id="_plantuml_gradle_the_ai_plugin">plantuml-gradle: The AI Plugin</h3> <div class="paragraph"> <p><strong>Specificity</strong>: LangChain4j integration, PlantUML diagram generation via LLM, tests with cloud API keys. <strong>Adaptation</strong>: Dense LAZY documentation (ARCHITECTURE, API_KEY_POOL_REFERENCE, DATASET_FINETUNING), numbered EPICs (1-11 completed, 107+ in progress), optimized EAGER/LAZY separation (60% token gain). <strong>Emblematic Rule</strong>:`*_ESSENTIALS.adoc`files (50 lines) vs`*_REFERENCE.adoc`(unlimited) for the API key pool.</p> </div> </div> <div class="sect2"> <h3 id="_magic_stick_the_live_system">magic-stick: The Live System</h3> <div class="paragraph"> <p><strong>Specificity</strong>: Live Linux ISO build (Xubuntu), GPT A/B partitioning, CI/CD with SourceForge. <strong>Adaptation</strong>: Complex LAZY technical references (AB_PARTITION, BOOT_TEST), SCRIPT_VERIFICATION.adoc as a specific step 5 (no traditional tests, but bash script verification). <strong>Emblematic Rule</strong>skipped in CI (non-privileged runners), tests reserved for local environments with Docker`isoTestAB`.`--privileged`Cross-Cutting Absolute Rules</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_a_few_critical_rules_that_appear_in_the_eager">A few critical rules that appear in the Eager</h2> <div class="sectionbody"> <div class="paragraph"> <p>file and apply to all sessions across all projects:`AGENT.adoc`Dev Environment</p> </div> <div class="paragraph"> <p><strong>✅ Use the project-specific command (</strong></p> </div> <div class="ulist"> <ul> <li> <p>, etc.)<code>./gradlew serve</code>, <code>./gradlew functionalTest</code>❌ Prohibited to use non-versioned external scripts</p> </li> <li> <p>Git</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ Read-only allowed (</strong></p> </div> <div class="ulist"> <ul> <li> <p>)<code>git status</code>, <code>git diff</code>, <code>git log</code>❌</p> </li> <li> <p>prohibited without explicit permission`git add`, <code>git commit</code>, <code>git push</code>❌</p> </li> <li> <p>prohibited except under meticulously respected conditions`git commit --amend`Configuration Files</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Never overwrite a config file with a</strong></p> </div> <div class="ulist"> <ul> <li> <p>complete overwrite when a`Write`partial one suffices`Edit`❌ Never replace sensitive values with fake values</p> </li> <li> <p>❌ Verify</p> </li> <li> <p>before any modification`git check-ignore` et `git ls-files`Tests</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Never run tests during the end-of-session procedure without explicit permission</strong></p> </div> <div class="ulist"> <ul> <li> <p>Forbidden Tools</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌</strong></p> </div> <div class="ulist"> <ul> <li> <p> — governance is done via AsciiDoc files, not via external tools`TodoWrite` et `Task`Anti-Patterns: What 150+ Sessions Taught Me</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_in_hindsight_certain_errors_have_become_patterns_so_predictable_that_i_can_list_them_as_anti_patterns_traps_that_every_new_project_will_likely_fall_into_here_they_are_ranked_by_frequency">In hindsight, certain errors have become patterns so predictable that I can list them as anti-patterns — traps that every new project will likely fall into. Here they are, ranked by frequency.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Anti-Pattern 1: The Agent without <code>opencode.json</code></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="1071" height="1060"> </div> </div> <div class="sect2"> <h3 id="_this_is_the_number_one_error_youve_written_a_magnificent">This is the number one error. You’ve written a magnificent</h3> <div class="paragraph"> <p>of 200 lines, but it’s never loaded automatically. The agent starts naked. You spend 20 minutes re-contextualizing it — exactly what the method is supposed to avoid.<code>AGENT.adoc</code><strong>Symptom</strong> : The agent asks basic questions about the project structure even though everything is in</p> </div> </div> <div class="sect2"> <h3 id="_at_session_2_of_your_project_you_create_5_specialized_agents_none_have_real_content_they_are_all_stubs_result">At session 2 of your project, you create 5 specialized agents. None have real content, they are all stubs. Result:</h3> <div class="paragraph"> <div class="title"><code>AGENT.adoc</code><strong>Correction</strong> : Create with the`opencode.json`block. Verify that the file exists in the Opencode working directory.`instructions: ["AGENT.adoc"]`Anti-Pattern 2: Too Many Agents Too Soon</div> <p>is polluted with empty files, and the agent hesitates on which one to load.<code>.agents/</code><strong>Symptom</strong> : Agent files containing only "To be defined" or a 10-line empty structure.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> : A specialized agent is justified when its business domain exceeds 100 lines or it encodes at least 5 concrete rules. Below that, the content fits in .`AGENT.adoc`Anti-Pattern 3: The Ghost PROMPT_REPRISE</p> </div> </div> <div class="sect2"> <h3 id="_is_updated_but_only_at_the_end_of_the_session_when_the_agent_executes_the_procedure_meanwhile_the_sessions_actual_mission_has_drifted_we_fixed_an_unforeseen_bug_instead_of_implementing_the_planned_feature_the">is updated…​ but only at the end of the session, when the agent executes the procedure. Meanwhile, the session’s actual mission has drifted — we fixed an unforeseen bug instead of implementing the planned feature. The</h3> <div class="paragraph"> <p><code>PROMPT_REPRISE.adoc`end-of-session summary does not reflect what <strong>really</strong> happened.`PROMPT_REPRISE.adoc</code><strong>Symptom</strong> : The "Priorities" section of</p> </div> <div class="paragraph"> <p>mentions a feature that wasn’t touched, while you spent the session on a critical bug.<code>PROMPT_REPRISE.adoc</code><strong>Correction</strong> : Update in real-time when the session drifts from its initial mission. Do not wait for the end-of-session procedure to document the change in direction. 30 seconds of editing during the session are better than a`PROMPT_REPRISE.adoc`lying summary.`PROMPT_REPRISE`Anti-Pattern 4: The Empty Archive</p> </div> </div> <div class="sect2"> <h3 id="_the_end_of_session_procedure_creates_the_archive_but_the_agent_eager_to_display_its_checklist_fills_the_template_with_placeholders">The end-of-session procedure creates the archive…​ but the agent, eager to display its checklist, fills the template with placeholders.</h3> <div class="paragraph"> <p>becomes "Details to be completed later." This "later" never comes.<code>{detail}</code><strong>Symptom</strong> : Session archives containing the words "TODO", "to be completed", or empty sections.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> : The absolute rule says no step can be marked [✅] if the file has not been effectively modified. Apply it to yourself: re-read the archive before displaying the checklist. If a section is empty, fill it now. Anti-Pattern 5: The Ghost Portfolio</p> </div> </div> <div class="sect2"> <h3 id="_you_create_a_new_project_with_perfect_governance_but_you_forget_to_add_it_to_the_portfolio_of_other_projects_three_weeks_later_you_open_a_session_on">You create a new project with perfect governance. But you forget to add it to the portfolio of other projects. Three weeks later, you open a session on</h3> <div class="paragraph"> <p>and the agent tells you that you have 4 projects. You have 5. The agent doesn’t know.<code>magic-stick</code><strong>Symptom</strong> : The project count in portfolios does not match reality.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> : Script the portfolio update, or at minimum maintain a post-bootstrap checklist that includes "Update the portfolio of all existing projects." This is the most tedious step of the method, and therefore the most frequently omitted. Anti-Pattern 6: Hidden Redundancy</p> </div> </div> <div class="sect2"> <h3 id="_you_copy_paste_the_same_50_line_backlog_into">You copy-paste the same 50-line backlog into</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>In the next session, you update one but not the other. Your two EAGER files contradict each other.<code>AGENT.adoc</code> et <code>INDEX.adoc</code><strong>Symptom</strong> : Divergences between EPICs listed in</p> </li> </ol> </div> <div class="paragraph"> <p>and those in`AGENT.adoc`.<code>INDEX.adoc</code><strong>Correction</strong> : Redundancy must be <strong>assumed and bounded</strong>. contains the detailed backlog with user stories.<code>AGENT.adoc`contains ONLY the summary table of EPICs (name, progress, priority). If the two diverge,`INDEX.adoc`is the authority — because it’s the one updated every end-of-session. Document this rule in your`INDEX.adoc</code>: "In case of divergence between AGENT.adoc and INDEX.adoc, INDEX.adoc is the source of truth."`AGENT.adoc`Anti-Pattern 7: The Session Too Long</p> </div> </div> <div class="sect2"> <h3 id="_you_ignore_the_signals_of_the">You ignore the signals of the</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>2 hours, 85 messages, 12 files modified. The agent is looping, so are you. You should have changed sessions 45 minutes ago.<code>SESSION_CHECKLIST.adoc</code><strong>Symptom</strong> : The LLM repeats errors already corrected, context tokens exceed 80k, you modified both</p> </li> </ol> </div> <div class="paragraph"> <p>in the same session.<code>persistence/</code> et <code>assistant/</code><strong>Correction</strong> : The exists for a reason. Respect it. The golden rule is not a suggestion. 5 sessions of 20 minutes > 1 session of 2 hours.`SESSION_CHECKLIST.adoc`Why AsciiDoc?</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i_chose_asciidoc_for_several_pragmatic_reasons_that_have_a_direct_impact_on_governance_efficiency">I chose AsciiDoc for several pragmatic reasons that have a direct impact on governance efficiency:</h2> <div class="sectionbody"> <div class="paragraph"> <p>Rich semantic structure</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>: sections, tables, admonitions, document attributes. An agent reads a structured document better than a wall of text.</strong>Document attributes</p> </li> <li> <p><strong>(</strong>) which allow defining metadata readable by both machine and human.<code>:jbake-type:</code>, `:jbake-status:`Compatibility with JBake</p> </li> <li> <p><strong>: my static site is generated by JBake, which natively processes AsciiDoc. Governance files and blog posts share the same format. My blog post <strong>on</strong> governance is written in the same format as the governance itself.</strong>Longevity</p> </li> <li> <p><strong>: AsciiDoc is a proven technical documentation format with a stable specification.</strong>Result: Seamless Continuity</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_since_i_put_this_system_in_place_moving_from_one_opencode_session_to_another_has_become_fluid_the_agent_picks_up_exactly_where_i_left_off_without_me_having_to_re_contextualize_anything">Since I put this system in place, moving from one Opencode session to another has become fluid. The agent picks up exactly where I left off, without me having to re-contextualize anything.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Decisions made in session 3 are accessible in session 133. The backlog remains consistent across five simultaneous projects. Security rules (especially on git and config files) are respected because they are omnipresent in the Eager file.</p> </div> <div class="paragraph"> <p>The numbers speak:</p> </div> <div class="paragraph"> <p>150+ archived sessions</p> </div> <div class="ulist"> <ul> <li> <p><strong>in total</strong>60% of EAGER tokens saved</p> </li> <li> <p><strong>after optimization (Session 109)</strong>Zero reminders necessary</p> </li> <li> <p><strong>regarding the business context of the API key pool</strong>100% of tests PASS</p> </li> <li> <p><strong>on plantuml-plugin (240/240)</strong>A single catastrophe</p> </li> <li> <p><strong>(Session 2 bakery-plugin) which gave birth to the absolute safety rule</strong>It is a</p> </li> </ul> </div> <div class="paragraph"> <p>handcrafted system<strong>, built with the tools of the trade (AsciiDoc, git, Gradle), without dependency on a proprietary platform. It reflects my fundamental conviction:</strong>a credible developer builds and uses their own tools<strong>.</strong>Links</p> </div> </div> </div> <div class="sect1"> <h2 id="_my_site_cheroliv_comhttpscheroliv_com">My site: [cheroliv.com](<a href="https://cheroliv.com" class="bare">https://cheroliv.com</a>)</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>The project</p> </li> <li> <p>: [github.com/cheroliv/bakery-gradle-plugin](<a href="https://github.com/cheroliv/bakery-gradle-plugin)`bakery-gradle`The" class="bare">https://github.com/cheroliv/bakery-gradle-plugin)`bakery-gradle`The</a> project</p> </li> <li> <p>: [github.com/cheroliv/plantuml-gradle-plugin](<a href="https://github.com/cheroliv/plantuml-gradle-plugin)`plantuml-gradle`The" class="bare">https://github.com/cheroliv/plantuml-gradle-plugin)`plantuml-gradle`The</a> project</p> </li> <li> <p>: [github.com/cheroliv/magic-stick](<a href="https://github.com/cheroliv/magic-stick)`magic-stick`The" class="bare">https://github.com/cheroliv/magic-stick)`magic-stick`The</a> project</p> </li> <li> <p>: [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>)<code>cheroliv.com</code><strong>The code we write for ourselves is the laboratory for the code we teach others.</strong></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/en/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="#_the_scene_four_screenshots_two_renderings">The scene: four screenshots, two renderings</a> <ul class="sectlevel2"> <li><a href="#_local_rendering">Local Rendering</a></li> <li><a href="#_online_rendering">Online Rendering</a></li> </ul> </li> <li><a href="#_the_diagnostic_serve_was_not_pointing_to_the_right_folder">The diagnostic: <code>serve</code> was not pointing to the right folder</a></li> <li><a href="#_the_root_cause_jbake_cli_doesnt_work_that_way">The root cause: JBake CLI doesn’t work that way</a></li> <li><a href="#_the_solution_positional_arguments_not_flags">The solution: positional arguments, not flags</a></li> <li><a href="#_quick_verification_with_curl">Quick verification with curl</a></li> <li><a href="#_why_this_bug_was_vicious">Why this bug was vicious</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 10 minutes</div> <p>You know that moment when your local site looks like nothing, but once deployed online everything is perfect? That’s what happened to me with my JBake Gradle plugin. The task`serve`displayed square buttons, dark text on a black background, and weirdly missing CSS. Yet`publishSite`generated the same site, and it was impeccable. The culprit was neither the CSS, nor the browser, nor the cache. It was a line of Kotlin code — and a bad habit with command-line arguments.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_four_screenshots_two_renderings">The scene: four screenshots, two renderings</h2> <div class="sectionbody"> <div class="paragraph"> <p>It was after a system crash. I had taken four screenshots to compare the local rendering (<code>./gradlew serve`on`localhost:8820</code>) with the online rendering (`publishSite`on GitHub Pages). Two screenshots per page: the top and the bottom.</p> </div> <div class="sect2"> <h3 id="_local_rendering">Local Rendering</h3> <div class="paragraph"> <p><strong>Top of page</strong>— The <strong>Project</strong> and <strong>Template</strong> buttons are<strong>small, rectangular</strong>, with standard colors (blue and green). The <strong>Start Writing</strong> card has a<strong>solid black background</strong>, without a border.</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>Bottom of page</strong>— The subtitle <strong>"Latest articles and resources"</strong> is<strong>almost unreadable</strong>, too dark on a black background. The dates under the blog images ("17 October 2013", etc.) are<strong>missing</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="_online_rendering">Online Rendering</h3> <div class="paragraph"> <p><strong>Top of page</strong>— The same buttons are<strong>large, oval, flashy neon green</strong>, uppercase text. The card has a<strong>rounded white border with a drop shadow</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>Bottom of page</strong>— The subtitle is<strong>clearly legible</strong>. The dates are<strong>visible</strong>. The article cards have<strong>rounded corners</strong>and the titles are<strong>bold</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>First reflex: the theme. I use a dynamic theme system (light, dark, high-contrast) based on`localStorage`. Maybe the local store triggered a high-contrast theme? No. I had already writtenhttps://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[an entire article on theme preloading], I know how it works. And besides, even in high-contrast mode, the CSS structure (oval buttons, shadows) should have been there. It wasn’t.</p> </div> <div class="paragraph"> <p>Second reflex: browser cache. No, I had tested with clean profiles. The diff persisted.</p> </div> <div class="paragraph"> <p>Third reflex:`serve`was not serving the same files as`publishSite`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_diagnostic_serve_was_not_pointing_to_the_right_folder">The diagnostic: <code>serve</code> was not pointing to the right folder</h2> <div class="sectionbody"> <div class="paragraph"> <p>My Gradle plugin`bakery`has two main tasks:</p> </div> <div class="ulist"> <ul> <li> <p><code>bake</code>: generates the static site in`build/bake/`</p> </li> <li> <p><code>serve</code>: launches a local web server</p> </li> <li> <p><code>publishSite</code>: pushes`build/bake/`to GitHub Pages</p> </li> </ul> </div> <div class="paragraph"> <p>The divergence could only come from`serve`. Si <code>publishSite`published the correct content, then`build/bake/`was correct. If`serve`displayed something else, it meant it wasn’t serving`build/bake/</code>.</p> </div> <div class="paragraph"> <p>Let’s look at the code. In`SiteManager.kt`, the task`serve`is defined as follows:</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`is the entry point of the JBake 2.7.0 CLI. The idea: pass</code>-b`for the source folder and`-s`for the destination folder, then launch the server mode. Except that…​</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_root_cause_jbake_cli_doesnt_work_that_way">The root cause: JBake CLI doesn’t work that way</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0 expects<strong>positional arguments</strong>for source and destination, then optional flags. The signature is:</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>Or in my code, I wrote:</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 interpreted this as:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ parses the "bake" flag (boolean), consumed</p> </li> <li> <p><code>/path/to/site</code>→ becomes positional argument 1 (source)</p> </li> <li> <p><code>-s</code>→ parses the "serve" flag (boolean), server launched<strong>immediately</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ becomes an orphan argument, ignored or misinterpreted</p> </li> </ol> </div> <div class="paragraph"> <p>Result: JBake took`/path/to/site`as the source,<strong>ignored the provided destination</strong>(<code>build/bake</code>), and used its default directory (often`./output`or a temporary copy). The`css/styles.css`file from the build was therefore overwritten or ignored, and an old default CSS (without custom variables, without rounded corners, without shadows) was served.</p> </div> <div class="paragraph"> <p>In comparison,<code>bake</code> et <code>publishSite`use the<strong>official JBake Gradle plugin</strong>(`jbake-gradle-plugin</code>) which writes properly into`build/bake/`via the Gradle API. They do not go through the CLI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_positional_arguments_not_flags">The solution: positional arguments, not flags</h2> <div class="sectionbody"> <div class="paragraph"> <p>The correction is trivial — once you know it. Simply pass the source and destination as positional arguments, then`-s`last:</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>That’s it. Three lines changed, bug resolved.</p> </div> <div class="paragraph"> <p>After local publication of the plugin (<code>publishToMavenLocal</code>), un `./gradlew serve`launches JBake with the correct syntax:</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>And this time, the Jetty server integrated into JBake correctly serves the content of`build/bake/`— identical to what is published online.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/serve-vs-publish-diagram.svg" alt="serve vs publish diagram" width="1141" height="348"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_quick_verification_with_curl">Quick verification with curl</h2> <div class="sectionbody"> <div class="paragraph"> <p>To ensure the server is serving the correct content, a simple`curl`confirms that`index.html`contains`data-bs-theme="light"`and that`build/bake/css/styles.css`weighs exactly 31,402 bytes — identical to the file generated by`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>The local rendering is now<strong>pixel-identical</strong>to the deployed rendering.</p> </div> </div> </div> <div class="sect1"> <h2 id="_why_this_bug_was_vicious">Why this bug was vicious</h2> <div class="sectionbody"> <div class="paragraph"> <p>See why it was hard to catch?</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>No explicit error</strong>: JBake didn’t crash. It "worked", just with the wrong folder.</p> </li> <li> <p><strong>The build worked</strong>:`./gradlew bake`correctly generated files in`build/bake/`.</p> </li> <li> <p><strong>The deployment worked</strong>:`publishSite`pushed the correct content online.</p> </li> <li> <p><strong>Only <code>serve</code> was broken</strong>: the development task, the one used constantly for iterating.</p> </li> <li> <p><strong>The <code>-key value</code> habit</strong>: as a developer, we are conditioned by years of Unix CLI (<code>-o output</code>, <code>-i input</code>). JBake CLI is an exception — source and destination are positional.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>If you maintain a Gradle plugin that wraps JBake (or any CLI tool),<strong>read the argument docs</strong>even if you think you know them. An implicit assumption (<code>-s</code>= "set destination") can cost you hours of visual debugging.</p> </div> <div class="paragraph"> <p>Here, the fix was literally to change:</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>Three tokens moved, and my local site is as beautiful as the production site again.</p> </div> <div class="paragraph"> <p><strong>Lesson</strong>: when the rendering differs between local and prod for no obvious reason, first suspect the <strong>pipeline</strong> — not the CSS, not the browser, and even less the framework. It’s often the step just before rendering that cheats.</p> </div> </div> </div> https://cheroliv.com/en/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="#_the_scene_a_blind_agent_in_a_world_of_tools">The scene: a blind agent in a world of tools</a></li> <li><a href="#_anatomy_of_the_bug_two_shells_two_worlds">Anatomy of the bug: two shells, two worlds</a></li> <li><a href="#_the_culprits_zshrc_vs_zshenv">The culprits: .zshrc vs .zshenv</a></li> <li><a href="#_step_by_step_diagnostic">Step-by-step diagnostic</a> <ul class="sectlevel2"> <li><a href="#_1_verify_the_agents_path">1. Verify the agent’s PATH</a></li> <li><a href="#_2_identify_what_is_in_zshrc_but_not_in_zshenv">2. Identify what is in .zshrc but not in .zshenv</a></li> <li><a href="#_3_check_if_zshenv_exists">3. Check if .zshenv exists</a></li> </ul> </li> <li><a href="#_the_solution_zshenv_the_right_paths">The solution: .zshenv + the right paths</a> <ul class="sectlevel2"> <li><a href="#_create_zshenv_with_all_essential_paths">Create .zshenv with all essential paths</a></li> <li><a href="#_why_not_source_sdkman_init_sh_in_zshenv">Why not <code>source sdkman-init.sh</code> in .zshenv?</a></li> </ul> </li> <li><a href="#_the_nvm_case_when_the_version_manager_forgets_to_leave_a_trace">The NVM case: when the version manager forgets to leave a trace</a> <ul class="sectlevel2"> <li><a href="#_the_nvm_problem">The NVM problem</a></li> <li><a href="#_the_solution_create_the_current_symlink_for_nvm">The solution: create the <code>current</code> symlink for NVM</a></li> <li><a href="#_automating_the_symlink_update">Automating the symlink update</a></li> </ul> </li> <li><a href="#_summary_table_of_paths">Summary table of paths</a></li> <li><a href="#_pitfalls_and_mitigations">Pitfalls and mitigations</a></li> <li><a href="#_lessons_learned">Lessons learned</a></li> <li><a href="#_final_verification">Final verification</a></li> <li><a href="#_links">Links</a> <ul class="sectlevel2"> <li><a href="#_official_documentation">Official Documentation</a></li> <li><a href="#_mentioned_tools">Mentioned Tools</a></li> <li><a href="#_further_reading">Further Reading</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p>reading time: 13 minutes</p> </li> </ol> </div> <div class="paragraph"> <p>You launch OpenCode in your terminal, everything works. The agent tries a`gh`— not found. A`java -version`— absent. A`node`— nowhere. Yet, these tools are right there in <em>your</em> shell. The problem? OpenCode launches shells<strong>non-interactive</strong>that never read your`.zshrc`. Here is how to diagnose and fix this properly.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_scene_a_blind_agent_in_a_world_of_tools">The scene: a blind agent in a world of tools</h2> <div class="sectionbody"> <div class="paragraph"> <p>It was a Tuesday evening. I had just installedhttps://opencode.ai[OpenCode], the AI agent that promised to transform the way I code. First test: asking it to list my GitHub repositories.</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>Strange.`gh`worked perfectly in my terminal. I try something else:</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>Then:</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>— everything was invisible to the agent. My terminal, however, saw everything. As if the agent and I lived in two parallel worlds.</p> </div> <div class="paragraph"> <p>It took me hours to understand. Hours of`echo $PATH`, de <code>which java</code>, of growing frustration. I eventually realized the problem wasn’t the tools — it was the<strong>shell</strong>. OpenCode, like any agent that launches subprocesses, works in<strong>non-interactive</strong>shells. And Zsh, in those shells, simply ignores your`.zshrc`.</p> </div> <div class="paragraph"> <p>What follows is the full account of this diagnostic, the resolution, and the lesson I learned. If you use an AI agent — OpenCode, Aider, Cursor, or even cron scripts — this problem will affect you one day.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomy_of_the_bug_two_shells_two_worlds">Anatomy of the bug: two shells, two worlds</h2> <div class="sectionbody"> <div class="paragraph"> <p>When you open a terminal, Zsh treats it as an<strong>interactive</strong>shell. It loads`.zshrc`, which initializes everything: SDKMAN, NVM, pnpm, aliases, your pretty prompt. Your environment is complete.</p> </div> <div class="paragraph"> <p>But when OpenCode executes a command, it doesn’t launch an interactive terminal. It launches a<strong>non-interactive</strong>shell — a task shell, with no human behind the screen. And Zsh, in this context, skips`.zshrc`. It only reads`.zshenv`.</p> </div> <div class="paragraph"> <p>Why does this distinction exist? Because a non-interactive shell is designed to execute scripts, not to serve a human user. Loading aliases, prompts, and completions in a script running in the background would be a waste. The problem is that your PATH — the most critical information for finding executables — is often initialized in`.zshrc`, not in`.zshenv`.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-path.svg" alt="probleme path" width="558" height="434"> </div> </div> <div class="paragraph"> <p>The root of the problem:<strong>Zsh only sources <code>.zshrc</code> for interactive shells</strong>. OpenCode, like any AI agent that launches subprocesses, uses non-interactive shells. These shells only read`.zshenv`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_culprits_zshrc_vs_zshenv">The culprits: .zshrc vs .zshenv</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh has<strong>four initialization files</strong>, each with a specific role. It’s an elegant design — but it’s also the heart of the problem:</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">File</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sourced when</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Role</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modifies 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>Always</strong>(interactive + non-interactive + login)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Essential environment variables, PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Yes — this is ITS place</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">Login shells only</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slow commands (once per session)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Possible</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>Interactive shells only</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias, prompt, completion, interactive tools</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Not for critical variables</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">Login shells (after .zshrc)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Welcome messages, finalization</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rarely</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The table gives a hint, but it must be understood in depth. Think of it like the rooms of a house:</p> </div> <div class="ulist"> <ul> <li> <p>`.zshenv`is the<strong>entrance hall</strong>— everyone passes through here, visitor or resident. If you put something here, any shell will see it.</p> </li> <li> <p>`.zshrc`is the<strong>living room</strong>— only residents (interactive shells) enter. Visitors (non-interactive shells) stay in the hall.</p> </li> <li> <p><code>.zprofile</code> et `.zlogin`are specialized rooms for login shells (like when you connect via SSH).</p> </li> </ul> </div> <div class="paragraph"> <p>The tragedy is that most of us put the PATH in the living room. And the AI agent is never allowed to enter.</p> </div> <div class="paragraph"> <p>The problem in a diagram:</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>When you open a terminal, Zsh is interactive: it reads`.zshrc`, everything works. When OpenCode launches a shell to execute a command, Zsh is non-interactive: it skips`.zshrc`, reads only`.zshenv`. Et si `.zshenv`doesn’t exist or doesn’t contain the PATH — it’s a desert.</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>Why does Zsh do this?</strong>It’s a design choice inherited from Unix. A non-interactive shell must be<strong>fast</strong> et <strong>reproducible</strong>. Loading aliases, colored prompts, and heavy SDKMAN initializations in a cron script or an AI agent would be slow and fragile. The separation is therefore logical:`.zshenv`for the essentials (variables, PATH),`.zshrc`for convenience (aliases, prompt, completions). The problem arises when we put the essentials in the convenience section.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_step_by_step_diagnostic">Step-by-step diagnostic</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before fixing, you must understand exactly what is missing. Here is a reproducible diagnostic method — keep it bookmarked if you work with AI agents.</p> </div> <div class="sect2"> <h3 id="_1_verify_the_agents_path">1. Verify the agent’s PATH</h3> <div class="paragraph"> <p>We compare what your interactive terminal sees with what a non-interactive shell sees — i.e., what OpenCode sees.</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>Typical result:</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>Now, let’s simulate what the agent sees — a non-interactive shell:</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>Result:</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>Five out of six paths have disappeared.</strong>The agent is amputated from 83% of its environment. It’s like being asked to cook without half of your utensils — you could boil water, but not much else.</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>The command`zsh -c 'echo $PATH'`is your<strong>number 1 diagnostic tool</strong>. If a tool you use daily is missing from the result, your AI agent won’t see it either. Test it before and after every modification of`.zshenv`.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_identify_what_is_in_zshrc_but_not_in_zshenv">2. Identify what is in .zshrc but not in .zshenv</h3> <div class="paragraph"> <p>Now, we look for the culprit in`.zshrc`. We filter the lines that mention our tools:</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>We typically find:</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>All of this is<strong>invisible</strong>to OpenCode. And the`PATH`on line 119 isn’t even`export`exported — it never leaves the current shell. This is a crucial technical detail: a variable without`export`remains local to the shell that defines it. Sub-shells — like those launched by OpenCode — never inherit it.</p> </div> </div> <div class="sect2"> <h3 id="_3_check_if_zshenv_exists">3. Check if .zshenv exists</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>If the answer is "FILE NOT FOUND", that’s where everything happens.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_zshenv_the_right_paths">The solution: .zshenv + the right paths</h2> <div class="sectionbody"> <div class="paragraph"> <p>The strategy is simple, but requires precision: put in`.zshenv` <strong>only</strong>the essential paths, without sourcing heavy initialization scripts. We don’t move`.zshrc`into`.zshenv`— we extract the essentials.</p> </div> <div class="sect2"> <h3 id="_create_zshenv_with_all_essential_paths">Create .zshenv with all essential paths</h3> <div class="paragraph"> <p>`.zshenv`is the<strong>only file</strong>that Zsh guarantees to source in<strong>all</strong>contexts. This is where the PATH should go.</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>We use`$HOME/.nvm/current/bin`and not`$HOME/.nvm/versions/node/v22.19.0/bin`. The reason: Node versions change. A hardcoded path becomes false at the next`nvm install`. More details in the next section.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_why_not_source_sdkman_init_sh_in_zshenv">Why not <code>source sdkman-init.sh</code> in .zshenv?</h3> <div class="paragraph"> <p>The most tempting approach would be to simply reproduce in`.zshenv`what we do in`.zshrc`— source the initialization scripts. One<strong>might</strong>be tempted to do:</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>Problems:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Slow</strong>:`sdkman-init.sh`does network resolutions and checks every shell. In a non-interactive shell, this is an unnecessary cost.</p> </li> <li> <p><strong>Fragile</strong>: SDKMAN expects an interactive context. Its initialization can fail silently in a pipe or a sub-shell.</p> </li> <li> <p><strong>Useless</strong>: SDKMAN places its candidates in`~/.sdkman/candidates/<tool>/current/bin`— stable symlinks pointing to the active version. We can use them<strong>directly</strong>.</p> </li> </ul> </div> <div class="paragraph"> <p>The right approach: bypass SDKMAN initialization and point directly to the`current`symlinks. This is the key to the whole solution:<strong>use the file structure as a contract, rather than the initialization code</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/sdkman-approach.svg" alt="sdkman approach" width="338" height="321"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_nvm_case_when_the_version_manager_forgets_to_leave_a_trace">The NVM case: when the version manager forgets to leave a trace</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_nvm_problem">The NVM problem</h3> <div class="paragraph"> <p>This is where the investigation led me the furthest. SDKMAN has an elegant design: when we do`sdk install java 25.0.2-tem`, it creates a 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>This symlink is<strong>always up to date</strong>. Point to it in`.zshenv`and you are covered, regardless of the shell. Beautiful.</p> </div> <div class="paragraph"> <p>NVM, however, creates<strong>nothing</strong>of the sort. No`current`symlink. No stable anchor point. We have to point to a hardcoded versioned path, which looks like this:</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>At the next`nvm install 24`, this path is dead. Your`.zshenv`will point to a version that is no longer the active version. It’s a time bomb.</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>Why does NVM do this?</strong>NVM works by dynamically modifying the PATH at every`nvm use`. It’s designed for developers who change versions often, in an interactive shell. The`current`symlink was not in the initial specifications — it’s a design oversight that we will correct ourselves.</p> </div> </td> </tr> </table> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-vs-sdkman.svg" alt="nvm vs sdkman" width="1869" height="217"> </div> </div> </div> <div class="sect2"> <h3 id="_the_solution_create_the_current_symlink_for_nvm">The solution: create the <code>current</code> symlink for NVM</h3> <div class="paragraph"> <p>Since NVM doesn’t do it, we do it ourselves. The principle is the same as SDKMAN — a`current`symlink that always points to the active version. We create it once, then automate it so it updates itself.</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>Now, in`.zshenv`, we use:</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>Rather than:</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="_automating_the_symlink_update">Automating the symlink update</h3> <div class="paragraph"> <p>A symlink is worthless if it doesn’t update. The`current`symlink must update when we do`nvm use` ou <code>nvm install</code>. The solution: a<strong>wrapper</strong>— a function that wraps the real`nvm`command and updates the symlink after each call.</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>How it works, in detail:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-wrapper-flow.svg" alt="nvm wrapper flow" width="676" height="393"> </div> </div> <div class="paragraph"> <p>The wrapper`_nvm`calls the real command`nvm`, then updates the symlink. The alias`nvm='_nvm'`ensures that by typing`nvm`, we go through the wrapper. And at shell initialization, we do the same after`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`is an internal NVM function that resolves the full path of a version. This avoids rebuilding the path manually.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_summary_table_of_paths">Summary table of paths</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before moving to the pitfalls, a visual summary of the transformation. On the left, what you had (everything in`.zshrc`, invisible to the agent). On the right, what you have now (essential paths in`.zshenv`, visible everywhere).</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">Tool</th> <th class="tableblock halign-left valign-top">Before (.zshrc only)</th> <th class="tableblock halign-left valign-top">After (.zshenv + symlink)</th> <th class="tableblock halign-left valign-top">Visible to 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 not exported in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/apps`in .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sdkman-init.sh`sourced in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/java/current/bin`in .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sdkman-init.sh`sourced in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.sdkman/candidates/gradle/current/bin`in .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`in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.nvm/current/bin`in .zshenv (symlink)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">pnpm</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$PNPM_HOME`in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$PNPM_HOME`in .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-added by Toolbox in .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`$HOME/.local/share/JetBrains/Toolbox/scripts`in .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`in PATH .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Explicitly in .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="_pitfalls_and_mitigations">Pitfalls and mitigations</h2> <div class="sectionbody"> <div class="paragraph"> <p>Not everything is perfect with this approach. Here are the problems I encountered and how to bypass them.</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">Pitfall</th> <th class="tableblock halign-left valign-top">Description</th> <th class="tableblock halign-left valign-top">Mitigation</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Duplicate PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">If .zshenv and .zshrc add the same path, it appears twice</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`.zshenv`is sourced<strong>before</strong>.zshrc. Both are read in an interactive shell. The PATH can duplicate. It’s cosmetic, not functional. To avoid it: only put paths in .zshenv that are <em>absent</em> from the default PATH.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM: hardcoded version in .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Putting`~/.nvm/versions/node/v22.19.0/bin`hardcoded becomes false at the next`nvm install`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Use the`$HOME/.nvm/current/bin`symlink + the`_nvm`wrapper in .zshrc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN: source sdkman-init.sh in .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slow, fragile, useless in a non-interactive shell</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Use`candidates/<tool>/current/bin`symlinks directly</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Missing alias after modification</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The`nvm='_nvm'`wrapper in .zshrc only takes effect after reloading</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Restart the shell or`source ~/.zshrc`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode doesn’t see changes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The agent has already launched its sub-shells with the old .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Restart OpenCode after modifying .zshenv</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv too bloated</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Putting heavy functions or interactive initializations in .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv = environment variables + PATH only. No`source`, no heavy functions, no prompts.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lessons_learned">Lessons learned</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong><code>.zshrc</code> is interactive, <code>.zshenv</code> is universal</strong>— If a variable must exist in <em>all</em> shells (AI agents, cron, scripts, IDE), it goes in`.zshenv`. The living room is comfortable, but the entrance hall is the only place where everyone passes.</p> </li> <li> <p><strong>Version managers are not created equal</strong>— SDKMAN creates`current`symlinks by design. NVM does not. This gap must be filled manually. This is an important lesson: before configuring your PATH, check if your manager offers a stable anchor point.</p> </li> <li> <p><strong>Do not source init scripts in .zshenv</strong>—<code>sdkman-init.sh</code> et `nvm.sh`are designed for an interactive shell. They are slow and fragile in a non-interactive context.`current`symlinks are sufficient and instantaneous.</p> </li> <li> <p><strong>Always test in a non-interactive shell</strong>—`zsh -c 'echo $PATH'`simulates exactly what an agent sees. This is the validation test. Without this test, you don’t know if your configuration works for agents.</p> </li> <li> <p><strong>The wrapper pattern is reusable</strong>— The same`_nvm`+`alias nvm='_nvm'`pattern applies to any tool that modifies the PATH dynamically without leaving a stable trace. It’s another tool in your idea box.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/avant-apres.svg" alt="avant apres" width="238" height="306"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_final_verification">Final verification</h2> <div class="sectionbody"> <div class="paragraph"> <p>After creating`.zshenv`and the NVM symlink, validate that everything works — in both contexts:</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>Both must succeed. If so, your AI agent will see the same tools as you. If not, go back to the step-by-step diagnostic — you probably forgot a path or the NVM symlink is not up to date.</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>Automate this test.</strong>Add this check to a healthcheck script that you run after every update of your tools. A`zsh -c 'which java && which node && which gh'`in CI is insurance against surprises.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p><em><em>_ A non-interactive shell is like a silent guest: it only reads what is posted on the front door. If the PATH is in the living room, it will never see it. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_links">Links</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_official_documentation">Official Documentation</h3> <div class="ulist"> <ul> <li> <p><a href="https://zsh.sourceforge.io/Doc/Release/Files.html">Zsh documentation: Startup Files</a>— The official reference on Zsh initialization files. This is where everything is explained, even if we often forget.</p> </li> <li> <p><a href="https://opencode.ai/docs/config/">OpenCode: configuration</a>— How to configure OpenCode and its execution environment.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_mentioned_tools">Mentioned Tools</h3> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nvm-sh/nvm">NVM on GitHub</a>— Node Version Manager. Node.js version manager.</p> </li> <li> <p><a href="https://sdkman.io">SDKMAN — official site</a>— SDKMAN! The version manager for the JVM (Java, Kotlin, Gradle…​)</p> </li> <li> <p><a href="https://sdkman.io/install">SDKMAN: installation</a>— SDKMAN installation guide.</p> </li> <li> <p><a href="https://cli.github.com"><code>gh</code> — GitHub CLI</a>— The GitHub command line tool, indispensable for any developer.</p> </li> <li> <p><a href="https://gradle.org">Gradle — official site</a>— The build system we install via SDKMAN.</p> </li> <li> <p><a href="https://pnpm.io">pnpm — official site</a>— The fast and space-efficient Node.js package manager.</p> </li> <li> <p><a href="https://www.jetbrains.com/toolbox-app/">JetBrains Toolbox</a>— The JetBrains IDE manager, which adds its scripts to the PATH.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_further_reading">Further Reading</h3> <div class="ulist"> <ul> <li> <p><a href="https://blog.andy2003.org/posts/2022/zsh-dotfiles/">Zsh dotfiles: a complete guide</a>— An in-depth article on managing Zsh dotfiles.</p> </li> <li> <p><a href="https://wiki.archlinux.org/title/Zsh">Zsh on ArchWiki</a>— One of the best community documentations on Zsh.</p> </li> <li> <p><a href="https://github.com/nvm-sh/nvm/issues">NVM GitHub issues</a>— To see discussions around the`current`symlink and PATH issues.</p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_diagrams_always_lagging_behind_the_code">The problem: diagrams always lagging behind the code</a></li> <li><a href="#_the_solution_a_deterministic_knowledge_graph_plantuml_pipeline">The solution: a deterministic Knowledge Graph → PlantUML pipeline</a></li> <li><a href="#_step_1_install_graphify_and_extract_the_knowledge_graph">Step 1: Install Graphify and extract the Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_installation">Installation</a></li> <li><a href="#_configuring_exclusions">Configuring exclusions</a></li> <li><a href="#_extracting_the_knowledge_graph">Extracting the Knowledge Graph</a></li> </ul> </li> <li><a href="#_step_2_the_gradle_plugin_transforms_the_knowledge_graph_into_plantuml">Step 2: The Gradle plugin transforms the Knowledge Graph into PlantUML</a> <ul class="sectlevel2"> <li><a href="#_pipeline_architecture">Pipeline architecture</a></li> <li><a href="#_internal_components">Internal components</a></li> <li><a href="#_rendering_rules">Rendering rules</a></li> </ul> </li> <li><a href="#_step_3_daily_usage">Step 3: Daily usage</a> <ul class="sectlevel2"> <li><a href="#_full_diagram">Full diagram</a></li> <li><a href="#_filter_by_community">Filter by community</a></li> <li><a href="#_filter_by_edge_type">Filter by edge type</a></li> <li><a href="#_filter_by_node_type_and_confidence">Filter by node type and confidence</a></li> <li><a href="#_custom_output_directory">Custom output directory</a></li> <li><a href="#_complete_properties_reference">Complete properties reference</a></li> </ul> </li> <li><a href="#_files">files</a> <ul class="sectlevel2"> <li><a href="#_the_complete_pipeline_in_a_gradle_workflow">The complete pipeline in a Gradle workflow</a></li> <li><a href="#_typical_workflow">Typical workflow</a></li> <li><a href="#_the_pipeline_integrates_naturally_into_key_development_stages">The pipeline integrates naturally into key development stages:</a></li> </ul> </li> <li><a href="#_on_kotlin_code_this_is_nearly_instantaneous_because_tree_sitter_works_locally_without_llm_calls">). On Kotlin code, this is nearly instantaneous because tree-sitter works locally without LLM calls.</a></li> <li><a href="#_from_the_graph_processes_them_via_llm_dogfooding">from the graph, processes them via LLM (dogfooding)</a></li> <li><a href="#_reviewed_in_pr_versioned_in_git">, reviewed in PR, versioned in Git.</a></li> <li><a href="#_to_close_the_loop_here_is_the_pipeline_diagram_as_it_would_be_generated_by_the_plugin">To close the loop, here is the pipeline diagram as it would be generated by the plugin:</a></li> <li><a href="#"><em>__</em></a></li> <li><a href="#_commit_results">Commit results</a></li> <li><a href="#_consume_llm_tokens">) consume LLM tokens</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 12 minutes</div> <p>Your codebase grows. Module dependencies multiply. Architecture documentation becomes obsolete before it’s even written. What if your Gradle build could <em>automatically</em> generate up-to-date diagrams from the actual code structure? That’s exactly what the Graphify + PlantUML Gradle Plugin pipeline does:`graphify . --no-viz`extracts the Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`transforms it into PlantUML diagrams. Zero LLM, zero manual work, 100% deterministic.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_diagrams_always_lagging_behind_the_code">The problem: diagrams always lagging behind the code</h2> <div class="sectionbody"> <div class="paragraph"> <p>Every project exceeding a few thousand lines experiences this syndrome:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>An architecture diagram is drawn at the start of the project</p> </li> <li> <p>The code evolves, dependencies change</p> </li> <li> <p>The diagram becomes a decorative lie</p> </li> <li> <p>Nobody updates it because it’s tedious</p> </li> <li> <p>Newcomers rely on it and make mistakes</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>The question isn’t <em>do we need diagrams?</em> — everyone knows we do. The question is:<strong>who keeps them up to date?</strong></p> </div> <div class="paragraph"> <p>The answer: nobody. Unless it’s automatic.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_a_deterministic_knowledge_graph_plantuml_pipeline">The solution: a deterministic Knowledge Graph → PlantUML pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>The principle is simple: instead of drawing diagrams by hand, we<strong>generate them from the actual code structure</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-complet.svg" alt="pipeline complet" width="1258" height="434"> </div> </div> <div class="paragraph"> <p>Two commands. That’s it.</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>The result? Files`.puml` et <code>.png`in`diagrams/knowledge-graph/</code>, versioned in Git, always in sync with the code.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_1_install_graphify_and_extract_the_knowledge_graph">Step 1: Install Graphify and extract the Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_installation">Installation</h3> <div class="paragraph"> <p>Graphify is a Python tool that analyzes your codebase and builds a structured knowledge graph:</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="_configuring_exclusions">Configuring exclusions</h3> <div class="paragraph"> <p>Create a`.graphifyignore`file at the project root to exclude files that are not part of the business logic:</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="_extracting_the_knowledge_graph">Extracting the 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>The`--no-viz`flag skips HTML generation (useless in a Gradle pipeline). The result is a`graphify-out/graph.json`file containing:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Nodes</strong>: classes, functions, files — with their type and community</p> </li> <li> <p><strong>Edges</strong>: relations between nodes (EXTRACTED from code, INFERRED by the LLM)</p> </li> <li> <p><strong>Communities</strong>: automatic groupings of linked nodes</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Example structure`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>The source code (<code>.kt</code>, <code>.java</code>) is analyzed locally by tree-sitter,<strong>without LLM calls</strong>. Only documentation files (<code>.adoc</code>, <code>.md</code>) require an LLM call for semantic extraction. Therefore`--update`on Kotlin code is nearly instantaneous.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_2_the_gradle_plugin_transforms_the_knowledge_graph_into_plantuml">Step 2: The Gradle plugin transforms the Knowledge Graph into PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pipeline_architecture">Pipeline architecture</h3> <div class="paragraph"> <p>The`com.cheroliv.plantuml`plugin integrates a`generateKnowledgeGraphDiagram`task that transforms`graph.json`into PlantUML diagrams in a<strong>totally deterministic manner</strong>:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1109" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_internal_components">Internal components</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">Component</th> <th class="tableblock halign-left valign-top">Role</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">Parse`graph.json`— supports 3 formats: native graphify (<code>nodes</code>+<code>links</code>), legacy (<code>communities</code>), flat. Resolves numerical IDs into 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">Deterministically transforms a`KnowledgeGraph`into PlantUML code. Groups by type, communities into packages, automatic legend.</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">Gradle task that orchestrates: parse → render → validate → PNG. Configurable via Gradle properties.</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">Data models:`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">Syntax validation + PNG rendering (reused by all plugin tasks).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_rendering_rules">Rendering rules</h3> <div class="paragraph"> <p>The renderer applies deterministic visual conventions:</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">Edge type</th> <th class="tableblock halign-left valign-top">PlantUML Notation</th> <th class="tableblock halign-left valign-top">Meaning</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">EXTRACTED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(solid line, black)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relation extracted from source code (certainty)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">INFERRED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(dotted line)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relation inferred by the LLM (confidence score)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBIGUOUS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(dotted red line)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ambiguous relation (to be verified)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Communities are rendered as PlantUML packages with an automatic color palette.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_3_daily_usage">Step 3: Daily usage</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_full_diagram">Full diagram</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>Output:`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filter_by_community">Filter by community</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="_filter_by_edge_type">Filter by edge type</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="_filter_by_node_type_and_confidence">Filter by node type and confidence</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="_custom_output_directory">Custom output directory</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="_complete_properties_reference">Complete properties reference</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">Property</th> <th class="tableblock halign-left valign-top">Default</th> <th class="tableblock halign-left valign-top">Description</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>(all)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filter communities by name (substring match)</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>(all)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comma-separated edge types:`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">Minimum confidence threshold for edges</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>(unlimited)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Maximum number of nodes to display</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>(all)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Comma-separated node types (e.g.<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">Output directory for`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_files">files</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_complete_pipeline_in_a_gradle_workflow">The complete pipeline in a Gradle 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="_typical_workflow">Typical workflow</h3> <div class="paragraph"> <p>Integration into the development cycle</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cycle-developpement.svg" alt="cycle developpement" width="733" height="454"> </div> </div> </div> <div class="sect2"> <h3 id="_the_pipeline_integrates_naturally_into_key_development_stages">The pipeline integrates naturally into key development stages:</h3> <div class="paragraph"> <p>Incremental update</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>`--update`When code changes, we don’t rebuild the entire graph from scratch:`graphify-out/cache/`re-extracts only modified files (detected by SHA256 in</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_on_kotlin_code_this_is_nearly_instantaneous_because_tree_sitter_works_locally_without_llm_calls">). On Kotlin code, this is nearly instantaneous because tree-sitter works locally without LLM calls.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dogfooding: the plugin documents itself</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/dogfooding-pipeline.svg" alt="dogfooding pipeline" width="1055" height="533"> </div> </div> <div class="paragraph"> <p>The PlantUML plugin exists to transform prompts into diagrams. It can also transform the Knowledge Graph of its <em>own</em> codebase into documentation diagrams. This is <em>dogfooding</em>: the plugin consumes its own service.</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">Associated Gradle tasks:</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Task</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">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non`graph.json`Transforms</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">into PlantUML (deterministic)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Yes`.prompt`Generates</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="_from_the_graph_processes_them_via_llm_dogfooding">from the graph, processes them via LLM (dogfooding)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Why it’s deterministic (and why it matters)<code>generateKnowledgeGraphDiagram`The key point of the<strong>pipeline:</strong>it makes no LLM calls`graph.json</code>. The</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/determinisme-vs-llm.svg" alt="determinisme vs llm" width="1004" height="405"> </div> </div> <div class="paragraph"> <p>→ PlantUML transformation is a pure function.</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">Concrete advantages:</th> <th class="tableblock halign-left valign-top">Advantage</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Impact</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reproducibility`graph.json`Same</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">→ same diagram. Exactly. Every time.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero cost</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No LLM call = no tokens = no API bill.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero latency</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render takes ~100ms, not 1-5 seconds.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI Compatible</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No API key required. No flaky tests due to variable LLM responses.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le `.puml`Versionable`diff`generated is text. It can be</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_reviewed_in_pr_versioned_in_git">, reviewed in PR, versioned in Git.</h2> <div class="sectionbody"> <div class="paragraph"> <p>Diagrams of the pipeline itself</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1695" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_to_close_the_loop_here_is_the_pipeline_diagram_as_it_would_be_generated_by_the_plugin">To close the loop, here is the pipeline diagram as it would be generated by the plugin:</h2> <div class="sectionbody"> <div class="paragraph"> <p>Integration into project governance</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/strategie-hybride.svg" alt="strategie hybride" width="2019" height="240"> </div> </div> <div class="paragraph"> <p>In our project, this pipeline integrates into an EAGER/LAZY context management strategy for the AI agent. The Knowledge Graph replaces manual architecture documentation with a structured, queryable, and auto-updated graph.</p> </div> <div class="ulist"> <ul> <li> <p><strong>The marriage of the two systems is complementary:</strong>The strategy manages the WHEN and the HOW</p> </li> <li> <p><strong>— governance, workflow, archiving</strong>Graphify manages the WHAT and the WHERE</p> </li> </ul> </div> <div class="paragraph"> <p>— code structure, relations, targeted queries <em>__</em><strong>The session strategy manages the</strong> et le <strong>WHEN</strong>HOW<strong>(governance, workflow, thresholds), Graphify manages the</strong> et le <strong>WHAT</strong>WHERE<strong>(code structure, relations, targeted queries). The PlantUML pipeline manages the</strong>WITH WHAT (deterministic, versioned, always up-to-date diagrams).</p> </div> </div> </div> <div class="sect1"> <h2 id=""><em>__</em></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">Setup: 5-minute checklist</th> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Step</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">Command</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">Install Graphify</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configure exclusions`.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">Create</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">Extract Knowledge Graph</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">Generate diagrams</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="_commit_results">Commit results</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">Pitfalls and mitigations</th> <th class="tableblock halign-left valign-top">Pitfall</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Mitigation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Graph too dense</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A large project generates hundreds of unreadable nodes`-Pplantuml.kg.maxNodes=30`Use</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">and filter by community</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Exclusions too broad`.graphifyignore`Too many files in</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">reduces the graph’s value</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Start by excluding only credentials and build</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Arrow direction</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">INFERRED edges may have an ambiguous direction`-Pplantuml.kg.edgeTypes=EXTRACTED`Filter by</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">for certain relations only</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Obsolete graph</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Code changes but the graph is not rebuilt`graphify . --update`Use`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">regularly or the git hook</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Update cost</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Incremental updates are nearly free (local tree-sitter)`.adoc`Only docs (</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_consume_llm_tokens">) consume LLM tokens</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/recap-visuel.svg" alt="recap visuel" width="372" height="258"> </div> </div> <div class="paragraph"> <p>What we get in the end</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">Concrete benefits:</th> <th class="tableblock halign-left valign-top">Benefit</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Detail</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentation always up to date</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Diagrams reflect current code, not a manual snapshot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero maintenance effort</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Diagrams regenerate on every build</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reduction of technical debt</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No more maintaining diagrams by hand</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Visual context for newcomers</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">A new developer understands the architecture by looking at the diagrams</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Potential fine-tuning</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">(sub-graph → diagram) pairs are AI training examples</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`Automatic validation</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">verifies each generated diagram</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fast onboarding</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>5 diagrams = complete view of the architecture <em>__</em> He who has a <em>why</em> can bear almost any <em>how</em>.</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>== The <em>why</em>: always up-to-date diagrams. The <em>how</em>: two commands in a Gradle pipeline.</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Links</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">Graphify on GitHub</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">PlantUML Gradle Plugin</a>The super tip for the fg command</p> </li> </ul> </div> </blockquote> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_a_busy_terminal">The problem: a busy terminal</a></li> <li><a href="#_the_three_essential_commands">The three essential commands</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_suspend_sigtstp">Ctrl+Z — Suspend (SIGTSTP)</a></li> <li><a href="#_fg_resume_in_foreground">fg — Resume in foreground</a></li> <li><a href="#_bg_resume_in_background">bg — Resume in background</a></li> <li><a href="#_jobs_list_shell_jobs">jobs — List shell jobs</a></li> </ul> </li> <li><a href="#_scenario_1_the_long_build">Scenario 1: The long build</a> <ul class="sectlevel2"> <li><a href="#_step_by_step">Step by step</a></li> </ul> </li> <li><a href="#_scenario_2_the_forgotten_editor">Scenario 2: The forgotten editor</a></li> <li><a href="#_scenario_3_the_suspended_opencode_process">Scenario 3: The suspended opencode process</a></li> <li><a href="#_scenario_4_managing_multiple_jobs_simultaneously">Scenario 4: Managing multiple jobs simultaneously</a> <ul class="sectlevel2"> <li><a href="#_job_commands_summary">Job commands summary</a></li> </ul> </li> <li><a href="#_differences_between_fg_bg_ctrlz_ctrlc_and">Differences between fg, bg, Ctrl+Z, Ctrl+C and &</a></li> <li><a href="#_the_complete_life_cycle_of_a_job">The complete life cycle of a job</a></li> <li><a href="#_advanced_tips">Advanced Tips</a> <ul class="sectlevel2"> <li><a href="#_fg_with_the_most_recent_job_and_alternating">fg with the most recent job and alternating</a></li> <li><a href="#_kill_a_job_cleanly">kill a job cleanly</a></li> <li><a href="#_disown_detach_from_shell">disown: detach from shell</a></li> <li><a href="#_combine_with_nohup_for_long_processes">Combine with nohup for long processes</a></li> </ul> </li> <li><a href="#_pitfalls_and_common_errors">Pitfalls and common errors</a> <ul class="sectlevel2"> <li><a href="#_confusing_ctrlz_and_ctrlc">Confusing Ctrl+Z and Ctrl+C</a></li> <li><a href="#_jobs_are_local_to_the_shell">Jobs are local to the shell</a></li> <li><a href="#_jobs_do_not_survive_shell_closure">Jobs do not survive shell closure</a></li> <li><a href="#_interactive_processes_and_fg">Interactive processes and fg</a></li> </ul> </li> <li><a href="#_summary_diagram">Summary diagram</a></li> <li><a href="#_why_fg_is_underestimated">Why fg is underestimated</a></li> <li><a href="#_technical_memory_signals">Technical memory: signals</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_references">References</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 10 minutes</div> <p>You launch`./gradlew build`, the terminal is blocked for 3 minutes, and you need to do something else <em>meanwhile</em>? No need to open a new tab.`Ctrl+Z`suspends the process,`fg`brings it back exactly where you left it. It’s the most underestimated Unix tip in a developer’s daily life.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_a_busy_terminal">The problem: a busy terminal</h2> <div class="sectionbody"> <div class="paragraph"> <p>Every developer has experienced this situation:</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>The terminal is blocked. You can no longer type any command. And you need to consult a file, launch a`git status`, or check a busy port.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/terminal-bloque.svg" alt="terminal bloque" width="455" height="408"> </div> </div> <div class="paragraph"> <p>Most developers open a new terminal. But there is a more elegant, faster, and native solution: job management.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_three_essential_commands">The three essential commands</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_suspend_sigtstp">Ctrl+Z — Suspend (SIGTSTP)</h3> <div class="paragraph"> <p>`Ctrl+Z`sends the signal`SIGTSTP`to the foreground process. The process is<strong>suspended</strong>— not killed — and the terminal gets its prompt back.</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>The number in brackets`[1]`is the<strong>job number</strong>. Le `+`indicates the default job.</p> </div> </div> <div class="sect2"> <h3 id="_fg_resume_in_foreground">fg — Resume in foreground</h3> <div class="paragraph"> <p>`fg`brings the suspended job back to the foreground. The process resumes exactly where it stopped.</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>With a specific job number:</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_resume_in_background">bg — Resume in background</h3> <div class="paragraph"> <p>`bg`resumes the process <em>without</em> blocking the terminal. Ideal for long builds.</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 `&`at the end means that the process is running in the background.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_list_shell_jobs">jobs — List shell jobs</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="imageblock"> <div class="content"> <img src="./images/jobs-lifecycle.svg" alt="jobs lifecycle" width="606" height="395"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_1_the_long_build">Scenario 1: The long build</h2> <div class="sectionbody"> <div class="paragraph"> <p>This is the most common use case. You launch a Gradle build, the terminal is blocked, and you need to do something else.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/scenario-build.svg" alt="scenario build" width="641" height="599"> </div> </div> <div class="sect2"> <h3 id="_step_by_step">Step by step</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="_scenario_2_the_forgotten_editor">Scenario 2: The forgotten editor</h2> <div class="sectionbody"> <div class="paragraph"> <p>You are in`vim`, you need to consult another file <em>without</em> leaving`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>But that’s tedious. With`Ctrl+Z`, it’s immediate:</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>NOTE:`vim`perfectly restores its state after a`fg`: cursor position, buffer content, undo history — everything is preserved.</p> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_3_the_suspended_opencode_process">Scenario 3: The suspended opencode process</h2> <div class="sectionbody"> <div class="paragraph"> <p>This is the scenario that motivated this article. You are using`opencode`(CLI tool to drive an LLM on your code), and the process is suspended.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/opencode-fg.svg" alt="opencode fg" width="431" height="618"> </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>The advantage is twofold:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>No loss of context</strong>: the LLM session, conversation history, open files — everything is preserved</p> </li> <li> <p><strong>No restarting</strong>: no need to relaunch opencode, reload the context, or re-explain the problem to the LLM</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_4_managing_multiple_jobs_simultaneously">Scenario 4: Managing multiple jobs simultaneously</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et `bg`accept a job number to target a specific process when several are suspended.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim config.yml ^Z [1]+ Stoppé vim config.yml $ ./gradlew test ^Z [2]+ Stoppé ./gradlew test $ htop ^Z [3]+ Stoppé htop $ jobs [1] Stoppé vim config.yml [2]- Stoppé ./gradlew test [3]+ Stoppé htop $ fg %2 ./gradlew test # Le build reprend en avant-plan $ bg %3 [3] htop & # htop reprend en arrière-plan</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/multiple-jobs.svg" alt="multiple jobs" width="778" height="280"> </div> </div> <div class="sect2"> <h3 id="_job_commands_summary">Job commands summary</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">Command</th> <th class="tableblock halign-left valign-top">Effect</th> <th class="tableblock halign-left valign-top">Example</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">Suspends the foreground process</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sending`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">Resumes the default job in foreground</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">Resumes job n in foreground</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">Resumes the default job in background</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">Resumes job n in background</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">Lists the current shell jobs</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code>(with 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">Terminates 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="_differences_between_fg_bg_ctrlz_ctrlc_and">Differences between fg, bg, Ctrl+Z, Ctrl+C and &</h2> <div class="sectionbody"> <div class="paragraph"> <p>Many developers confuse these mechanisms. Here is a decisive clarification.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signals-comparison.svg" alt="signals comparison" width="1476" height="244"> </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">Shortcut/Command</th> <th class="tableblock halign-left valign-top">Signal</th> <th class="tableblock halign-left valign-top">Effect</th> <th class="tableblock halign-left valign-top">Come back?</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">Suspends the process (frozen, in memory)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Yes:`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">Kills the process (terminated)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No: process destroyed</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">Kills the process + core dump</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No: process destroyed</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">Launches in background directly</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`fg`to bring it to foreground</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`is<strong>non-destructive</strong>. The process is frozen as is, in memory. You can resume immediately with`fg</code>. It’s a <em>pause</em>, not a <em>stop</em>. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_the_complete_life_cycle_of_a_job">The complete life cycle of a job</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/job-lifecycle-complete.svg" alt="job lifecycle complete" width="466" height="689"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_advanced_tips">Advanced Tips</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg_with_the_most_recent_job_and_alternating">fg with the most recent job and alternating</h3> <div class="paragraph"> <p><code>fg`without argument brings back the job marked</code>+<code>(the most recent). But you can also use</code>%-`to target the previous job:</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="_kill_a_job_cleanly">kill a job cleanly</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="_disown_detach_from_shell">disown: detach from shell</h3> <div class="paragraph"> <p><code>disown`removes a job from the shell’s job table. The process continues to run but can no longer be brought back with`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="_combine_with_nohup_for_long_processes">Combine with nohup for long processes</h3> <div class="paragraph"> <p>For a process to survive the closing of the 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="imageblock"> <div class="content"> <img src="./images/advanced-tips.svg" alt="advanced tips" width="1371" height="205"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pitfalls_and_common_errors">Pitfalls and common errors</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_confusing_ctrlz_and_ctrlc">Confusing Ctrl+Z and Ctrl+C</h3> <div class="paragraph"> <p>This is the most frequent error.`Ctrl+C`kills the process.`Ctrl+Z`suspends it. If you press`Ctrl+C`by reflex, all state is lost — open files, LLM sessions, builds in progress.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/ctrlz-vs-ctrlc.svg" alt="ctrlz vs ctrlc" width="1142" height="129"> </div> </div> </div> <div class="sect2"> <h3 id="_jobs_are_local_to_the_shell">Jobs are local to the shell</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et `bg`only work in the shell that launched the processes. If you open a new terminal, you will not see the jobs from the other.</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>To see system-wide processes, use`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="_jobs_do_not_survive_shell_closure">Jobs do not survive shell closure</h3> <div class="paragraph"> <p>If you close the terminal, all suspended or background jobs are destroyed. For a process to survive, use`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="_interactive_processes_and_fg">Interactive processes and fg</h3> <div class="paragraph"> <p>Some interactive programs do not behave well after a`Ctrl+Z`+<code>fg</code>. It’s rare but it happens:</p> </div> <div class="ulist"> <ul> <li> <p>Some programs that use signals (vim, htop, less handle`Ctrl+Z`well)</p> </li> <li> <p>Long network programs (ssh, opencode) generally recover correctly</p> </li> <li> <p>Programs that modify the terminal (ncurses) can sometimes leave the terminal in an unexpected state</p> </li> </ul> </div> <div class="paragraph"> <p>In case of a corrupted terminal after a`fg`, type:</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="_summary_diagram">Summary diagram</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/fg-recap.svg" alt="fg recap" width="1271" height="233"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_fg_is_underestimated">Why fg is underestimated</h2> <div class="sectionbody"> <div class="paragraph"> <p>Most modern developers discover`fg`late, if ever. A few reasons:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>IDEs hide the terminal</strong>: VS Code offers an integrated terminal, but multiple tabs make`fg`seem less necessary</p> </li> <li> <p><strong>Graphical tools replace CLIs</strong>: file managers, system monitors, graphical Git clients</p> </li> <li> <p><strong>tmux and screen</strong>: these multiplexers solve the same problem differently, but`fg`is simpler and always available</p> </li> </ol> </div> <div class="paragraph"> <p>Yet,`fg`is:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Universal</strong>: present in all POSIX shells (bash, zsh, fish…​)</p> </li> <li> <p><strong>Dependency-free</strong>: no need to install tmux or screen</p> </li> <li> <p><strong>Instant</strong>: two keystrokes (<code>Ctrl+Z`then`fg</code>) to suspend and resume</p> </li> <li> <p><strong>Context preserving</strong>: the process state remains intact</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/why-fg-underrated.svg" alt="why fg underrated" width="771" height="227"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_technical_memory_signals">Technical memory: signals</h2> <div class="sectionbody"> <div class="paragraph"> <p>For the curious, here are the signals involved:</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">Signal</th> <th class="tableblock halign-left valign-top">Name</th> <th class="tableblock halign-left valign-top">Sent by</th> <th class="tableblock halign-left valign-top">Effect</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">Interruption — terminates the process</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">Quit with 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">Interactive stop — suspends the process</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">Continue — resumes a suspended process</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">Clean termination</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">Forced termination (impossible to intercept)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>The complete flow:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signal-flow.svg" alt="signal flow" width="434" height="525"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>`fg`is not an obscure tip — it’s a fundamental mechanism of the Unix shell, available since the 70s. The fact that most developers ignore it is a symptom of our era: IDEs and multiplexers have distanced us from the basics.</p> </div> <div class="paragraph"> <p>But when you are on an SSH server, in a minimal terminal, or simply using`opencode`and the LLM is in the middle of working —<code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, `jobs`are your best friends.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z suspends, fg resumes. It’s the pause-play of the terminal. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code>— JOB CONTROL section</p> </li> <li> <p><code>man signal</code>— list of POSIX signals</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Bash Reference Manual — Job Control</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 signal — Linux signals</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">Advanced Bash-Scripting Guide — Job Control</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_journey_overview">Journey Overview</a></li> <li><a href="#_the_why_vs_code_in_the_home">The Why: VS Code in the Home</a> <ul class="sectlevel2"> <li><a href="#_the_problem_with_system_installation">The problem with system installation</a></li> <li><a href="#_the_solution_a_local_installation">The solution: a local installation</a></li> <li><a href="#_concrete_advantages">Concrete Advantages</a></li> </ul> </li> <li><a href="#_customizing_the_main_menu_font">Customizing the main menu font</a> <ul class="sectlevel2"> <li><a href="#_the_observation">The observation</a></li> <li><a href="#_the_technique_direct_css_patch">The technique: direct CSS patch</a></li> <li><a href="#_removing_the_integrity_warning">Removing the integrity warning</a></li> </ul> </li> <li><a href="#_customizing_the_explorer_pane_font_the_struggle">Customizing the Explorer pane font — the struggle</a> <ul class="sectlevel2"> <li><a href="#_attempt_1_a_setting_that_doesnt_exist">Attempt 1: a setting that doesn’t exist</a></li> <li><a href="#_attempt_2_the_custom_css_and_js_loader_extension">Attempt 2: the Custom CSS and JS Loader extension</a></li> <li><a href="#_the_trap_the_extension_must_be_activated_every_time">The trap: the extension must be activated every time</a></li> <li><a href="#_attempt_3_lines_overlap">Attempt 3: lines overlap</a></li> <li><a href="#_the_solution_zoom_on_the_parent_container">The solution: <code>zoom</code> on the parent container</a></li> <li><a href="#_summary_of_selectors_and_what_works">Summary of selectors and what works</a></li> </ul> </li> <li><a href="#_the_automatic_update_script">The automatic update script</a> <ul class="sectlevel2"> <li><a href="#_the_problem">The problem</a></li> <li><a href="#_the_vscode_update_sh_script">The <code>vscode-update.sh</code> script</a></li> </ul> </li> <li><a href="#_files_involved_overview">Files involved — overview</a></li> <li><a href="#_lessons_learned">Lessons Learned</a> <ul class="sectlevel2"> <li><a href="#_installing_in_the_home_frees_everything">Installing in the home frees everything</a></li> <li><a href="#_zoom_font_size_for_list_components"><code>zoom</code> > <code>font-size</code> for list components</a></li> <li><a href="#_custom_css_extension_requires_explicit_activation">Custom CSS extension requires explicit activation</a></li> <li><a href="#_an_update_script_is_indispensable">An update script is indispensable</a></li> </ul> </li> <li><a href="#_quick_references">Quick References</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">reading time: 8 minutes</div> <p>Why install VS Code in`/opt`or via`apt`when you can place it in your home and turn your IDE into a playground without ever typing`sudo`? Here is the account of a local installation followed by a fierce battle to enlarge the fonts of the menu and the file explorer.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_journey_overview">Journey Overview</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-overview.svg" alt="vscode local overview" width="1057" height="380"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_why_vs_code_in_the_home">The Why: VS Code in the Home</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_problem_with_system_installation">The problem with system installation</h3> <div class="paragraph"> <p>VS Code installed via`apt`, <code>dnf`or in</code>/opt`locks the application files behind root rights. Any modification of the native CSS,<code>product.json`or the installation folder requires`sudo</code>.</p> </div> <div class="paragraph"> <p>However, when using<strong>opencode</strong>(CLI tool to drive an LLM on one’s code), the agent needs to be able to:</p> </div> <div class="ulist"> <ul> <li> <p>Write to configuration files (<code>~/.config/Code/User/settings.json</code>) — that is already in the home</p> </li> <li> <p>Modify the IDE assets (workbench CSS,<code>product.json</code>) for advanced customizations — that is blocked without sudo</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_the_solution_a_local_installation">The solution: a local installation</h3> <div class="paragraph"> <p>We download the official tarball archive and extract it directly into`~/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>The binary is then located in`~/apps/VSCode-linux-x64/bin/code`. No`sudo`is necessary to read, modify, or replace any file under`~/apps/VSCode-linux-x64/`.</p> </div> </div> <div class="sect2"> <h3 id="_concrete_advantages">Concrete Advantages</h3> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-vs-system.svg" alt="vscode local vs system" width="1320" height="229"> </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">Advantage</th> <th class="tableblock halign-left valign-top">Detail</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">No sudo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">All IDE files belong to the user</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Direct CSS modification</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">We can patch`workbench.desktop.main.css`without elevation of privileges</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Home-made update script</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A simple shell script automatically downloads, replaces, and repatches</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Isolation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The system installation is not polluted; rollback = delete the folder</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_customizing_the_main_menu_font">Customizing the main menu font</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_observation">The observation</h3> <div class="paragraph"> <p>The default font of the main menu (File, Edit, View…​) and the dropdowns is too small. VS Code offers no setting to modify it.</p> </div> </div> <div class="sect2"> <h3 id="_the_technique_direct_css_patch">The technique: direct CSS patch</h3> <div class="paragraph"> <p>We add CSS to the end of the file`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="_removing_the_integrity_warning">Removing the integrity warning</h3> <div class="paragraph"> <p>VS Code detects modifications to its files and displays a "Your installation is corrupt" banner. To avoid this, we remove the checksums from`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>After restarting, no more warnings and the menus are finally readable.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_customizing_the_explorer_pane_font_the_struggle">Customizing the Explorer pane font — the struggle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_attempt_1_a_setting_that_doesnt_exist">Attempt 1: a setting that doesn’t exist</h3> <div class="paragraph"> <p>We first try the native setting`workbench.tree.fontSize`in`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>Result:<strong>no effect</strong>. This setting does not exist in VS Code. Proof that unrecognized settings are silently ignored.</p> </div> </div> <div class="sect2"> <h3 id="_attempt_2_the_custom_css_and_js_loader_extension">Attempt 2: the Custom CSS and JS Loader extension</h3> <div class="paragraph"> <p>We install the extension`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>We create a CSS file in`~/.vscode-custom-css/custom.css`with selectors targeting the explorer elements:</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>And we reference this file in the settings:</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>Result:<strong>the changes are not applied</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_the_trap_the_extension_must_be_activated_every_time">The trap: the extension must be activated every time</h3> <div class="paragraph"> <p>The extension documentation is discreet on this crucial point: after each modification of the custom CSS, you<strong>must</strong>execute the command from the palette:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>Ctrl+Shift+P</code>→ type<strong>"Enable Custom CSS and JS"</strong></p> </li> <li> <p>VS Code asks for a restart → accept</p> </li> </ol> </div> <div class="paragraph"> <p>Without this step, the CSS is never injected into the IDE.</p> </div> </div> <div class="sect2"> <h3 id="_attempt_3_lines_overlap">Attempt 3: lines overlap</h3> <div class="paragraph"> <p>Even with`font-size: 22px` et <code>line-height: 36px</code>, descending letters (g, p, f, b) overflow into neighboring lines. We try adding`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>Result:<strong>no change</strong>. VS Code calculates line heights in JavaScript and overrides CSS values.</p> </div> </div> <div class="sect2"> <h3 id="_the_solution_zoom_on_the_parent_container">The solution: <code>zoom</code> on the parent container</h3> <div class="imageblock"> <div class="content"> <img src="./images/explorer-css-approaches.svg" alt="explorer css approaches" width="465" height="822"> </div> </div> <div class="paragraph"> <p>Rather than fighting the JavaScript layout, we use the`zoom`property on the lines container:</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`uniformly enlarges the rendering of the container — text AND spacing — without breaking the layout calculated by the VS Code JavaScript engine. The 1.25 factor corresponds roughly to moving from 13px to 16px.</p> </div> <div class="paragraph"> <p>Result:<strong>file names are finally readable, lines correctly spaced</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_summary_of_selectors_and_what_works">Summary of selectors and what works</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">Approach</th> <th class="tableblock halign-left valign-top">CSS</th> <th class="tableblock halign-left valign-top">Result</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size`on</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">Larger text but overlapping lines</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height</code>+<code>height`on</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">No effect (JS override)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom`on</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">Success — proportional text + spacing</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_the_automatic_update_script">The automatic update script</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-update-sequence.svg" alt="vscode update sequence" width="1079" height="654"> </div> </div> <div class="sect2"> <h3 id="_the_problem">The problem</h3> <div class="paragraph"> <p>When VS Code updates, it replaces the installation folder and<strong>erases all CSS patches</strong>. Modifications must be re-applied manually each time.</p> </div> </div> <div class="sect2"> <h3 id="_the_vscode_update_sh_script">The <code>vscode-update.sh</code> script</h3> <div class="paragraph"> <p>We create`~/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>The script:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Downloads the latest stable version</p> </li> <li> <p>Checks if the version differs from the current one</p> </li> <li> <p>Backs up the current installation (timestamped) in`~/apps/vscode-backup/`</p> </li> <li> <p>Replaces the installation folder</p> </li> <li> <p><strong>Re-applies</strong>the main menu CSS patch</p> </li> <li> <p><strong>Deletes the checksums</strong> de `product.json`to avoid the integrity warning</p> </li> </ol> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> Explorer pane customizations via the Custom CSS extension and the file`~/.vscode-custom-css/custom.css`survive updates because they live outside the installation folder. </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_files_involved_overview">Files involved — overview</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-files-deployment.svg" alt="vscode files deployment" width="907" height="331"> </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">Path</th> <th class="tableblock halign-left valign-top">Role</th> <th class="tableblock halign-left valign-top">Survives updates?</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">IDE Installation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (replaced)</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">Workbench CSS (menu, dropdowns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (re-patched by the 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">Integrity checksums</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No (re-cleaned by the 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">Automatic update script</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</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">User settings (fontSize, custom CSS)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</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">Custom CSS for the Explorer (zoom)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Yes</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_lessons_learned">Lessons Learned</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-lessons-learned.svg" alt="vscode lessons learned" width="1116" height="532"> </div> </div> <div class="sect2"> <h3 id="_installing_in_the_home_frees_everything">Installing in the home frees everything</h3> <div class="paragraph"> <p>A local installation in`~/apps`gives total control over VS Code:</p> </div> <div class="ulist"> <ul> <li> <p>No`sudo`to modify the CSS or configuration</p> </li> <li> <p>The opencode+LLM agent can write to config files and IDE assets</p> </li> <li> <p>Trivial rollback: restore the timestamped backup</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_zoom_font_size_for_list_components"><code>zoom</code> > <code>font-size</code> for list components</h3> <div class="paragraph"> <p>VS Code controls line height via JavaScript. Modifying`font-size`without being able to touch the height allocated by the layout engine results in overflowing text. The`zoom`property on the parent container enlarges everything proportionally and bypasses this problem.</p> </div> </div> <div class="sect2"> <h3 id="_custom_css_extension_requires_explicit_activation">Custom CSS extension requires explicit activation</h3> <div class="paragraph"> <p>It is not a "set and forget" setting. Every modification to the custom CSS file requires re-executing "Enable Custom CSS and JS" from the command palette (<code>Ctrl+Shift+P</code>).</p> </div> </div> <div class="sect2"> <h3 id="_an_update_script_is_indispensable">An update script is indispensable</h3> <div class="paragraph"> <p>Without a script, every VS Code update erases the workbench CSS patches. The`vscode-update.sh`script automates downloading, replacing, re-patching, and cleaning checksums.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_quick_references">Quick References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>VS Code Download: <a href="https://code.visualstudio.com/Download" class="bare">https://code.visualstudio.com/Download</a></p> </li> <li> <p>Custom CSS and JS Loader Extension:`be5invis.vscode-custom-css`</p> </li> <li> <p>VS Code issue requesting a native setting for the Explorer font:https://github.com/microsoft/vscode/issues/149[github.com/microsoft/vscode#149]</p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_context_and_objective">Context and objective</a> <ul class="sectlevel2"> <li><a href="#_the_starting_point">The starting point</a></li> <li><a href="#_the_objective">The objective</a></li> </ul> </li> <li><a href="#_the_first_obstacle_ruby_gems">The first obstacle: <code>ruby { gems() }</code></a> <ul class="sectlevel2"> <li><a href="#_what_the_groovy_syntactic_sugar_hides">What the Groovy syntactic sugar hides</a></li> <li><a href="#_deconstructing_the_mechanism">Deconstructing the mechanism</a></li> </ul> </li> <li><a href="#_the_three_part_solution">The three-part solution</a> <ul class="sectlevel2"> <li><a href="#_part_1_the_ivy_repo_for_rubygems">Part 1: the Ivy repo for rubygems</a></li> <li><a href="#_part_2_the_asciidoctorgems_dependency">Part 2: the asciidoctorGems dependency</a></li> <li><a href="#_part_3_settings_gradle_kts">Part 3: settings.gradle.kts</a></li> </ul> </li> <li><a href="#_api_introspection_via_bytecodes">API Introspection via bytecodes</a> <ul class="sectlevel2"> <li><a href="#_why_javap">Why <code>javap</code>?</a></li> <li><a href="#_task_hierarchy">Task hierarchy</a></li> <li><a href="#_discovery_of_forkoptions">Discovery of <code>forkOptions</code></a></li> <li><a href="#_the_javaforkoptions_grolifant_api">The <code>JavaForkOptions</code> (grolifant) API</a></li> <li><a href="#_revealjsextension">RevealJSExtension</a></li> </ul> </li> <li><a href="#_java_toolchain_configuration">Java toolchain configuration</a> <ul class="sectlevel2"> <li><a href="#_the_javatoolchainservice_problem">The JavaToolchainService problem</a></li> </ul> </li> <li><a href="#_automatic_docker_detection">Automatic Docker detection</a> <ul class="sectlevel2"> <li><a href="#_context">Context</a></li> <li><a href="#_strategy">Strategy</a></li> </ul> </li> <li><a href="#_final_result">Final result</a> <ul class="sectlevel2"> <li><a href="#_the_consuming_buildscript">The consuming buildscript</a></li> <li><a href="#_settings_gradle_kts">settings.gradle.kts</a></li> </ul> </li> <li><a href="#_summary_of_pitfalls_and_solutions">Summary of pitfalls and solutions</a></li> <li><a href="#_investigation_method_reading_an_unknown_api_with_javap">Investigation method: reading an unknown API with javap</a> <ul class="sectlevel2"> <li><a href="#_principle">Principle</a></li> <li><a href="#_step_1_locate_the_jar_in_the_gradle_cache">Step 1: locate the jar in the Gradle cache</a></li> <li><a href="#_step_2_list_the_classes_of_the_jar">Step 2: list the classes of the jar</a></li> <li><a href="#_step_3_inspect_a_class">Step 3: inspect a class</a></li> <li><a href="#_step_4_climb_the_hierarchy">Step 4: climb the hierarchy</a></li> <li><a href="#_step_5_follow_unknown_types">Step 5: follow unknown types</a></li> <li><a href="#_step_6_verify_project_extensions">Step 6: verify project extensions</a></li> <li><a href="#_method_summary">Method Summary</a></li> </ul> </li> <li><a href="#_next_step">Next step</a></li> </ul> </div> <div class="sect1"> <h2 id="_context_and_objective">Context and objective</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_starting_point">The starting point</h3> <div class="paragraph"> <p>The project`slider-gradle`generates Reveal.js presentations from AsciiDoc files via the Gradle plugin`org.asciidoctor.jvm.revealjs`. The main task configuration`asciidoctorRevealJs`lived directly in the root buildscript`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="_the_objective">The objective</h3> <div class="paragraph"> <p>Move all this configuration into`buildSrc/src/main/kotlin/slides/SlidesPlugin.kt`so that the consuming buildscript is reduced to:</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>The plugin must be totally autonomous: it applies its own plugin dependencies, configures its repos, and manages its Ruby gems.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_first_obstacle_ruby_gems">The first obstacle: <code>ruby { gems() }</code></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_what_the_groovy_syntactic_sugar_hides">What the Groovy syntactic sugar hides</h3> <div class="paragraph"> <p>The line`repositories { ruby { gems() } }`is a Groovy DSL extension available only within the buildscript execution context. It does not exist as a static Kotlin API accessible from buildSrc.</p> </div> <div class="paragraph"> <p>When attempting to call it from`SlidesPlugin.kt`, compilation fails immediately.</p> </div> </div> <div class="sect2"> <h3 id="_deconstructing_the_mechanism">Deconstructing the mechanism</h3> <div class="paragraph"> <p>After analyzing the Gradle cache (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), we discover in the file`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() }`actually performed<strong>three distinct operations</strong>:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Registering an Ivy repo pointing to`https://rubygems.org/gems/`</p> </li> <li> <p>Excluding the group`rubygems`from Maven repos to avoid conflicts</p> </li> <li> <p>Registering the gem in the configuration`asciidoctorGems`so that JRuby loads it at runtime</p> </li> </ol> </div> <div class="paragraph"> <p>These three responsibilities must be reproduced separately in Kotlin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_three_part_solution">The three-part solution</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_part_1_the_ivy_repo_for_rubygems">Part 1: the Ivy repo for 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>The extension`.gem`must be hardcoded.<code>[ext]`resolves by default to</code>.jar`, which causes an error`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"> The Ivy repo is declared directly on`project.repositories`and not in a`repositories { }`block because the receiver of this block is not the`RepositoryHandler`standard Gradle one but a grolifant API incompatible with the`ivy`Kotlin DSL extension. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_part_2_the_asciidoctorgems_dependency">Part 2: the asciidoctorGems dependency</h3> <div class="paragraph"> <p>The plugin`org.asciidoctor.jvm.gems`must be applied first — it creates the configuration`asciidoctorGems`and the task`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>Application order is important:`gems`before`revealjs`. <2> The qualifier`@gem`forces the correct extension on the dependency.</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_part_3_settings_gradle_kts">Part 3: settings.gradle.kts</h3> <div class="paragraph"> <p>`dependencyResolutionManagement`in`settings.gradle.kts`must allow projects to declare their own repos:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) }</code></pre> </div> </div> <div class="paragraph"> <p>Without this line, Gradle ignores the repos declared in the plugin and gem resolution fails.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_api_introspection_via_bytecodes">API Introspection via bytecodes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_why_javap">Why <code>javap</code>?</h3> <div class="paragraph"> <p>The plugin`asciidoctor-gradle-jvm-slides`is version`4.0.0-alpha.1`. Its documentation is non-existent or incomplete. The only reliable source is direct inspection of the compiled classes.</p> </div> </div> <div class="sect2"> <h3 id="_task_hierarchy">Task hierarchy</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>Result:</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="_discovery_of_forkoptions">Discovery of <code>forkOptions</code></h3> <div class="paragraph"> <p>By inspecting`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>We find:</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="_the_javaforkoptions_grolifant_api">The <code>JavaForkOptions</code> (grolifant) API</h3> <div class="paragraph"> <p>`javaLauncher`does not exist on this task. The actual API of`org.ysb33r.grolifant.api.v4.JavaForkOptions`exposes:</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>The method`executable(Object)`replaces the assignment`executable = …​`which does not compile (`val`cannot be reassigned).</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_revealjsextension">RevealJSExtension</h3> <div class="paragraph"> <p>`revealjs { }`is not a task method but a<strong>project extension</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>It is accessed 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="_java_toolchain_configuration">Java toolchain configuration</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_javatoolchainservice_problem">The JavaToolchainService problem</h3> <div class="paragraph"> <p>`JavaToolchainService`is not a project extension. The following call fails:</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>The correct API is`serviceOf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.gradle.kotlin.dsl.support.serviceOf project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_automatic_docker_detection">Automatic Docker detection</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_context">Context</h3> <div class="paragraph"> <p>The Asciidoctor/JRuby plugin requires Java 17. Kotlin 2.0.x in buildSrc does not support Java 25 (the version parser crashes on`"25.0.2"`). Therefore, the Gradle daemon must run on Java 17 or Docker must be used.</p> </div> </div> <div class="sect2"> <h3 id="_strategy">Strategy</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Docker available → execution via container`eclipse-temurin:17`(default behavior)</p> </li> <li> <p>Docker absent + Java 17 → local execution</p> </li> <li> <p>Docker absent + Java > 17 → explicit error</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="_final_result">Final result</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_consuming_buildscript">The consuming buildscript</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>That’s it. The plugin carries the entire responsibility.</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="_summary_of_pitfalls_and_solutions">Summary of pitfalls and solutions</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">Problem</th> <th class="tableblock halign-left valign-top">Cause</th> <th class="tableblock halign-left valign-top">Solution</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`ruby { gems() }`not available in Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Groovy DSL extension only</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Three separate mechanisms: Ivy repo + Maven exclusion +<code>asciidoctorGems</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle looks for a`.jar`instead of a`.gem`</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`[ext]`resolves to`jar`by default</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Hardcode`.gem`in the Ivy pattern + qualifier`@gem`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ivy { }`does not compile in`repositories { }</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Grolifant receiver incompatible with Kotlin DSL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Direct call`project.repositories.ivy { }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">`javaLauncher`unresolved</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non-existent property on`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 = …​`does not compile</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Property`val`in`JavaForkOptions`grolifant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Method`executable(Object)`instead</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>JavaToolchainService`not found via`extensions</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">It is a Gradle service, not an extension</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 { }`unresolved in the task</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Project extension, not task method</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 crashes with Java 25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin 2.0.x does not parse two-digit Java versions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Automatic Docker detection + Java 17 fallback</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_investigation_method_reading_an_unknown_api_with_javap">Investigation method: reading an unknown API with javap</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principle">Principle</h3> <div class="paragraph"> <p>When documentation is absent or incomplete, bytecodes are the source of truth. <code>javap`is the standard JDK tool that decompiles</code>.class`files into readable Java signatures, without requiring source code.</p> </div> </div> <div class="sect2"> <h3 id="_step_1_locate_the_jar_in_the_gradle_cache">Step 1: locate the jar in the Gradle cache</h3> <div class="paragraph"> <p>Gradle downloads all its dependencies into`~/.gradle/caches/modules-2/files-2.1/`. The first step is to find the jar containing the class to inspect:</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">Result:</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="_step_2_list_the_classes_of_the_jar">Step 2: list the classes of the jar</h3> <div class="paragraph"> <p>Before inspecting a class, verify it actually exists in the 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> <div class="sect2"> <h3 id="_step_3_inspect_a_class">Step 3: inspect a class</h3> <div class="listingblock"> <div class="title">This reveals all available classes: <code>AsciidoctorJRevealJSTask</code>, <code>RevealJSExtension</code>, <code>RevealJSOptions</code>, etc.</div> <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>The option`-p`displays all members including private ones. The result immediately shows the key line:</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="_step_4_climb_the_hierarchy">Step 4: climb the hierarchy</h3> <div class="paragraph"> <p>The task extends`AbstractAsciidoctorTask`. We inspect it in turn by first locating its 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>This is where we discover`forkOptions`, <code>JAVA_EXEC</code>, et <code>javaForkOptions</code> of type`org.ysb33r.grolifant.api.v4.JavaForkOptions`.</p> </div> </div> <div class="sect2"> <h3 id="_step_5_follow_unknown_types">Step 5: follow unknown types</h3> <div class="paragraph"> <p>`JavaForkOptions`is an unknown grolifant class. We locate its 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>Then we inspect it:</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>We find`executable(java.lang.Object)`— the correct method to call, as opposed to`executable = …​`which does not compile because it is a`val`property.</p> </div> </div> <div class="sect2"> <h3 id="_step_6_verify_project_extensions">Step 6: verify project extensions</h3> <div class="paragraph"> <p>For`revealjs { }`, the question was: is it a task method or a project extension? Inspection of`AsciidoctorJRevealJSTask` shows no`revealjs`method. We then inspect`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>The presence of`NAME`confirms it is an extension registered on the project, accessible via`project.extensions.getByType<RevealJSExtension>()`.</p> </div> </div> <div class="sect2"> <h3 id="_method_summary">Method Summary</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">Step</th> <th class="tableblock halign-left valign-top">Action</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>— locate the 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>— verify class exists</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>— inspect the class</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">Identify`extends`and climb the hierarchy</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">Follow unknown types in their own 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">Search for`NAME`to identify a project extension</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>This method applies to any Gradle plugin whose API is undocumented or whose alpha version no longer matches the existing documentation.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_next_step">Next step</h2> <div class="sectionbody"> <div class="paragraph"> <p>This buildSrc plugin will be extracted into an independent project published on the Gradle Plugin Portal or Maven Local. The consuming buildscript will then become:</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`will be reduced to its strict minimum without reference to`foojay-resolver-convention</code>, with JDK provisioning handled by the plugin itself or documented as a prerequisite.</p> </div> </div> </div> https://cheroliv.com/en/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="#_architectural_vision">Architectural Vision</a> <ul class="sectlevel2"> <li><a href="#_guiding_principle">Guiding principle</a></li> <li><a href="#_strategic_choice_asciidoc_for_the_portfolio">Strategic choice: AsciiDoc for the portfolio</a></li> <li><a href="#_data_model">Data model</a></li> </ul> </li> <li><a href="#_detailed_use_cases">Detailed Use Cases</a> <ul class="sectlevel2"> <li><a href="#_uc1_adding_an_item_to_the_portfolio">UC1: Adding an item to the portfolio</a> <ul class="sectlevel3"> <li><a href="#_nominal_flow">Nominal flow</a></li> <li><a href="#_template_of_the_file_to_create">Template of the file to create</a></li> <li><a href="#_validation_points">Validation points</a></li> </ul> </li> <li><a href="#_uc2_deleting_an_item_from_the_portfolio">UC2: Deleting an item from the portfolio</a> <ul class="sectlevel3"> <li><a href="#_nominal_flow_2">Nominal flow</a></li> <li><a href="#_alternative_strategy_archiving">Alternative strategy: archiving</a></li> <li><a href="#_resource_cleanup">Resource cleanup</a></li> </ul> </li> <li><a href="#_uc3_setting_to_unpublished_draft">UC3: Setting to unpublished (draft)</a> <ul class="sectlevel3"> <li><a href="#_nominal_flow_3">Nominal flow</a></li> <li><a href="#_possible_states">Possible states</a></li> <li><a href="#_typical_use_cases">Typical use cases</a></li> </ul> </li> </ul> </li> <li><a href="#_templating_architecture">Templating Architecture</a> <ul class="sectlevel2"> <li><a href="#_reusable_template_strategy">Reusable template strategy</a></li> <li><a href="#_data_extraction_pattern">Data extraction pattern</a></li> <li><a href="#_naming_conventions">Naming conventions</a></li> </ul> </li> <li><a href="#_publication_workflow">Publication Workflow</a> <ul class="sectlevel2"> <li><a href="#_development_pipeline">Development pipeline</a></li> <li><a href="#_environments">Environments</a></li> </ul> </li> <li><a href="#_extensibility">Extensibility</a> <ul class="sectlevel2"> <li><a href="#_adding_new_attributes">Adding new attributes</a></li> <li><a href="#_advanced_categorization">Advanced categorization</a></li> </ul> </li> <li><a href="#_best_practices">Best Practices</a> <ul class="sectlevel2"> <li><a href="#_file_organization">File organization</a></li> <li><a href="#_content_management">Content management</a></li> <li><a href="#_performance">Performance</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_architectural_vision">Architectural Vision</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_guiding_principle">Guiding principle</h3> <div class="paragraph"> <p>The architecture is based on the principle of <strong>separation of concerns</strong>:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Content</strong>: structured AsciiDoc files with rich metadata</p> </li> <li> <p><strong>Presentation</strong>: reusable Thymeleaf templates</p> </li> <li> <p><strong>Data</strong>: model automatically extracted by JBake from AsciiDoc attributes</p> </li> <li> <p><strong>Style</strong>: Bootstrap 5 for visual consistency</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_strategic_choice_asciidoc_for_the_portfolio">Strategic choice: AsciiDoc for the portfolio</h3> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Why AsciiDoc?</caption> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Criterion</th> <th class="tableblock halign-left valign-top">Advantage</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Consistency</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Same format as blog posts</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metadata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Structured and extensible attributes (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Maintainability</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Simple text editing, Git versionable</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Flexibility</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Can contain rich content (tables, code, images)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Templating</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake automatically extracts attributes for Thymeleaf</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_data_model">Data model</h3> <div class="paragraph"> <p>Each portfolio project is an AsciiDoc document with:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Header metadata</strong>: structured information (client, duration, technologies, etc.)</p> </li> <li> <p><strong>Document body</strong>: narrative description, challenges, solutions, results</p> </li> <li> <p><strong>Custom attributes</strong>: prefixed`project-*`for automatic extraction</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-39f614a45c003c8e4b1a076206012364.png" alt="Diagram" width="386" height="811"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_detailed_use_cases">Detailed Use Cases</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_adding_an_item_to_the_portfolio">UC1: Adding an item to the portfolio</h3> <div class="sect3"> <h4 id="_nominal_flow">Nominal flow</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-10f84eeb379f90577b624b1ddd2283fd.png" alt="Diagram" width="980" height="715"> </div> </div> </div> <div class="sect3"> <h4 id="_template_of_the_file_to_create">Template of the file to create</h4> <div class="paragraph"> <p>The developer creates`content/portfolio/nom-projet.adoc`with a standardized structure:</p> </div> <div class="ulist"> <ul> <li> <p>Header with all required attributes</p> </li> <li> <p>Standardized sections (Context, Challenges, Solutions, Results)</p> </li> <li> <p>Consistent image naming</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_validation_points">Validation points</h4> <div class="ulist"> <ul> <li> <p>Mandatory attributes are present (<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>Referenced images exist in`assets/img/portfolio/`</p> </li> <li> <p>The JBake build succeeds without error</p> </li> <li> <p>The project appears on the portfolio page</p> </li> <li> <p>The individual project page displays correctly</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_deleting_an_item_from_the_portfolio">UC2: Deleting an item from the portfolio</h3> <div class="sect3"> <h4 id="_nominal_flow_2">Nominal flow</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-d0113242083726276d0bc353b8b5f695.png" alt="Diagram" width="738" height="645"> </div> </div> </div> <div class="sect3"> <h4 id="_alternative_strategy_archiving">Alternative strategy: archiving</h4> <div class="paragraph"> <p>Instead of permanent deletion, possibility to create an`content/portfolio/archive/`folder:</p> </div> <div class="ulist"> <ul> <li> <p>Move the file instead of deleting it</p> </li> <li> <p>Allows for easy restoration</p> </li> <li> <p>Keeps the Git history cleaner</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_resource_cleanup">Resource cleanup</h4> <div class="ulist"> <ul> <li> <p>Check for orphaned images in`assets/img/portfolio/`</p> </li> <li> <p>Delete images not referenced by other projects</p> </li> <li> <p>Clear JBake cache to avoid ghost references</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_setting_to_unpublished_draft">UC3: Setting to unpublished (draft)</h3> <div class="sect3"> <h4 id="_nominal_flow_3">Nominal flow</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-f7dfefdd65ada55b764b6d82def2581d.png" alt="Diagram" width="783" height="594"> </div> </div> </div> <div class="sect3"> <h4 id="_possible_states">Possible states</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="_typical_use_cases">Typical use cases</h4> <div class="ulist"> <ul> <li> <p><strong>Project in drafting</strong> : create as draft, publish when ready</p> </li> <li> <p><strong>Temporarily confidential project</strong> : set to draft until client agreement</p> </li> <li> <p><strong>Major update</strong> : set to draft, modify, republish</p> </li> <li> <p><strong>A/B testing</strong> : duplicate as draft, test, publish the best version</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_templating_architecture">Templating Architecture</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_reusable_template_strategy">Reusable template strategy</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-947a1865680ea1351c022f08cee9d68c.png" alt="Diagram" width="881" height="350"> </div> </div> </div> <div class="sect2"> <h3 id="_data_extraction_pattern">Data extraction pattern</h3> <div class="paragraph"> <p>JBake automatically transforms AsciiDoc attributes into properties accessible in Thymeleaf:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-24dd3ccd504cafd397fe34bb5e84e414.png" alt="Diagram" width="891" height="346"> </div> </div> </div> <div class="sect2"> <h3 id="_naming_conventions">Naming conventions</h3> <div class="ulist"> <ul> <li> <p><strong>Project attributes</strong> : prefix`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>Files</strong> : kebab-case (e.g.,<code>ecommerce-platform.adoc</code>)</p> </li> <li> <p><strong>Images</strong> : project-name prefix (e.g.,<code>ecommerce-platform-thumb.jpg</code>)</p> </li> <li> <p><strong>Templates</strong> : functional name (e.g.,<code>project-card.html</code>, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_publication_workflow">Publication Workflow</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_development_pipeline">Development pipeline</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-2694c3ad773a745365e7ae3fa7dc2d53.png" alt="Diagram" width="386" height="811"> </div> </div> </div> <div class="sect2"> <h3 id="_environments">Environments</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">Environment</th> <th class="tableblock halign-left valign-top">Usage</th> <th class="tableblock halign-left valign-top">Accepted status</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">Development and preview</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">draft, published</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Staging</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pre-production validation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">published only</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Production</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Public site</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">published only</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_extensibility">Extensibility</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adding_new_attributes">Adding new attributes</h3> <div class="paragraph"> <p>To enrich the data model, simply add new attributes prefixed`project-*`:</p> </div> <div class="ulist"> <ul> <li> <p><code>project-awards</code>: Price and awards</p> </li> <li> <p><code>project-testimonial</code>: Client quote</p> </li> <li> <p><code>project-team-size</code>: Team size</p> </li> <li> <p><code>project-budget-range</code>: Budget range</p> </li> </ul> </div> <div class="paragraph"> <p>These attributes automatically become available in the templates without modifying the JBake engine.</p> </div> </div> <div class="sect2"> <h3 id="_advanced_categorization">Advanced categorization</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-5778cdd97fbd507aeb0b4ae9b4bb4724.png" alt="Diagram" width="561" height="259"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_best_practices">Best Practices</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_file_organization">File organization</h3> <div class="ulist"> <ul> <li> <p><strong>One file = one project</strong> : avoid mixing multiple projects</p> </li> <li> <p><strong>Images in dedicated folder</strong> :`assets/img/portfolio/nom-projet/`</p> </li> <li> <p><strong>Consistent nomenclature</strong> : facilitates search and maintenance</p> </li> <li> <p><strong>Git Versioning</strong> : complete tracking of modifications</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_content_management">Content management</h3> <div class="ulist"> <ul> <li> <p><strong>Draft status by default</strong> : publish only when ready</p> </li> <li> <p><strong>Review before publication</strong> : quality and confidentiality validation</p> </li> <li> <p><strong>Complete metadata</strong> : fill in all relevant fields</p> </li> <li> <p><strong>Rich narrative content</strong> : do not limit to metadata</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_performance">Performance</h3> <div class="ulist"> <ul> <li> <p><strong>Optimize images</strong> : compression before commit</p> </li> <li> <p><strong>Pagination if necessary</strong> : if >20 projects</p> </li> <li> <p><strong>Lazy loading</strong> : gallery images loaded on demand</p> </li> <li> <p><strong>Browser cache</strong> : appropriate headers for assets</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>This architecture allows:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Simplicity of use</strong> : adding a project = creating a text file</p> </li> <li> <p><strong>Flexibility</strong> : extensible via new attributes</p> </li> <li> <p><strong>Maintainability</strong> : separation of content/presentation</p> </li> <li> <p><strong>Traceability</strong> : complete Git versioning</p> </li> <li> <p><strong>Automation</strong> : continuous build and deployment possible</p> </li> </ul> </div> <div class="paragraph"> <p>The choice of AsciiDoc ensures consistency with the rest of the site while offering the metadata richness necessary for a professional portfolio.</p> </div> </div> </div> https://cheroliv.com/en/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">reading time: 12 minutes</div> <p>Instead of choosing between the simplicity of Supabase and the power of Spring Boot, why not combine both? Discover a hybrid architecture that leverages the best of each technology.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_the_false_dilemma_of_modern_architecture">The False Dilemma of Modern Architecture</h2> <div class="sectionbody"> <div class="paragraph"> <p>When building a modern application with a static frontend, we often face a binary choice:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Betting everything on a Backend-as-a-Service solution</strong>(Supabase, Firebase) - simple but limited</p> </li> <li> <p><strong>Building a full backend</strong>(Spring Boot, Node.js) - powerful but complex</p> </li> </ul> </div> <div class="paragraph"> <p>This choice is a false dilemma. Hybrid architecture offers a third way: <strong>use each technology where it excels</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_architectural_vision">Architectural Vision</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_traditional_architecture_monolithic">Traditional Architecture: Monolithic</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="807" height="436"> </div> </div> <div class="paragraph"> <p>In this approach, even the simplest operations (reading an article, creating a comment) must pass through your backend. You pay the cost of complexity from day one.</p> </div> </div> <div class="sect2"> <h3 id="_baas_architecture_fully_delegated">BaaS Architecture: Fully Delegated</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>Conversely, delegating everything to a BaaS is appealing at first but quickly shows its limits as business logic becomes more complex.</p> </div> </div> <div class="sect2"> <h3 id="_hybrid_architecture_separation_of_responsibilities">Hybrid Architecture: Separation of Responsibilities</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1529" height="479"> </div> </div> <div class="paragraph"> <p>Hybrid architecture clearly separates responsibilities based on the complexity and nature of the operations.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_design_principles">Design Principles</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principle_1_start_simple_evolve_smartly">Principle 1: Start Simple, Evolve Smartly</h3> <div class="imageblock"> <div class="content"> <img src="evolution-phases.svg" alt="evolution phases" width="465" height="392"> </div> </div> <div class="paragraph"> <p><strong>Don’t build Spring Boot if you don’t need it.</strong>Start with Supabase, add Spring Boot when the complexity justifies it.</p> </div> </div> <div class="sect2"> <h3 id="_principle_2_separation_by_nature_of_operation">Principle 2: Separation by Nature of Operation</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="_principle_3_a_single_source_of_truth">Principle 3: A Single Source of Truth</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1361" height="247"> </div> </div> <div class="paragraph"> <p>By sharing the same PostgreSQL instance, Supabase and Spring Boot work on the same data without complex synchronization.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_flow_orchestration">Flow Orchestration</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flow_1_centralized_authentication">Flow 1: Centralized Authentication</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1101" height="950"> </div> </div> <div class="paragraph"> <p><strong>Key point</strong>: A single authentication process, a single JWT, usable everywhere.</p> </div> </div> <div class="sect2"> <h3 id="_flow_2_orchestration_of_a_complex_business_process">Flow 2: Orchestration of a Complex Business Process</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1093" height="990"> </div> </div> <div class="paragraph"> <p><strong>What Spring Boot brings</strong>: Reliable orchestration of complex processes involving multiple systems with transactional guarantees.</p> </div> </div> <div class="sect2"> <h3 id="_flow_3_scheduled_jobs_and_synchronizations">Flow 3: Scheduled Jobs and Synchronizations</h3> <div class="imageblock"> <div class="content"> <img src="scheduled-jobs.svg" alt="scheduled jobs" width="945" height="912"> </div> </div> <div class="paragraph"> <p><strong>What Spring Boot brings</strong>: Reliable scheduled jobs with state management, automatic retry, and guaranteed execution.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_decision_matrix">Decision Matrix</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_when_to_use_supabase">When to Use Supabase?</h3> <div class="imageblock"> <div class="content"> <img src="supabase-decision.svg" alt="supabase decision" width="1045" height="482"> </div> </div> </div> <div class="sect2"> <h3 id="_when_to_use_spring_boot">When to Use Spring Boot?</h3> <div class="imageblock"> <div class="content"> <img src="springboot-decision.svg" alt="springboot decision" width="1157" height="522"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architecture_examples_by_project_type">Architecture Examples by Project Type</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portfolio">Blog / Portfolio</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>Verdict</strong>: 100% Supabase is more than enough.</p> </div> </div> <div class="sect2"> <h3 id="_saas_application">SaaS Application</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1756" height="341"> </div> </div> <div class="paragraph"> <p><strong>Verdict</strong>: Hybrid architecture necessary. Supabase for the essentials, Spring Boot for the critical part (payments, billing).</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="1937" height="313"> </div> </div> <div class="paragraph"> <p><strong>Verdict</strong>: Spring Boot indispensable. Supabase for auth and catalog only.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_progressive_migration_strategy">Progressive Migration Strategy</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="_costs_and_operational_considerations">Costs and Operational Considerations</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_cost_structure">Cost Structure</h3> <div class="imageblock"> <div class="content"> <img src="cost-structure.svg" alt="cost structure" width="2139" height="225"> </div> </div> </div> <div class="sect2"> <h3 id="_operational_responsibilities">Operational Responsibilities</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1220" height="392"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_the_perfect_balance">Conclusion: The Perfect Balance</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Supabase + Spring Boot hybrid architecture is not a compromise; it’s a<strong>synergy</strong>.</p> </div> <div class="sect2"> <h3 id="_principles_to_remember">Principles to Remember</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="_when_to_choose_this_architecture">When to Choose This Architecture?</h3> <div class="paragraph"> <p><strong>✅ This architecture is ideal if:</strong></p> </div> <div class="ulist"> <ul> <li> <p>You want to start quickly (MVP in days, not months)</p> </li> <li> <p>You anticipate growth in business complexity</p> </li> <li> <p>You want to minimize initial costs</p> </li> <li> <p>You like PostgreSQL and want a single source of truth</p> </li> <li> <p>You appreciate Kotlin and Coroutines for business code</p> </li> <li> <p>You want to avoid total vendor lock-in</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ This architecture is NOT suitable if:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Your project is simple and will stay that way (personal blog → 100% Supabase is enough)</p> </li> <li> <p>You already have an established backend stack that you master</p> </li> <li> <p>You prefer a traditional monolith</p> </li> <li> <p>You need .NET, Python, or another language on the backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_final_overview">Final Overview</h3> <div class="imageblock"> <div class="content"> <img src="final-vision.svg" alt="final vision" width="1524" height="497"> </div> </div> </div> <div class="sect2"> <h3 id="_the_best_of_both_worlds">The Best of Both Worlds</h3> <div class="paragraph"> <p>This architecture gives you:</p> </div> <div class="paragraph"> <p><strong>🚀 The Velocity of Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Get started in hours, not weeks</p> </li> <li> <p>OAuth2 authentication in a few clicks</p> </li> <li> <p>Automatically generated REST APIs</p> </li> <li> <p>Zero server configuration</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💪 The Power of Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin and Coroutines for elegant asynchronous code</p> </li> <li> <p>Orchestration of complex business processes</p> </li> <li> <p>Reliable scheduled jobs</p> </li> <li> <p>Guaranteed ACID transactions</p> </li> <li> <p>Complete Spring ecosystem</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 Progressive Economy</strong></p> </div> <div class="ulist"> <ul> <li> <p>€0 to start and validate</p> </li> <li> <p>Costs that follow growth</p> </li> <li> <p>No premature over-engineering</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 Architectural Flexibility</strong></p> </div> <div class="ulist"> <ul> <li> <p>Progressive migration without a full rewrite</p> </li> <li> <p>Adding Spring Boot only if necessary</p> </li> <li> <p>No total vendor lock-in</p> </li> <li> <p>Evolvable architecture</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_to_go_further">To Go Further</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_technical_resources">Technical Resources</h3> <div class="paragraph"> <p><strong>Supabase Documentation:</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Authentication Guide</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Row Level Security</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">Auto-generated APIs</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot Documentation:</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot with Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">Coroutines and Spring</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">JWT Resource Server</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Complementary Articles:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Securing APIs with JWT</p> </li> <li> <p>Optimizing PostgreSQL performance</p> </li> <li> <p>Progressive migration patterns</p> </li> <li> <p>Error handling in distributed architecture</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_real_use_cases">Real Use Cases</h3> <div class="paragraph"> <p>This hybrid architecture is successfully used in:</p> </div> <div class="ulist"> <ul> <li> <p><strong>B2B SaaS</strong>: Supabase authentication, Spring Boot billing</p> </li> <li> <p><strong>Marketplaces</strong>: Supabase catalog, Spring Boot transactions</p> </li> <li> <p><strong>Content Platforms</strong>: Supabase articles, Spring Boot analytics</p> </li> <li> <p><strong>Internal Tools</strong>: Supabase CRUD, Spring Boot workflows</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_getting_started_checklist">Getting Started Checklist</h3> <div class="paragraph"> <p><strong>Phase 1 - Foundations (Week 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Create Supabase account - [ ] Configure PostgreSQL project - [ ] Enable Auth (Google, GitHub) - [ ] Define initial schema - [ ] Configure Row Level Security - [ ] Test APIs from JBake</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 2 - MVP (Week 2-3)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Implement main pages - [ ] Integrate OAuth2 authentication - [ ] Create CRUD forms - [ ] Configure Storage for files - [ ] Deploy to GitHub Pages - [ ] Test in real conditions</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - Evolution (As needed)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identify complex logic needs - [ ] Create Spring Boot project if necessary - [ ] Configure Supabase JWT validation - [ ] Connect to Supabase PostgreSQL - [ ] Migrate complex features - [ ] Implement scheduled jobs - [ ] Deploy Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_anti_patterns_to_avoid">Anti-Patterns to Avoid</h3> <div class="paragraph"> <p><strong>❌ Do not do:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Duplicate data between Supabase and Spring Boot</p> </li> <li> <p>Create two separate PostgreSQL databases</p> </li> <li> <p>Code authentication yourself</p> </li> <li> <p>Use Spring Boot for simple CRUD</p> </li> <li> <p>Over-engineer from the start</p> </li> <li> <p>Ignore Supabase Row Level Security</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ Do this instead:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Share a single PostgreSQL database</p> </li> <li> <p>Let Supabase handle authentication</p> </li> <li> <p>Use Spring Boot only for complexity</p> </li> <li> <p>Start simple, evolve progressively</p> </li> <li> <p>Leverage the strengths of each technology</p> </li> <li> <p>Secure with RLS at the database level</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_evolution_perspectives">Evolution Perspectives</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_adding_new_capabilities">Adding New Capabilities</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1998" height="331"> </div> </div> </div> <div class="sect2"> <h3 id="_horizontal_scaling">Horizontal Scaling</h3> <div class="paragraph"> <p>As your application grows, the hybrid architecture scales naturally:</p> </div> <div class="paragraph"> <p><strong>Supabase:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Scales automatically up to millions of operations</p> </li> <li> <p>Read replicas for read performance</p> </li> <li> <p>Point-in-time recovery for security</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Multiple instances behind load balancer</p> </li> <li> <p>Stateless design facilitates horizontal scaling</p> </li> <li> <p>Kubernetes for orchestration if necessary</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Partitioning for large tables</p> </li> <li> <p>Connection pooling (PgBouncer)</p> </li> <li> <p>Sharding if truly necessary (rare)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architectural_testimonials">Architectural Testimonials</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_saas_startup_50k_users">SaaS Startup (50k users)</h3> <div class="paragraph"> <p><em><em>_ We started with 100% Supabase. At 5k users, we added Spring Boot only for Stripe billing and monthly reports. A year later, 80% of our operations still go through Supabase. Spring Boot only handles the critical part. This separation allowed us to scale without a rewrite. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_e_learning_platform_10k_users">E-learning Platform (10k users)</h3> <div class="paragraph"> <p><em><em>_ Supabase’s OAuth2 authentication saved us 3 weeks of development. Auto-generated APIs handle our entire course catalog. Spring Boot is only used for PDF certificates and progress emails. Simple, maintainable, scalable architecture. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_b2b_marketplace_3k_users">B2B Marketplace (3k users)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot handles transactions between buyers and sellers (critical). Supabase handles everything else: profiles, real-time messaging, documents. The fact that they share the same PostgreSQL database saves us from any complex synchronization. Best architectural choice we’ve made. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_synthesis_a_modern_architectural_paradigm">Synthesis: A Modern Architectural Paradigm</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Supabase + Spring Boot hybrid architecture represents a new paradigm:<strong>architectural specialization</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="paradigm-shift.svg" alt="paradigm shift" width="1058" height="260"> </div> </div> <div class="paragraph"> <p><strong>The fundamental principle:</strong>Don’t build what already exists as a service. Focus on what differentiates your application.</p> </div> <div class="sect2"> <h3 id="_the_8020_rule">The 80/20 Rule</h3> <div class="paragraph"> <p>In most applications:</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% of operations</strong>are standard CRUD → Supabase</p> </li> <li> <p><strong>20% of operations</strong>require business logic → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>This natural rule justifies the hybrid architecture.</p> </div> <div class="imageblock"> <div class="content"> <img src="8020-rule.svg" alt="8020 rule" width="1605" height="221"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_final_conclusion">Final Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Hybrid architecture is not a technical compromise; it’s a<strong>strategic decision</strong>.</p> </div> <div class="paragraph"> <p><strong>It allows you to:</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Start quickly with a functional MVP</p> </li> <li> <p>✅ Validate your market without heavy investment</p> </li> <li> <p>✅ Evolve progressively when complexity requires it</p> </li> <li> <p>✅ Control your costs at every stage</p> </li> <li> <p>✅ Leverage the best of each technology</p> </li> <li> <p>✅ Avoid premature over-engineering</p> </li> <li> <p>✅ Maintain flexibility for the future</p> </li> </ul> </div> <div class="paragraph"> <p><strong>It represents:</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯<strong>Pragmatism</strong>: Each technology where it excels</p> </li> <li> <p>🚀<strong>Velocity</strong>: Minimal time-to-market</p> </li> <li> <p>💰<strong>Economy</strong>: Costs aligned with value</p> </li> <li> <p>🔮<strong>Scalability</strong>: Architecture that grows with you</p> </li> <li> <p>🛡️<strong>Robustness</strong>: Proven and reliable services</p> </li> </ul> </div> <div class="sect2"> <h3 id="_your_next_step">Your Next Step</h3> <div class="paragraph"> <p>If this architecture speaks to you, here is where to start:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Create a Supabase account</strong>(free)</p> </li> <li> <p><strong>Define your minimal data schema</strong></p> </li> <li> <p><strong>Configure OAuth2 authentication</strong></p> </li> <li> <p><strong>Create your first JBake page that consumes the API</strong></p> </li> <li> <p><strong>Deploy to GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>You will have a functional MVP in<strong>a few days</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot will come naturally when you need it. Not before.</p> </div> <hr> <div class="paragraph"> <p><strong>Hybrid architecture is the art of building exactly what is needed, when it is needed.</strong></p> </div> <div class="paragraph"> <p><em>Happy developing! 🚀</em></p> </div> <hr> <div class="paragraph"> <p><em>Share this article if you think it can help other developers make the right architectural choices.</em></p> </div> </div> </div> </div> https://cheroliv.com/en/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="#_summary">Summary</a></li> <li><a href="#_the_problem_that_cursed_theme_flicker">The Problem: That Cursed Theme Flicker</a> <ul class="sectlevel2"> <li><a href="#_a_user_experience_nightmare">A User Experience Nightmare</a></li> <li><a href="#_fouc_an_old_web_problem">FOUC: An Old Web Problem</a></li> <li><a href="#_impact_on_quality_perception">Impact on Quality Perception</a></li> <li><a href="#_technical_analysis_of_the_problem">Technical Analysis of the Problem</a></li> </ul> </li> <li><a href="#_why_a_standard_script_isnt_enough">Why a Standard Script Isn’t Enough?</a> <ul class="sectlevel2"> <li><a href="#_the_intuitive_but_ineffective_approach">The Intuitive but Ineffective Approach</a></li> <li><a href="#_understanding_the_domcontentloaded_event">Understanding the DOMContentLoaded Event</a></li> <li><a href="#_the_render_blocking_problem">The Render Blocking Problem</a></li> <li><a href="#_visualizing_the_problem">Visualizing the Problem</a></li> <li><a href="#_ineffective_solution_attempts">Ineffective Solution Attempts</a></li> <li><a href="#_the_real_solution_acting_earlier">The Real Solution: Acting Earlier</a></li> </ul> </li> <li><a href="#_the_solution_early_loading">The Solution: Early Loading</a> <ul class="sectlevel2"> <li><a href="#_the_fundamental_principle">The Fundamental Principle</a></li> <li><a href="#_why_the_head_is_the_ideal_place">Why the <code><head></code> is the Ideal Place</a></li> <li><a href="#_three_layer_solution_architecture">Three-Layer Solution Architecture</a></li> </ul> </li> <li><a href="#_step_1_saving_the_users_choice">Step 1: Saving the User’s Choice</a> <ul class="sectlevel2"> <li><a href="#_localstorage_your_persistent_memory">localStorage: Your Persistent Memory</a></li> <li><a href="#_implementing_theme_saving">Implementing Theme Saving</a></li> <li><a href="#_error_case_management">Error Case Management</a></li> <li><a href="#_advanced_persistence_strategies">Advanced Persistence Strategies</a></li> </ul> </li> <li><a href="#_step_2_the_preloading_script_in_the_head">Step 2: The Preloading Script in the <code><head></code></a> <ul class="sectlevel2"> <li><a href="#_the_heart_of_the_solution">The Heart of the Solution</a></li> <li><a href="#_script_anatomy_every_line_counts">Script Anatomy: Every Line Counts</a></li> <li><a href="#_system_preference_detection_bonus">System Preference Detection (Bonus)</a></li> <li><a href="#_performance_why_this_script_is_fast">Performance: Why this Script is Fast</a></li> <li><a href="#_optimal_placement_in_the_head">Optimal Placement in the <code><head></code></a></li> </ul> </li> <li><a href="#_step_3_the_power_of_css_attribute_selectors">Step 3: The Power of CSS Attribute Selectors</a> <ul class="sectlevel2"> <li><a href="#_the_bootstrap_5_theme_system">The Bootstrap 5 Theme System</a></li> <li><a href="#_css_structure_for_a_theme_system">CSS Structure for a Theme System</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_summary">Summary</h2> <div class="sectionbody"> <div class="paragraph"> <p>In this in-depth technical article, we explore how to implement a theme selector (light/dark) without the unpleasant flickering effect that occurs during page load. We analyze in detail the browser rendering cycle, the root causes of FOUC (Flash of Unstyled Content), and propose a robust solution based on synchronous preloading in the`<head>`. This technique ensures a smooth and professional user experience.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_that_cursed_theme_flicker">The Problem: That Cursed Theme Flicker</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_a_user_experience_nightmare">A User Experience Nightmare</h3> <div class="paragraph"> <p>Imagine the scene: you have spent hours designing a beautiful dark theme for your web application. The colors are perfectly balanced, the contrast is optimal, and your users love this option. But there is an embarrassing problem: with every page reload, for a fraction of a second, the default light theme is displayed before the dark theme takes over.</p> </div> <div class="paragraph"> <p>This visual "flash," although brief (sometimes less than 100ms), is immediately perceptible to the human eye and creates an unpleasant experience. For users who have chosen the dark theme for visual comfort or accessibility reasons, this flicker can even be painful, particularly in a low-light environment.</p> </div> </div> <div class="sect2"> <h3 id="_fouc_an_old_web_problem">FOUC: An Old Web Problem</h3> <div class="paragraph"> <p>This phenomenon is a variant of what is called "Flash of Unstyled Content" (FOUC), a classic web development problem dating back to the early days of CSS. FOUC occurs when the browser temporarily displays HTML content without its CSS styles applied, creating a flash of unstyled content.</p> </div> <div class="paragraph"> <p>In our specific case, we are not talking about completely unstyled content, but rather a<strong>Flash of Wrong Theme</strong>(FOWT) - the content is styled, but with the wrong theme. This is particularly frustrating because it shows that our application "forgets" the user’s preference on every page load.</p> </div> </div> <div class="sect2"> <h3 id="_impact_on_quality_perception">Impact on Quality Perception</h3> <div class="paragraph"> <p>This problem, although technical, has significant repercussions on the perception of your application’s quality:</p> </div> <div class="paragraph"> <p><strong>Lack of polish</strong>: The flicker gives the impression of an unfinished or poorly optimized application. Users often associate these small visual flaws with a general lack of professionalism.</p> </div> <div class="paragraph"> <p><strong>Break in consistency</strong>: The application seems to "forget" user preferences, creating a feeling of desynchronization between the interface and expectations.</p> </div> <div class="paragraph"> <p><strong>Visual fatigue</strong>: For users sensitive to light or suffering from migraines, this bright flash can be more than just an aesthetic nuisance.</p> </div> <div class="paragraph"> <p><strong>Perceived performance</strong>: Ironically, even if your site loads quickly, this flicker can give the impression of a slow or unresponsive application.</p> </div> </div> <div class="sect2"> <h3 id="_technical_analysis_of_the_problem">Technical Analysis of the Problem</h3> <div class="paragraph"> <p>To understand how to solve this problem, one must first understand why it occurs. The flicker happens because of a time lag between three critical events in a web page’s lifecycle:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Initial HTML parsing</strong>: The browser reads and analyzes your page structure</p> </li> <li> <p><strong>Application of CSS styles</strong>: The browser applies CSS rules and calculates the visual rendering</p> </li> <li> <p><strong>JavaScript execution</strong>: Your code that changes the theme executes</p> </li> </ol> </div> <div class="paragraph"> <p>The problem occurs when event #3 (JavaScript execution) arrives after the browser has already started or finished event #2 (application of styles). At that point, the browser has already made a decision on which theme to display, and your code arrives too late to influence it before the first render.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_a_standard_script_isnt_enough">Why a Standard Script Isn’t Enough?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_intuitive_but_ineffective_approach">The Intuitive but Ineffective Approach</h3> <div class="paragraph"> <p>The most natural approach for a developer would be to place a script at the end of our`<body>`that checks the user’s preferred theme and applies it. This approach follows traditional web best practices which recommend loading scripts at the end of the page so as not to block rendering.</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>This approach seems logical at first glance. We wait for the DOM to be ready, then we apply the theme. Simple, right? Unfortunately, this simplicity hides a fundamental flaw related to the timing of the browser’s rendering cycle.</p> </div> </div> <div class="sect2"> <h3 id="_understanding_the_domcontentloaded_event">Understanding the DOMContentLoaded Event</h3> <div class="paragraph"> <p>The`DOMContentLoaded`event triggers when the initial HTML document has been completely loaded and parsed by the browser,<strong>without waiting</strong>for the completion of the loading of stylesheets, images, and sub-frames. This is an important point to understand.</p> </div> <div class="paragraph"> <p>Here is the typical sequence of events:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The browser starts downloading the HTML</p> </li> <li> <p>It parses the HTML as it is received</p> </li> <li> <p>It discovers the`<link>`tags for CSS and starts downloading them</p> </li> <li> <p>It discovers the`<script>`tags and executes them (depending on their type and attributes)</p> </li> <li> <p>It builds the DOM (Document Object Model)</p> </li> <li> <p><strong>The <code>DOMContentLoaded</code> event triggers</strong></p> </li> <li> <p>It continues to apply styles and perform the layout</p> </li> <li> <p>The first paint (display) occurs</p> </li> <li> <p>The`load`event triggers when all resources are loaded</p> </li> </ol> </div> <div class="paragraph"> <p>The problem? Between step 6 (DOMContentLoaded) and step 8 (first paint), the browser has already made decisions on how to display the page. If your theme-change script executes at step 6, it is already too late to avoid a first display with the default styles.</p> </div> </div> <div class="sect2"> <h3 id="_the_render_blocking_problem">The Render Blocking Problem</h3> <div class="paragraph"> <p>In reality, the timing is even more complex. Modern browsers use sophisticated optimization techniques to improve perceived performance. They try to perform the first paint (First Contentful Paint) as quickly as possible so that the user sees something on the screen.</p> </div> <div class="paragraph"> <p>CSS is "render-blocking" by default, which means the browser waits until it has downloaded and parsed the stylesheets before performing the first paint. This makes sense: we don’t want to display unstyled content.</p> </div> <div class="paragraph"> <p>But here is the trap: when the browser applies these CSS styles for the first time, it does so based on the current state of the DOM. If the`data-bs-theme`attribute is not yet defined on the`<html>`tag, the browser will apply the default styles (usually the light theme).</p> </div> <div class="paragraph"> <p>Then, when your script executes and changes this attribute, the browser must:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Recalculate all styles affected by this change</p> </li> <li> <p>Redo the layout if necessary</p> </li> <li> <p>Repaint the affected elements</p> </li> </ol> </div> <div class="paragraph"> <p>This process of recalculation and repainting is what causes the visible flicker.</p> </div> </div> <div class="sect2"> <h3 id="_visualizing_the_problem">Visualizing the Problem</h3> <div class="paragraph"> <p>To better understand this problematic sequence, let’s examine a detailed sequence diagram:</p> </div> <div id="diag-flux-incorrect" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-57b60980e84e348efaebec98f8f82fce.svg" alt="Diagramme de séquence du chargement incorrect" width="1488" height="666"> </div> </div> <div class="paragraph"> <p>This diagram clearly illustrates the problem: the first paint occurs before our script has had the chance to define the correct theme. The subsequent repaint creates the visible flicker.</p> </div> </div> <div class="sect2"> <h3 id="_ineffective_solution_attempts">Ineffective Solution Attempts</h3> <div class="paragraph"> <p>Several approaches have been attempted to solve this problem, but most have their own drawbacks:</p> </div> <div class="paragraph"> <p><strong>Approach 1: Hiding content until loading</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>This approach hides all content until the JavaScript has defined the correct theme. The problem? This artificially delays the display of content, giving the impression of a slower site. Furthermore, if JavaScript is disabled, the user sees nothing at all!</p> </div> <div class="paragraph"> <p><strong>Approach 2: Using a loader/spinner</strong></p> </div> <div class="paragraph"> <p>Similar to approach 1, but with a loading spinner. This masks the problem but does not improve actual performance and adds an unnecessary perceived delay.</p> </div> <div class="paragraph"> <p><strong>Approach 3: Defaulting to dark theme</strong></p> </div> <div class="paragraph"> <p>Some developers define the dark theme as the default in CSS. This avoids the flicker for dark theme users, but creates the reverse problem for light theme users!</p> </div> <div class="paragraph"> <p>None of these approaches are satisfactory because they treat the symptom rather than the root cause of the problem.</p> </div> </div> <div class="sect2"> <h3 id="_the_real_solution_acting_earlier">The Real Solution: Acting Earlier</h3> <div class="paragraph"> <p>The key to solving this problem is realizing that we must define the`data-bs-theme` <strong>before</strong>the browser begins applying the CSS styles. This means our script must execute earlier in the page’s lifecycle, and that is exactly what we will explore in the next section.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_early_loading">The Solution: Early Loading</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_fundamental_principle">The Fundamental Principle</h3> <div class="paragraph"> <p>The elegant solution to our flickering problem rests on a simple but powerful principle:<strong>synchronize the application state with the browser’s rendering process</strong>. Instead of waiting for the page to be loaded to define the theme, we must define it<strong>during</strong>loading, even before the CSS styles are applied.</p> </div> <div class="paragraph"> <p>This approach is called "Early Loading" or "Synchronous Preloading" in web development jargon. The idea is to execute our theme detection logic as early as possible in the page lifecycle, ideally in the`<head>`tag, even before the browser starts downloading CSS files.</p> </div> </div> <div class="sect2"> <h3 id="_why_the_head_is_the_ideal_place">Why the <code><head></code> is the Ideal Place</h3> <div class="paragraph"> <p>Le `<head>`of an HTML document is processed sequentially by the browser, from top to bottom. Each element is processed in the order it appears. This characteristic is crucial for our solution.</p> </div> <div class="paragraph"> <p>When the browser encounters a`<script>`tag in the`<head>`without the`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Interrupts the HTML parsing</strong></p> </li> <li> <p><strong>Downloads the script</strong>(if external) or reads it (if inline)</p> </li> <li> <p><strong>Executes the script immediately</strong></p> </li> <li> <p><strong>Resumes HTML parsing</strong></p> </li> </ol> </div> <div class="paragraph"> <p>This behavior, often considered a performance problem (hence the usual recommendation to place scripts at the end of the page), becomes our ally in this specific case. By placing our theme detection script at the beginning of the`<head>`, we guarantee that it executes before the browser encounters the`<link>`tags of our stylesheets.</p> </div> </div> <div class="sect2"> <h3 id="_three_layer_solution_architecture">Three-Layer Solution Architecture</h3> <div class="paragraph"> <p>Our complete solution consists of three interdependent layers, each playing a specific role:</p> </div> <div class="paragraph"> <p><strong>Layer 1: Persistence (localStorage)</strong> This layer is responsible for saving and retrieving the user’s choice between sessions.</p> </div> <div class="paragraph"> <p><strong>Layer 2: Early Synchronization (Inline script in <code><head></code>)</strong> This layer synchronizes the application state with the DOM before the initial render.</p> </div> <div class="paragraph"> <p><strong>Layer 3: Reactive Styles (CSS with attribute selectors)</strong> This layer defines the visual styles based on the state defined by layer 2.</p> </div> <div class="paragraph"> <p>Let’s now explore each layer in detail.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_1_saving_the_users_choice">Step 1: Saving the User’s Choice</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_localstorage_your_persistent_memory">localStorage: Your Persistent Memory</h3> <div class="paragraph"> <p>Le `localStorage`is a Web Storage API that allows storing key-value pairs in the browser persistently. Unlike cookies,`localStorage`data:</p> </div> <div class="ulist"> <ul> <li> <p>Is never sent to the server automatically</p> </li> <li> <p>Has a larger storage capacity (generally 5-10MB)</p> </li> <li> <p>Has no expiration date (persistent until explicit deletion)</p> </li> <li> <p>Is limited to the protocol and domain (Same-Origin Policy)</p> </li> </ul> </div> <div class="paragraph"> <p>For our use case,`localStorage`is perfect because:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>We don’t need to share this information with the server</p> </li> <li> <p>We want the preference to persist indefinitely</p> </li> <li> <p>The required storage size is minimal (a few bytes)</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_implementing_theme_saving">Implementing Theme Saving</h3> <div class="paragraph"> <p>Here is how we save the user’s choice when they change the theme:</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="_error_case_management">Error Case Management</h3> <div class="paragraph"> <p>It is crucial to handle cases where`localStorage`is unavailable or inaccessible. Several scenarios can prevent access to`localStorage`:</p> </div> <div class="paragraph"> <p><strong>Strict private browsing</strong>: Safari in private browsing mode throws a`QuotaExceededError`exception when attempting to write to`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Privacy settings</strong>: Some browsers or privacy extensions may block access to`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Domain limitations</strong> : Le `localStorage`is not accessible on the`file://`protocol in some browsers.</p> </div> <div class="paragraph"> <p><strong>Saturated storage space</strong>: Although rare, storage space can be completely full.</p> </div> <div class="paragraph"> <p>That is why our code uses a`try…​catch`block to handle these cases gracefully, continuing to offer the theme-change functionality even if persistence is unavailable.</p> </div> </div> <div class="sect2"> <h3 id="_advanced_persistence_strategies">Advanced Persistence Strategies</h3> <div class="paragraph"> <p>For more sophisticated applications, you may consider additional strategies:</p> </div> <div class="paragraph"> <p><strong>Server synchronization (optional)</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>This approach allows synchronizing preferences across devices for logged-in users, while maintaining immediate local responsiveness.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_2_the_preloading_script_in_the_head">Step 2: The Preloading Script in the <code><head></code></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_heart_of_the_solution">The Heart of the Solution</h3> <div class="paragraph"> <p>This is where the magic truly happens. We will place a small<strong>inline</strong>script directly in our`<head>`, before all our stylesheet`<link>`tags. This script is intentionally minimalist, self-contained, and designed to execute as quickly as possible.</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="_script_anatomy_every_line_counts">Script Anatomy: Every Line Counts</h3> <div class="paragraph"> <p>Let’s break down this script line by line to understand every design decision:</p> </div> <div class="paragraph"> <p><strong>The IIFE (Immediately Invoked Function Expression)</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>This structure creates a function that executes immediately. Why? To isolate our variables in a local scope and avoid polluting the global scope. Even if we only use`const`(which has block scope), the IIFE is a good practice that makes our intentions clear and protects against potential naming conflicts.</p> </div> <div class="paragraph"> <p><strong>Strict Mode</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>This directive activates JavaScript’s strict mode, which: - Prohibits the use of undeclared variables - Generates errors for dangerous operations - Improves performance in some JavaScript engines</p> </div> <div class="paragraph"> <p>For a critical script like this, we want maximum security.</p> </div> <div class="paragraph"> <p><strong>The try…​catch Block</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>This block is absolutely crucial. It ensures that if something goes wrong (localStorage blocked, improbable syntax error, etc.), our script will not block the loading of the entire page. Using`console.warn`rather than`console.error`indicates that it is a non-critical problem.</p> </div> <div class="paragraph"> <p><strong>Reading 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>This line can throw an exception in some contexts (Safari strict private browsing). That is why it is in a try…​catch block.</p> </div> <div class="paragraph"> <p><strong>Conditional Application</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>We apply the theme only if we found a saved one. Otherwise, we let the CSS use its default theme. This approach is more robust than a default value hard-coded in JavaScript.</p> </div> </div> <div class="sect2"> <h3 id="_system_preference_detection_bonus">System Preference Detection (Bonus)</h3> <div class="paragraph"> <p>An optional but elegant improvement is to detect the theme preference of the user’s operating system if they have not yet made an explicit choice in your application:</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>This feature uses the`prefers-color-scheme`Media Query to query the system. On macOS, Windows 10+, iOS, and modern Android, this query returns the user’s system preference.</p> </div> <div class="paragraph"> <p><strong>Advantages:</strong> - Personalized experience from the first visit - Consistency with the user’s system environment - No storage required for the first visit</p> </div> <div class="paragraph"> <p><strong>Considerations:</strong> - Not all browsers support this feature (but support has been excellent since 2020) - The`window.matchMedia`check ensures compatibility - The user can still override this choice</p> </div> </div> <div class="sect2"> <h3 id="_performance_why_this_script_is_fast">Performance: Why this Script is Fast</h3> <div class="paragraph"> <p>Our preloading script is designed to be extremely fast:</p> </div> <div class="paragraph"> <p><strong>Minimal size</strong>: About 300 bytes unminified, 200 bytes minified. This is negligible compared to any image or JavaScript library.</p> </div> <div class="paragraph"> <p><strong>Inline</strong>: No additional HTTP request. The script is in the HTML, so it is immediately available.</p> </div> <div class="paragraph"> <p><strong>Simple synchronous operations</strong>: Reading a key in localStorage (ultra-fast operation) and modifying a DOM attribute (native browser operation).</p> </div> <div class="paragraph"> <p><strong>No dependencies</strong>: No framework, no library, just vanilla JavaScript. No startup time, no dependency parsing.</p> </div> <div class="paragraph"> <p><strong>Single execution</strong>: This script executes only once upon loading. No event listeners, no loops, no complex calculations.</p> </div> <div class="paragraph"> <p>In practice, on modern hardware, this script executes in less than 1 millisecond, an imperceptible time that has no impact on the page loading performance.</p> </div> </div> <div class="sect2"> <h3 id="_optimal_placement_in_the_head">Optimal Placement in the <code><head></code></h3> <div class="paragraph"> <p>The order of elements in the`<head>`is important. Here is the recommended order:</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>This order ensures that:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>The charset is defined before any text processing</p> </li> <li> <p>Our script executes before the loading of CSS</p> </li> <li> <p>The CSS is loaded next and directly applies the correct theme</p> </li> <li> <p>Other non-critical resources are loaded last</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_3_the_power_of_css_attribute_selectors">Step 3: The Power of CSS Attribute Selectors</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_bootstrap_5_theme_system">The Bootstrap 5 Theme System</h3> <div class="paragraph"> <p>Bootstrap 5 introduced an elegant theme management system based on CSS custom properties (CSS variables) and attribute selectors. This system uses the`data-bs-theme`attribute on the`<html>`element to determine which set of color variables to apply.</p> </div> <div class="paragraph"> <p>The beauty of this system lies in its simplicity: instead of loading different stylesheets or toggling classes on thousands of elements, we simply change one attribute on a single element, and the CSS does the rest thanks to the cascade.</p> </div> </div> <div class="sect2"> <h3 id="_css_structure_for_a_theme_system">CSS Structure for a Theme System</h3> <div class="paragraph"> <p>Here is a complete CSS structure to implement a robust theme system:</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/en/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="#_introduction">Introduction</a></li> <li><a href="#_the_problem_dependency_on_gradlerunner">The Problem: Dependency on GradleRunner</a> <ul class="sectlevel2"> <li><a href="#_plugin_development_context">Plugin Development Context</a></li> <li><a href="#_the_logging_dilemma">The Logging Dilemma</a></li> <li><a href="#_false_good_ideas">False Good Ideas</a></li> </ul> </li> <li><a href="#_the_solution_independent_logger">The Solution: Independent Logger</a> <ul class="sectlevel2"> <li><a href="#_recommended_architecture">Recommended Architecture</a></li> <li><a href="#_execution_flow">Execution Flow</a></li> </ul> </li> <li><a href="#_complete_implementation">Complete Implementation</a> <ul class="sectlevel2"> <li><a href="#_gradle_dependencies">Gradle Dependencies</a></li> <li><a href="#_logback_configuration">Logback Configuration</a></li> <li><a href="#_complete_test_class">Complete Test Class</a></li> </ul> </li> <li><a href="#_multi_level_logging_schema">Multi-Level Logging Schema</a></li> <li><a href="#_best_practices">Best Practices</a> <ul class="sectlevel2"> <li><a href="#_recommended_logging_structure">Recommended Logging Structure</a></li> <li><a href="#_visual_symbols_for_readability">Visual Symbols for Readability</a></li> <li><a href="#_information_extraction_from_output">Information Extraction from Output</a></li> </ul> </li> <li><a href="#_beforeafter_comparison">Before/After Comparison</a> <ul class="sectlevel2"> <li><a href="#_before_problematic_approach">Before: Problematic Approach</a></li> <li><a href="#_after_robust_approach">After: Robust Approach</a></li> </ul> </li> <li><a href="#_summary_diagram">Summary Diagram</a></li> <li><a href="#_pitfalls_to_avoid">Pitfalls to Avoid</a> <ul class="sectlevel2"> <li><a href="#_pitfall_1_forgetting_forwardoutput">❌ Pitfall #1: Forgetting <code>.forwardOutput()</code></a></li> <li><a href="#_pitfall_2_uninitialized_logger">❌ Pitfall #2: Uninitialized Logger</a></li> <li><a href="#_pitfall_3_excessive_logging">❌ Pitfall #3: Excessive Logging</a></li> </ul> </li> <li><a href="#_results_and_metrics">Results and Metrics</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_resources">Resources</a></li> <li><a href="#_going_further">Going Further</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>When developing a Gradle plugin, functional tests are essential to validate the plugin’s behavior in a real Gradle environment. However, a crucial question quickly arises:<strong>how to implement an efficient logging system without creating problematic dependencies with <code>GradleRunner</code>?</strong></p> </div> <div class="paragraph"> <p>In this article, we will explore:</p> </div> <div class="ulist"> <ul> <li> <p>The logging problem in Gradle functional tests</p> </li> <li> <p>The architecture of a robust solution with SLF4J and Logback</p> </li> <li> <p>Complete implementation with concrete examples</p> </li> <li> <p>Best practices and pitfalls to avoid</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_dependency_on_gradlerunner">The Problem: Dependency on GradleRunner</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_plugin_development_context">Plugin Development Context</h3> <div class="paragraph"> <p>When developing a Gradle plugin, we generally use the`GradleRunner`of <em>Gradle TestKit</em> to execute test builds:</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="_the_logging_dilemma">The Logging Dilemma</h3> <div class="paragraph"> <p>The main problem is as follows:<strong>logging must not depend on an object whose initialization is uncertain</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-098f273556d73eefcb03088a9c320c28.png" alt="Diagram" width="460" height="262"> </div> </div> </div> <div class="sect2"> <h3 id="_false_good_ideas">False Good Ideas</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Do NOT do this:</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="_the_solution_independent_logger">The Solution: Independent Logger</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recommended_architecture">Recommended Architecture</h3> <div class="paragraph"> <p>The solution is to use a<strong>completely independent</strong> du `GradleRunner`logger, initialized at the test class level.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ffb0cf405a345057991a32f0ed77e9f4.png" alt="Diagram" width="601" height="448"> </div> </div> </div> <div class="sect2"> <h3 id="_execution_flow">Execution Flow</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ee708f49dc49046ba65da9a958958434.png" alt="Diagram" width="713" height="686"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_complete_implementation">Complete Implementation</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_gradle_dependencies">Gradle Dependencies</h3> <div class="paragraph"> <p>Add the necessary dependencies in your`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="_logback_configuration">Logback Configuration</h3> <div class="paragraph"> <p>Create the file`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="_complete_test_class">Complete Test Class</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="_multi_level_logging_schema">Multi-Level Logging Schema</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-69cc83dd2b31ced14c3dd245c6509cb0.png" alt="Diagram" width="314" height="911"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_best_practices">Best Practices</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_recommended_logging_structure">Recommended Logging Structure</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="_visual_symbols_for_readability">Visual Symbols for Readability</h3> <div class="paragraph"> <p>Use Unicode symbols to improve log readability:</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="_information_extraction_from_output">Information Extraction from Output</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="_beforeafter_comparison">Before/After Comparison</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_before_problematic_approach">Before: Problematic Approach</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="_after_robust_approach">After: Robust Approach</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="_summary_diagram">Summary Diagram</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e6aafa175e92a0e0de6ae9cdeb5f360e.png" alt="Diagram" width="963" height="1345"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pitfalls_to_avoid">Pitfalls to Avoid</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pitfall_1_forgetting_forwardoutput">❌ Pitfall #1: Forgetting <code>.forwardOutput()</code></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="_pitfall_2_uninitialized_logger">❌ Pitfall #2: Uninitialized Logger</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="_pitfall_3_excessive_logging">❌ Pitfall #3: Excessive Logging</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="_results_and_metrics">Results and Metrics</h2> <div class="sectionbody"> <div class="paragraph"> <p>With this approach, you get:</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">Metric</th> <th class="tableblock halign-left valign-top">Before</th> <th class="tableblock halign-left valign-top">After</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Lines of code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50 lines</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~80 lines (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Debug time</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~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">Detected errors</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Basic</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Detailed</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Maintenance</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Difficult</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Simple</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Independence</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Coupled</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✓ Independent</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Implementing a robust logging system in Gradle plugin functional tests rests on a simple principle:<strong>independence</strong>.</p> </div> <div class="paragraph"> <p>Key points to remember:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Independent logger</strong>: Initialized in a`companion object`</p> </li> <li> <p><strong>SLF4J + Logback</strong>: Proven and configurable stack</p> </li> <li> <p><strong><code>.forwardOutput()</code></strong>: Capture of Gradle output</p> </li> <li> <p><strong>Structured logging</strong>: INFO for steps, DEBUG for details</p> </li> <li> <p><strong>Output analysis</strong>: Extraction of information from`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>This approach ensures tests that are<strong>maintainable</strong>, <strong>debuggable</strong> et <strong>robust</strong>, while respecting solid design principles.</p> </div> </div> </div> <div class="sect1"> <h2 id="_resources">Resources</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/test_kit.html">Gradle TestKit Documentation</a></p> </li> <li> <p><a href="https://www.slf4j.org/manual.html">SLF4J Manual</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">Gradle TestKit Source Code</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_going_further">Going Further</h2> <div class="sectionbody"> <div class="paragraph"> <p>In a future article, we will explore:</p> </div> <div class="ulist"> <ul> <li> <p>Continuous integration with structured logging</p> </li> <li> <p>HTML test reports with integrated logs</p> </li> <li> <p>Advanced debugging with JVM attach</p> </li> <li> <p>Logging performance and optimizations</p> </li> </ul> </div> <div class="paragraph"> <p><em>This article is part of the "Gradle Plugin Development" series on my technical blog.</em></p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_the_problem">The Problem</a> <ul class="sectlevel2"> <li><a href="#_usage_context">Usage Context</a></li> <li><a href="#_possible_approaches">Possible Approaches</a> <ul class="sectlevel3"> <li><a href="#_option_1_unicode_characters">Option 1: Unicode Characters</a></li> <li><a href="#_option_2_external_images">Option 2: External Images</a></li> <li><a href="#_option_3_custom_css_roles">Option 3: Custom CSS Roles</a></li> <li><a href="#_option_4_html_injection_chosen_solution">Option 4: HTML Injection (chosen solution)</a></li> </ul> </li> </ul> </li> <li><a href="#_the_solution_html_injection_with">The Solution: HTML Injection with <code></code></a> <ul class="sectlevel2"> <li><a href="#_working_principle">Working Principle</a></li> <li><a href="#_implementation">Implementation</a> <ul class="sectlevel3"> <li><a href="#_explanation_of_css_properties">Explanation of CSS Properties</a></li> </ul> </li> <li><a href="#_complete_example">Complete Example</a></li> </ul> </li> <li><a href="#_optimizations_and_best_practices">Optimizations and Best Practices</a> <ul class="sectlevel2"> <li><a href="#_handling_light_colors">Handling Light Colors</a></li> <li><a href="#_adapting_square_size">Adapting Square Size</a></li> <li><a href="#_creating_variants">Creating Variants</a> <ul class="sectlevel3"> <li><a href="#_colored_circle">Colored circle</a></li> <li><a href="#_square_with_colored_border">Square with colored border</a></li> </ul> </li> </ul> </li> <li><a href="#_solution_architecture">Solution Architecture</a></li> <li><a href="#_advantages_and_limitations">Advantages and Limitations</a> <ul class="sectlevel2"> <li><a href="#_advantages">Advantages</a></li> <li><a href="#_limitations">Limitations</a></li> <li><a href="#_improving_accessibility">Improving Accessibility</a></li> </ul> </li> <li><a href="#_concrete_example_theme_documentation">Concrete Example: Theme Documentation</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_resources">Resources</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>When writing technical documentation, especially for style guides or user interface specifications, it is common to need to display color palettes. AsciiDoc, while very powerful for documentation, does not offer native syntax for displaying color samples. This article explores the problem and proposes an elegant solution based on HTML injection.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem">The Problem</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_usage_context">Usage Context</h3> <div class="paragraph"> <p>Imagine you are documenting the CSS variables of a web application theme. You need to:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>List the hexadecimal color codes</p> </li> <li> <p>Display a visual preview of each color</p> </li> <li> <p>Maintain the readability of the source document</p> </li> <li> <p>Ensure compatibility with static site generators like JBake</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="use-case-diagram.svg" alt="use case diagram" width="1050" height="205"> </div> </div> </div> <div class="sect2"> <h3 id="_possible_approaches">Possible Approaches</h3> <div class="paragraph"> <p>Several solutions can be considered for displaying colors in an AsciiDoc document:</p> </div> <div class="imageblock"> <div class="content"> <img src="component-diagram.svg" alt="component diagram" width="874" height="190"> </div> </div> <div class="sect3"> <h4 id="_option_1_unicode_characters">Option 1: Unicode Characters</h4> <div class="paragraph"> <p>Using Unicode characters like`■`(■) is simple but limited:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* ■ --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitations</strong>: No control over color, depends on the system font.</p> </div> </div> <div class="sect3"> <h4 id="_option_2_external_images">Option 2: External Images</h4> <div class="paragraph"> <p>Creating PNG or SVG images for each color:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* image:colors/violet.svg[width=16] --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitations</strong>: Heavy maintenance, proliferation of files, no automatic synchronization.</p> </div> </div> <div class="sect3"> <h4 id="_option_3_custom_css_roles">Option 3: Custom CSS Roles</h4> <div class="paragraph"> <p>Defining CSS classes and applying them via AsciiDoc roles:</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>Limitations</strong>: Requires an external stylesheet, prior definition of all possible colors.</p> </div> </div> <div class="sect3"> <h4 id="_option_4_html_injection_chosen_solution">Option 4: HTML Injection (chosen solution)</h4> <div class="paragraph"> <p>Using the <code></code> macro``to inject HTML with inline styles:</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="_the_solution_html_injection_with">The Solution: HTML Injection with <code></code></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_working_principle">Working Principle</h3> <div class="paragraph"> <p>The <code></code> macro``in AsciiDoc allows the insertion of raw content that will not be interpreted by the AsciiDoc processor. This allows us to directly inject HTML with inline CSS styles.</p> </div> <div class="imageblock"> <div class="content"> <img src="sequence-diagram.svg" alt="sequence diagram" width="628" height="282"> </div> </div> </div> <div class="sect2"> <h3 id="_implementation">Implementation</h3> <div class="paragraph"> <p>Here is the HTML structure to inject:</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="_explanation_of_css_properties">Explanation of CSS Properties</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">Property</th> <th class="tableblock halign-left valign-top">Function</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">Allows defining width/height while remaining in the inline flow</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">Square size relative to font size (responsive)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>background:#7952b3</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The color to display (variable according to your needs)</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">Aligns the square with the adjacent text</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">Spacing between the square and the text</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_complete_example">Complete Example</h3> <div class="paragraph"> <p>Here is an example documenting a theme palette:</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>Which produces the following rendering:</p> </div> <div class="paragraph"> <p><strong>Light Theme</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`(off-white)</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`(very dark black)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --accent-color:`#7952b3`(Bootstrap purple)</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`(darker purple)</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`(white)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_optimizations_and_best_practices">Optimizations and Best Practices</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_handling_light_colors">Handling Light Colors</h3> <div class="paragraph"> <p>For very light colors (white, very light gray), add a border to make them visible on a white background:</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>The gray border (<code>border:1px solid #ccc</code>) allows the white square to be delineated on a white background.</p> </div> </div> <div class="sect2"> <h3 id="_adapting_square_size">Adapting Square Size</h3> <div class="paragraph"> <p>You can adjust the size of the squares according to your needs:</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>Using the <code>em</code> unit`em`ensures that the squares adapt to the font size.</p> </div> </div> <div class="sect2"> <h3 id="_creating_variants">Creating Variants</h3> <div class="paragraph"> <p>For specific needs, you can create different shapes:</p> </div> <div class="sect3"> <h4 id="_colored_circle">Colored circle</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="_square_with_colored_border">Square with colored border</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="_solution_architecture">Solution Architecture</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="architecture-diagram.svg" alt="architecture diagram" width="483" height="412"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_advantages_and_limitations">Advantages and Limitations</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_advantages">Advantages</h3> <div class="ulist"> <ul> <li> <p>✓ <strong>Autonomy</strong>: No dependency on external files</p> </li> <li> <p>✓ <strong>Portability</strong>: Works with all AsciiDoc processors</p> </li> <li> <p>✓ <strong>Synchronization</strong>: The color code is directly in the HTML</p> </li> <li> <p>✓ <strong>Flexibility</strong>: Complete style customization</p> </li> <li> <p>✓ <strong>Maintenance</strong>: Simple modification of the hexadecimal code</p> </li> <li> <p>✓ <strong>JBake Compatibility</strong>: Works perfectly with static site generators</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_limitations">Limitations</h3> <div class="ulist"> <ul> <li> <p>✗ <strong>Verbosity</strong>: Repetitive HTML code in the AsciiDoc source</p> </li> <li> <p>✗ <strong>Source Readability</strong>: The source document is less clean</p> </li> <li> <p>✗ <strong>Accessibility</strong>: No native alternative text (must be added manually)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_improving_accessibility">Improving Accessibility</h3> <div class="paragraph"> <p>To make the squares accessible to screen readers:</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>The <code>role</code> and <code>aria-label</code> attributes`role="img"` et `aria-label`allow assistive technologies to understand and describe the visual content.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_concrete_example_theme_documentation">Concrete Example: Theme Documentation</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is a complete example documenting several themes:</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>HTML injection via the <code></code> macro``in AsciiDoc offers an elegant and pragmatic solution for displaying color samples in technical documentation. Although slightly verbose, this approach guarantees maximum portability and simplified maintenance.</p> </div> <div class="paragraph"> <p>This technique requires no external configuration, no additional stylesheets, and works immediately with JBake and all standard AsciiDoc processors.</p> </div> <div class="paragraph"> <p>Once you have created your first colored square, simply copy and paste the HTML code and modify the hexadecimal code to quickly create a complete palette.</p> </div> <div class="paragraph"> <p>This technique can be extended to other use cases requiring custom visual rendering: icons, badges, simple graphics, or any visual element requiring precise style control.</p> </div> </div> </div> <div class="sect1"> <h2 id="_resources">Resources</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">AsciiDoc Documentation: pass macro</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake Documentation</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value" target="_blank" rel="noopener">MDN: CSS Color Values</a></p> </li> </ul> </div> <div class="paragraph"> <p><em>Article published on 2025-11-01</em></p> </div> </div> </div> https://cheroliv.com/en/blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html Mon, 20 Oct 2025 00:00:00 +0000 blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduction">Introduction</a> <ul class="sectlevel2"> <li><a href="#_use_case_diagram">Use Case Diagram</a></li> </ul> </li> <li><a href="#_internationalization_architecture">Internationalization Architecture</a> <ul class="sectlevel2"> <li><a href="#_structure_diagram_file_organization">Structure Diagram (File Organization)</a></li> <li><a href="#_why_this_approach">Why this approach?</a></li> <li><a href="#_component_diagram">Component Diagram</a></li> </ul> </li> <li><a href="#_templating_i18n_with_thymeleaf">Templating i18n with Thymeleaf</a> <ul class="sectlevel2"> <li><a href="#_message_file_structure">Message file structure</a></li> <li><a href="#_content_of_message_files">Content of message files</a></li> <li><a href="#_usage_in_templates">Usage in templates</a></li> <li><a href="#_sequence_diagram_i18n_resolution">Sequence Diagram - i18n Resolution</a></li> <li><a href="#_locale_configuration_in_jbake">Locale configuration in JBake</a></li> </ul> </li> <li><a href="#_article_i18n_organization_by_folders">Article i18n: organization by folders</a> <ul class="sectlevel2"> <li><a href="#_flow_diagram_generation">Flow Diagram - Generation</a></li> <li><a href="#_folder_structure">Folder structure</a></li> <li><a href="#_advantages_of_this_approach">Advantages of this approach</a></li> <li><a href="#_article_metadata">Article metadata</a></li> <li><a href="#_url_configuration">URL Configuration</a></li> </ul> </li> <li><a href="#_templates_for_multilingual_display">Templates for multilingual display</a> <ul class="sectlevel2"> <li><a href="#_article_template_with_language_selector">Article template with language selector</a></li> <li><a href="#_index_filtered_by_language">Index filtered by language</a></li> </ul> </li> <li><a href="#_navigation_between_languages">Navigation between languages</a> <ul class="sectlevel2"> <li><a href="#_global_language_selector">Global language selector</a></li> <li><a href="#_flow_diagram_user_reading">Flow Diagram - User Reading</a></li> <li><a href="#_css_style_for_the_selector">CSS style for the selector</a></li> </ul> </li> <li><a href="#_rss_feeds_by_language">RSS feeds by language</a></li> <li><a href="#_best_practices_and_tips">Best practices and tips</a> <ul class="sectlevel2"> <li><a href="#_1_consistency_of_article_identifiers">1. Consistency of article identifiers</a></li> <li><a href="#_2_consistent_dates">2. Consistent dates</a></li> <li><a href="#_3_multilingual_tags">3. Multilingual tags</a></li> <li><a href="#_4_management_of_untranslated_articles">4. Management of untranslated articles</a></li> <li><a href="#_5_multilingual_sitemap">5. Multilingual sitemap</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a> <ul class="sectlevel2"> <li><a href="#_deployment_diagram">Deployment Diagram</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>Internationalization (i18n) of a static site may seem complex at first, but JBake combined with Thymeleaf offers elegant solutions for creating a multilingual site. In this article, I will show you how I implemented i18n on my blog, covering both templating and the management of articles in multiple languages.</p> </div> <div class="sect2"> <h3 id="_use_case_diagram">Use Case Diagram</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c2a5be17bd909780be607cfd597f215f.png" alt="Diagram" width="660" height="447"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_internationalization_architecture">Internationalization Architecture</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our approach is based on two pillars:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Templating i18n</strong>: use of Thymeleaf message files for interface elements</p> </li> <li> <p><strong>Content i18n</strong>: organization of articles by language in a dedicated folder structure</p> </li> </ol> </div> <div class="sect2"> <h3 id="_structure_diagram_file_organization">Structure Diagram (File Organization)</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="_why_this_approach">Why this approach?</h3> <div class="paragraph"> <p>This separation allows for:</p> </div> <div class="ulist"> <ul> <li> <p>Maintaining consistency in the interface regardless of the language</p> </li> <li> <p>Independent management of content and article translations</p> </li> <li> <p>Easier addition of new languages without major refactoring</p> </li> <li> <p>Allowing articles to be available only in certain languages</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_component_diagram">Component Diagram</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-9d42e1ff744debfc429aaa889922ac15.png" alt="Diagram" width="1771" height="477"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_templating_i18n_with_thymeleaf">Templating i18n with Thymeleaf</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_message_file_structure">Message file structure</h3> <div class="paragraph"> <p>The first step consists of creating property files for each supported language:</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="_content_of_message_files">Content of message files</h3> <div class="paragraph"> <p>Here is an example of a file`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>And its English equivalent`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="_usage_in_templates">Usage in templates</h3> <div class="paragraph"> <p>In your Thymeleaf templates, use the syntax`#{}`to access messages:</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="_sequence_diagram_i18n_resolution">Sequence Diagram - i18n Resolution</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-890efdf0cf45e6d957ea45af6e68a11d.png" alt="Diagram" width="910" height="882"> </div> </div> </div> <div class="sect2"> <h3 id="_locale_configuration_in_jbake">Locale configuration in JBake</h3> <div class="paragraph"> <p>In your`jbake.properties`file, define the default locale:</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="_article_i18n_organization_by_folders">Article i18n: organization by folders</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flow_diagram_generation">Flow Diagram - Generation</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-dc5f4bca87c443b337bf4e82c96c9a69.png" alt="Diagram" width="285" height="1034"> </div> </div> </div> <div class="sect2"> <h3 id="_folder_structure">Folder structure</h3> <div class="paragraph"> <p>Rather than using suffixes in filenames, I opted for a folder organization which offers more clarity and maintainability:</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="_advantages_of_this_approach">Advantages of this approach</h3> <div class="paragraph"> <p>This structure presents several advantages:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Clear separation</strong>: each language has its own space</p> </li> <li> <p><strong>Flexible naming</strong>: files can have different names depending on the language</p> </li> <li> <p><strong>Scalability</strong>: easy to add a new language</p> </li> <li> <p><strong>Natural organization</strong>: follows the JBake temporal logic</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_article_metadata">Article metadata</h3> <div class="paragraph"> <p>Each article must contain metadata to allow linking between translations. Here is an example:</p> </div> <div class="paragraph"> <p><strong>French version</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>English version</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="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> The`:jbake-article-id:`attribute is crucial: it allows linking different translations of the same article. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_url_configuration">URL Configuration</h3> <div class="paragraph"> <p>In`jbake.properties`, configure the URL pattern to include the language:</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>This will generate URLs of the type:</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="_templates_for_multilingual_display">Templates for multilingual display</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_article_template_with_language_selector">Article template with language selector</h3> <div class="paragraph"> <p>Create a`post.html`template that displays available translations:</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="_index_filtered_by_language">Index filtered by language</h3> <div class="paragraph"> <p>Create index templates for each language:</p> </div> <div class="paragraph"> <p><strong><code>index.html</code></strong>(French index) :</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><code>index_en.html</code></strong>(English index) :</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="_navigation_between_languages">Navigation between languages</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_global_language_selector">Global language selector</h3> </div> <div class="sect2"> <h3 id="_flow_diagram_user_reading">Flow Diagram - User Reading</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>Add a language selector in your main template:</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="_css_style_for_the_selector">CSS style for the selector</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.language-switcher { display: flex; gap: 1rem; padding: 0.5rem; background: #f5f5f5; border-radius: 4px; } .language-switcher a { padding: 0.5rem 1rem; text-decoration: none; color: #333; border-radius: 4px; transition: background 0.2s; } .language-switcher a:hover { background: #e0e0e0; } .language-switcher a.active { background: #007bff; color: white; } .translations { margin: 1rem 0; padding: 1rem; background: #f8f9fa; border-left: 4px solid #007bff; } .language-list { display: inline-flex; gap: 0.5rem; list-style: none; padding: 0; margin: 0; } .language-list li::after { content: "•"; margin-left: 0.5rem; } .language-list li:last-child::after { content: ""; }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_rss_feeds_by_language">RSS feeds by language</h2> <div class="sectionbody"> <div class="paragraph"> <p>To have RSS feeds separated by language, create distinct templates:</p> </div> <div class="paragraph"> <p><strong><code>feed.xml</code></strong>(French feed) :</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="_best_practices_and_tips">Best practices and tips</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_consistency_of_article_identifiers">1. Consistency of article identifiers</h3> <div class="paragraph"> <p>Ensure that`:jbake-article-id:`is identical for all translations of the same article. Use a consistent format:</p> </div> <div class="ulist"> <ul> <li> <p>Prefer English identifiers for universality</p> </li> <li> <p>Use dashes to separate words</p> </li> <li> <p>Avoid special characters</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_consistent_dates">2. Consistent dates</h3> <div class="paragraph"> <p>All translations of an article must have the same publication date (<code>:jbake-date:</code>). This facilitates sorting and chronological display.</p> </div> </div> <div class="sect2"> <h3 id="_3_multilingual_tags">3. Multilingual tags</h3> <div class="paragraph"> <p>For tags, you have two options:</p> </div> <div class="paragraph"> <p><strong>Option 1: Universal tags in English</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> <div class="paragraph"> <p><strong>Option 2: Translated tags with mapping</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_management_of_untranslated_articles">4. Management of untranslated articles</h3> <div class="paragraph"> <p>It is not mandatory to translate all articles. If an article only exists in one language, it will simply not appear in the listings of the other language.</p> </div> </div> <div class="sect2"> <h3 id="_5_multilingual_sitemap">5. Multilingual sitemap</h3> <div class="paragraph"> <p>Generate a sitemap that includes all languages:</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Internationalization of a JBake site with Thymeleaf is a robust and maintainable approach. By separating templating i18n (via message files) and content i18n (via folder organization), you obtain a flexible system that can evolve easily.</p> </div> <div class="paragraph"> <p>Key points to remember:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Thymeleaf message files</strong>for the user interface</p> </li> <li> <p><strong>Folder organization</strong>(year/language) for articles</p> </li> <li> <p><strong>Article identifiers</strong>to link translations</p> </li> <li> <p><strong>Dedicated templates</strong>for each language</p> </li> <li> <p><strong>Explicit URLs</strong>including the language code</p> </li> </ul> </div> <div class="sect2"> <h3 id="_deployment_diagram">Deployment Diagram</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e93d75cf1c345b28883ab04c6a861e54.png" alt="Diagram" width="535" height="713"> </div> </div> <div class="paragraph"> <p>This architecture allows you to start simply with two languages and add others without major refactoring. Everything remains entirely static and performant, faithful to the JBake philosophy.</p> </div> <div class="paragraph"> <p>Happy multilingual development! 🌍</p> </div> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_downloading_tor_and_its_signature">Downloading Tor and its signature</a></li> <li><a href="#_cryptographic_verification_of_the_signature">Cryptographic verification of the signature</a> <ul class="sectlevel2"> <li><a href="#_1_import_the_tor_project_public_key">1. Import the Tor Project public key</a></li> <li><a href="#_2_verify_the_signature">2. Verify the signature</a></li> <li><a href="#_practical_case_valid_signature_but_uncertified_key">Practical case: Valid signature but uncertified key</a></li> </ul> </li> <li><a href="#_why_verify_the_signature">Why verify the signature?</a></li> <li><a href="#_extraction_and_launching_of_tor_browser">Extraction and launching of Tor Browser</a></li> <li><a href="#_integration_into_the_ubuntu_desktop">Integration into the Ubuntu desktop</a></li> <li><a href="#_explore_educational_resources_with_tor">Explore educational resources with Tor</a></li> <li><a href="#_updating_tor_browser">Updating Tor Browser</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_references">References</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>In a world where digital privacy is increasingly threatened, <strong>Tor Browser</strong> remains an essential tool for preserving anonymity and freedom of information. However, it is crucial to never run downloaded software without having<strong>verified its authenticity</strong>. This article presents a complete method to:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Download <strong>Tor Browser</strong> and its signature`.asc`</p> </li> <li> <p>Verify the validity of the downloaded file</p> </li> <li> <p>Install and launch <strong>Tor Browser</strong> on Ubuntu</p> </li> <li> <p>Add it to the desktop menus for daily use</p> </li> <li> <p>Explore educational and ethical OSINT resources via Tor</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_downloading_tor_and_its_signature">Downloading Tor and its signature</h2> <div class="sectionbody"> <div class="paragraph"> <p>Create a dedicated folder for the Tor browser:</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>Then download the Tor browser archive and its signature:</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="_cryptographic_verification_of_the_signature">Cryptographic verification of the signature</h2> <div class="sectionbody"> <div class="paragraph"> <p>This step is<strong>indispensable</strong>to ensure that the downloaded file truly comes from the <strong>Tor Project</strong> and has not been modified.</p> </div> <div class="sect2"> <h3 id="_1_import_the_tor_project_public_key">1. Import the Tor Project public key</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>Verify that the key has been imported:</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_verify_the_signature">2. Verify the signature</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>If everything is correct, the following message will appear:</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>In the event of an uncertified key warning, this simply means that you have not yet signed the Tor Project’s trust key, but the signature remains valid.</p> </div> </div> <div class="sect2"> <h3 id="_practical_case_valid_signature_but_uncertified_key">Practical case: Valid signature but uncertified key</h3> <div class="paragraph"> <p>It is common to encounter a message like this during verification:</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>This message indicates that the signature is technically "good" (the file has not been altered), but that your GPG system cannot <strong>certify the trust</strong> in the key itself. To resolve this doubt, it is imperative to compare the fingerprint of the main key (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) with the one published on the official Tor Project website.</p> </div> <div class="paragraph"> <p>According to the official site, the expected fingerprint is:`EF6E286DDA85EA2A4BA7DE684E2C6E8793298290`.</p> </div> <div class="paragraph"> <p>Since the fingerprint displayed by`gpg`matches <strong>exactly</strong> the one from the official site, you can be certain that the key is legitimate and the file is safe. The "uncertified key" warning is then information about your local GPG configuration, and not about the validity of the signature or the authenticity of the file.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_why_verify_the_signature">Why verify the signature?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Verifying GPG signatures is a fundamental act of digital security. It allows you to:</p> </div> <div class="ulist"> <ul> <li> <p>Guarantee<strong>the authenticity</strong>of the downloaded software</p> </li> <li> <p>Prevent the installation of a file compromised by a malicious actor</p> </li> <li> <p>Participate in<strong>individual digital sovereignty</strong> individuelle</p> </li> <li> <p>Encourage a responsible and ethical digital culture</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="usecase-tor-verification.svg" alt="usecase tor verification" width="420" height="264"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_extraction_and_launching_of_tor_browser">Extraction and launching of Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Decompress the downloaded archive:</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>Then launch the browser:</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>Upon the first launch, a configuration window will open to establish the connection to the Tor network.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integration_into_the_ubuntu_desktop">Integration into the Ubuntu desktop</h2> <div class="sectionbody"> <div class="paragraph"> <p>To add <strong>Tor Browser</strong> to the applications menu:</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>You can then:</p> </div> <div class="ulist"> <ul> <li> <p>Launch <strong>Tor Browser</strong> from the applications menu</p> </li> <li> <p>Add it to the dock favorites</p> </li> <li> <p>Create a keyboard shortcut if desired</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="_explore_educational_resources_with_tor">Explore educational resources with Tor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor is not solely an anonymity tool. It constitutes a gateway to educational and research resources, notably in the fields of:</p> </div> <div class="ulist"> <ul> <li> <p><strong>OSINT (Open Source Intelligence)</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>Educational and open source sharing</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(access via Tor for more privacy)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(browsable via Tor)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(access to free scientific literature)</p> </li> <li> <p><strong>Knowledge transmission and understanding of humans in the digital society</strong></p> </li> <li> <p>Resources on digital culture, freedom of expression, and access to knowledge</p> </li> <li> <p>Free documentation on cybersecurity and technology ethics</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_updating_tor_browser">Updating Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>To ensure optimal security, it is crucial to keep <strong>Tor Browser</strong> up to date. The browser includes an automatic update mechanism that can be triggered via the command line.</p> </div> <div class="paragraph"> <p>From the Tor Browser installation directory, simply relaunch the startup script:</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>Upon launching, <strong>Tor Browser</strong> will automatically check if a new version exists. If so, it will download and install it for you.</p> </div> <div class="paragraph"> <p>This simple method ensures that you always have the latest security patches and the most recent improvements, which is essential for secure browsing.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Verifying downloads is an essential reflex for anyone wishing to evolve in a secure digital environment. Installing Tor in a verified manner means<strong>protecting one’s digital integrity</strong>, <strong>preserving trust in free software</strong>, et <strong>strengthening one’s informational autonomy</strong>.</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>Digital security is an act of consciousness, not paranoia.</strong></p> </div> </blockquote> </div> <div class="imageblock"> <div class="content"> <img src="summary-diagram.svg" alt="summary diagram" width="442" height="203"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_references">References</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Official Tor Project site:https://www.torproject.org/download/[<a href="https://www.torproject.org/download/" class="bare">https://www.torproject.org/download/</a>]</p> </li> <li> <p>Signature verification documentation: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>Ubuntu documentation:https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>Educational archive: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>This article is part of the <strong>Digital Security and Consciousness</strong> series, aiming to promote responsible and pedagogical practices around free tools.</p> </div> </td> </tr> </table> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_1_the_version_catalog_libs_versions_toml_a_reminder">1. The Version Catalog (<code>libs.versions.toml</code>): A Reminder</a></li> <li><a href="#_2_the_problem_a_composite_build_and_two_separate_worlds">2. The Problem: A Composite Build and Two Separate Worlds</a></li> <li><a href="#_3_the_solution_sharing_dependency_resolution">3. The Solution: Sharing Dependency Resolution</a></li> <li><a href="#_4_conclusion_the_power_of_well_managed_composite_builds">4. Conclusion: The Power of Well-Managed Composite Builds</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Target audience: Gradle developers facing dependency management in multi-build projects.</div> <p>In our quest to create the`site-baker`plugin, we sought to maintain a clean and centralized codebase. One of the best practices in the modern Gradle ecosystem is the use of the<strong>version catalog</strong>(<code>libs.versions.toml</code>) to manage dependencies. But what happens when your project becomes more complex, such as a<strong>composite build</strong>where an independent build (our plugin) must be included in another?</p> </div> <div class="paragraph"> <p>That is where our adventure took an unexpected turn. We wanted our`site-baker`plugin, which is itself a Gradle project, to use the same version catalog as our main project. This article, the fifth in our series, tells the story of how we solved this challenge.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_the_version_catalog_libs_versions_toml_a_reminder">1. The Version Catalog (<code>libs.versions.toml</code>): A Reminder</h2> <div class="sectionbody"> <div class="paragraph"> <p>The`gradle/libs.versions.toml`file is a Gradle feature that allows you to centralize the versions and coordinates of your project’s dependencies. It is generally structured into four sections:</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: Defines aliases for version numbers (e.g.,<code>kotlin = "1.9.20"</code>).</p> </li> <li> <p><code>[libraries]</code>: Defines aliases for complete dependencies, using the versions defined above (e.g.,<code>kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }</code>).</p> </li> <li> <p><code>[bundles]</code>: Groups several libraries under a single alias (e.g.,<code>jackson = ["jackson-core", "jackson-databind"]</code>).</p> </li> <li> <p><code>[plugins]</code>: Defines aliases for Gradle plugins.</p> </li> </ul> </div> <div class="paragraph"> <p>Once defined, Gradle automatically generates typed accessors, which makes your`build.gradle.kts`much more readable:</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="478" height="252"> </div> <div class="title">Figure 1. Version catalog data flow</div> </div> </div> </div> <div class="sect1"> <h2 id="_2_the_problem_a_composite_build_and_two_separate_worlds">2. The Problem: A Composite Build and Two Separate Worlds</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our project structure is a<strong>composite build</strong>. The main project (<code>thymeleaf.cheroliv.com</code>) includes the plugin project (<code>site-baker</code>) via the`includeBuild("site-baker")`command in the`settings.gradle.kts`file.</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. Composite build structure</div> </div> <div class="paragraph"> <p>The problem is that, by default, an included build is a<strong>separate world</strong>. It has its own configuration, its own lifecycle, and it does not see the`libs.versions.toml`file of the main build. Our`plugin/build.gradle.kts`was trying to use`libs.plugins.kotlin.jvm`, but the`libs`object was not generated from the correct TOML file, causing build errors.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_the_solution_sharing_dependency_resolution">3. The Solution: Sharing Dependency Resolution</h2> <div class="sectionbody"> <div class="paragraph"> <p>After several searches, the solution turned out to be a Gradle feature designed precisely for this case:`dependencyResolutionManagement`.</p> </div> <div class="paragraph"> <p>In the`settings.gradle.kts` du <strong>included build</strong>file (<code>site-baker/settings.gradle.kts</code>), we can tell Gradle where to find the version catalog to use.</p> </div> <div class="paragraph"> <p>Here is the configuration we added to`site-baker/settings.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// site-baker/settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { gradlePluginPortal() mavenCentral() } versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } } rootProject.name = "site-baker" include("plugin")</code></pre> </div> </div> <div class="paragraph"> <p>Let’s analyze the crucial part:</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>: We declare a version catalog that will be accessible via the`libs`alias.</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))</code>: This is the magic. We tell Gradle that the source of this catalog is the TOML file located in the`gradle` du <strong>parent project</strong>directory (<code>../</code>).</p> </li> </ul> </div> <div class="paragraph"> <p>With this configuration, the`site-baker`build now knows that it must use the version catalog of the main project. The`libs`object is generated correctly, and dependencies are resolved as expected.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_conclusion_the_power_of_well_managed_composite_builds">4. Conclusion: The Power of Well-Managed Composite Builds</h2> <div class="sectionbody"> <div class="paragraph"> <p>This experience was rich in lessons. The version catalog is a fantastic tool for maintainability, but its behavior in composite build scenarios is not always intuitive.</p> </div> <div class="paragraph"> <p>The key is to remember that an included build remains an independent build. To share configurations like the version catalog, you must use the explicit mechanisms provided by Gradle, such as the`dependencyResolutionManagement`block in`settings.gradle.kts`.</p> </div> <div class="paragraph"> <p>By resolving this problem, we not only made our build cleaner, but we also strengthened the consistency of our project by ensuring that the plugin and the main project share a single source of truth for their dependencies.</p> </div> <div class="paragraph"> <p>In the next article, we will continue to enrich our plugin by adding more complex tasks, now that our dependency management is solid and centralized.</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_the_symptom_ghost_builds">The Symptom: Ghost Builds</a></li> <li><a href="#_the_investigation_what_is_the_configuration_cache">The Investigation: What is the Configuration Cache?</a></li> <li><a href="#_the_cause_of_the_problem_a_non_compliant_plugin">The Cause of the Problem: A Non-Compliant Plugin</a></li> <li><a href="#_the_temporary_solution_disabling_the_cache">The Temporary Solution: Disabling the Cache</a></li> <li><a href="#_the_real_solution_making_the_plugin_compatible">The Real Solution: Making the Plugin Compatible</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Target audience: Gradle developers who have already encountered "magic" or unexpected build behaviors.</div> <p>In our adventure of creating the plugin`site-baker`, we followed a rigorous TDD approach. Every feature was tested, validated, and we moved forward with confidence. And then, one day, the unexpected happened. Builds began to behave erratically. Changes in the plugin logic or in configuration files seemed to be ignored, and our functional tests, once reliable, were failing for no apparent reason.</p> </div> <div class="paragraph"> <p>This kind of problem can be incredibly frustrating. It calls into question the reliability of the tool and the validity of our code. After an intense debugging session, the culprit was identified: the<strong>Gradle configuration cache</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_symptom_ghost_builds">The Symptom: Ghost Builds</h2> <div class="sectionbody"> <div class="paragraph"> <p>The problem manifested in several ways:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>I would modify a string in a task`println`, but the old string continued to appear during execution.</p> </li> <li> <p>I would change a value in my`managed-jbake-context.yml`file, but the plugin acted as if the file had not been modified.</p> </li> <li> <p>Functional tests, which create test projects on the fly, failed because the plugin did not seem to detect the freshly created configuration files.</p> </li> </ol> </div> <div class="paragraph"> <p>Everything happened as if Gradle were executing a "ghost version" of our build, ignoring our most recent changes.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_investigation_what_is_the_configuration_cache">The Investigation: What is the Configuration Cache?</h2> <div class="sectionbody"> <div class="paragraph"> <p>The configuration cache is a relatively modern and extremely powerful Gradle feature, enabled by default in newer versions. Its goal is to make builds faster.</p> </div> <div class="olist arabic"> <div class="title">The principle is simple:</div> <ol class="arabic"> <li> <p>During the first execution, Gradle runs the<strong>Configuration</strong>phase (reading`build.gradle.kts`, creating tasks, resolving dependencies) and builds a task graph.</p> </li> <li> <p>At the end of this phase, Gradle<strong>serializes this task graph</strong>and caches it.</p> </li> <li> <p>During subsequent executions, if nothing has changed (build scripts,<code>gradle.properties</code>, etc.), Gradle<strong>completely skips the configuration phase</strong>and reuses the cached task graph.</p> </li> </ol> </div> <div class="paragraph"> <p>The time gain is spectacular on large projects. However, this performance comes at a price: it imposes strict rules on how plugins must be written.</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. The configuration cache lifecycle</div> </div> </div> </div> <div class="sect1"> <h2 id="_the_cause_of_the_problem_a_non_compliant_plugin">The Cause of the Problem: A Non-Compliant Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our plugin`site-baker`was unwittingly violating several configuration cache rules. For a task graph to be serializable, tasks must not contain references to complex objects like the`Project`object or read files arbitrarily during the execution phase.</p> </div> <div class="paragraph"> <p>Our main error was reading the content of the YAML file directly inside the task’s execution logic, using a reference to the path stored in our extension. This approach is incompatible with the cache because Gradle cannot know if the file content has changed if this read is not modeled as a<strong>task input</strong>(Task Input).</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_temporary_solution_disabling_the_cache">The Temporary Solution: Disabling the Cache</h2> <div class="sectionbody"> <div class="paragraph"> <p>To unblock us and regain predictable build behavior, the fastest solution was to disable the configuration cache. Simply add the following line to the`gradle.properties`file of the project using the plugin (or in our case, the test project`site-baker`).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># site-baker/gradle.properties org.gradle.configuration-cache=false</code></pre> </div> </div> <div class="paragraph"> <p>Instantly, the builds returned to their normal behavior. Each execution restarted the configuration phase and our changes were taken into account.</p> </div> <div class="paragraph"> <p>However, this is a workaround, not a sustainable solution. It sacrifices performance and does not solve the underlying problem of our plugin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_real_solution_making_the_plugin_compatible">The Real Solution: Making the Plugin Compatible</h2> <div class="sectionbody"> <div class="paragraph"> <p>For a plugin to be a good citizen of the modern Gradle ecosystem, it must be compatible with the configuration cache. This involves rethinking how data flows into our tasks.</p> </div> <div class="paragraph"> <p>The key is to use Gradle’s<strong>Provider APIs</strong>. Instead of passing direct values (such as a`String` ou un <code>File</code>) to our tasks, we must pass`Property<T>`or`Provider<T>`.</p> </div> <div class="olist arabic"> <div class="title">Here is the refactoring plan:</div> <ol class="arabic"> <li> <p><strong>Declare task inputs:</strong>The task that parses the YAML file must declare this file as an input. For this, we use the`@InputFile`annotation.</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] ---- @get:InputFile abstract val configFile: RegularFileProperty ----</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Use <code>Property</code> and <code>Provider</code>:</strong>The value of`configFile`will be connected to the`configPath`property of our DSL extension. Gradle is thus able to track the provenance of the data.</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] ---- // In the plugin tasks.register<MyTask>("myTask") { configFile.set(extension.configPath.flatMap { project.layout.projectDirectory.file(it) }) } ----</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Read the content at the right time:</strong>The file reading must take place inside the task action (<code>@TaskAction</code>), using the`Provider`of the input.</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] ---- @TaskAction fun execute() { val content = configFile.get().asFile.readText() // …​ parse the content } ----</p> </div> <div class="paragraph"> <p>By following this model, Gradle understands that if the content of`configFile`changes, the configuration cache is invalid and the configuration phase must be re-executed. Furthermore, it knows that the task output depends on the content of this file, which also allows for the optimization of the execution cache (<code>UP-TO-DATE</code>).</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>This debugging adventure was a valuable lesson. The "magic" behavior of the configuration cache forced us to better understand the Gradle lifecycle and the principles of declarative and lazy programming (<code>lazy</code>).</p> </div> <div class="paragraph"> <p>Disabling the configuration cache is a useful diagnostic tool, but the real solution is to design robust and modern plugins. By correctly modeling our task inputs and outputs with the`Provider`APIs, we are not just fixing a bug; we are improving the performance, reliability, and maintainability of our plugin.</p> </div> <div class="paragraph"> <p>In the next article, we will put this refactoring into practice to make our YAML parsing task fully compatible with the configuration cache.</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_1_the_context_our_site_baker_plugin">1. The Context: Our <code>site-baker</code> Plugin</a></li> <li><a href="#_2_modeling_the_configuration_in_kotlin">2. Modeling the Configuration in Kotlin</a></li> <li><a href="#_3_integrating_jackson_into_build_gradle_kts">3. Integrating Jackson into <code>build.gradle.kts</code></a></li> <li><a href="#_4_the_tdd_approach_testing_yaml_parsing">4. The TDD Approach: Testing YAML Parsing</a> <ul class="sectlevel2"> <li><a href="#_4_1_unit_test_mapping_yaml_to_a_kotlin_object">4.1. Unit Test: Mapping YAML to a Kotlin Object</a></li> <li><a href="#_4_2_functional_test_validating_configuration_file_reading">4.2. Functional Test: Validating Configuration File Reading</a></li> </ul> </li> <li><a href="#_5_visualizing_the_parsing_flow">5. Visualizing the Parsing Flow</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Target audience: Intermediate Gradle developers wishing to manage complex configurations.</div> <p>In Gradle plugin development, managing complex configurations is a common task. Rather than overloading the DSL with hundreds of properties, it is often cleaner and more maintainable to define the configuration in an external file, such as YAML. This article guides you through the integration of the powerful Jackson library to parse YAML files into Kotlin objects, adopting a rigorous TDD approach to ensure the robustness of our plugin.<code>site-baker</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_the_context_our_site_baker_plugin">1. The Context: Our <code>site-baker</code> Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our plugin`site-baker`is designed to automate the generation and deployment of a static site. It needs to read a YAML configuration file (<code>managed-jbake-context.yml</code>) to obtain information such as source paths, deployment destinations, and Git identifiers.</p> </div> <div class="paragraph"> <p>The YAML configuration we want to parse looks like this:</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_modeling_the_configuration_in_kotlin">2. Modeling the Configuration in Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Before parsing, we must define the structure of our data in Kotlin. Jackson will use these classes to automatically map the YAML content.</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>The function`parseSiteConfiguration`is our entry point for deserialization. It uses`ObjectMapper`from Jackson, configured with`YAMLFactory`for the YAML format and`registerKotlinModule()`for support of Kotlin specifics (such as property default values).</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_integrating_jackson_into_build_gradle_kts">3. Integrating Jackson into <code>build.gradle.kts</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>To use Jackson, we must add the necessary dependencies in the`build.gradle.kts`of our`plugin`module:</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>We use`jackson-module-kotlin`for Kotlin support and`jackson-dataformat-yaml`for managing the YAML format.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_the_tdd_approach_testing_yaml_parsing">4. The TDD Approach: Testing YAML Parsing</h2> <div class="sectionbody"> <div class="paragraph"> <p>Now, let’s apply TDD to validate our parsing logic.</p> </div> <div class="sect2"> <h3 id="_4_1_unit_test_mapping_yaml_to_a_kotlin_object">4.1. Unit Test: Mapping YAML to a Kotlin Object</h3> <div class="paragraph"> <p>We start with a unit test in`SiteBakerPluginTest.kt`to verify that the function`parseSiteConfiguration`can correctly transform a YAML string into a`SiteConfiguration`object.</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>This test reads the content of the`managed-jbake-context.yml`file (which must exist for the test to be valid) and performs assertions on the resulting`SiteConfiguration`object. It validates that the key YAML values are correctly mapped.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_functional_test_validating_configuration_file_reading">4.2. Functional Test: Validating Configuration File Reading</h3> <div class="paragraph"> <p>To ensure that the plugin can read the configuration file via its DSL and that parsing works in a real Gradle environment, we add a functional test in`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="paragraph"> <p>This test is crucial because it simulates the execution of the plugin in a real project. It must be<strong>hermetic</strong>, meaning it must create the`managed-jbake-context.yml`file itself with controlled content, to guarantee the reproducibility and isolation of the test.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt @Test fun `config file contains good data`(){ val configContent = configFile.readText(UTF_8) // Vérifications comme dans vos commentaires assertTrue(configContent.contains("bake")) assertTrue(configContent.contains("pushPage")) assertTrue(configContent.contains("repository")) }</code></pre> </div> </div> <div class="paragraph"> <p>This functional test verifies that the configuration file copied into the test temporary directory contains the expected data. Although this test does not directly parse the YAML into a Kotlin object, it validates the presence of the file and its content, which is an essential prerequisite for parsing by the plugin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_visualizing_the_parsing_flow">5. Visualizing the Parsing Flow</h2> <div class="sectionbody"> <div class="paragraph"> <p>The following diagram illustrates the data flow and interactions during the parsing of the YAML configuration:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-0994e4ea85b7366b45651fc9303bc947.png" alt="Diagram" width="1523" height="472"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>By following a TDD approach, we have successfully integrated the Jackson library to parse YAML configuration files into Kotlin objects within our Gradle plugin. This method allowed us to:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Clearly model</strong>our configuration with Kotlin data classes.</p> </li> <li> <p><strong>Validate the parsing logic</strong>with targeted unit tests.</p> </li> <li> <p><strong>Ensure integration</strong>in a real Gradle environment through hermetic functional tests.</p> </li> </ul> </div> <div class="paragraph"> <p>This solid foundation gives us great confidence in extending our plugin with features that rely on this configuration, while ensuring the maintainability and robustness of the code. YAML parsing is now a reliable and tested feature of our`site-baker`plugin.</p> </div> </div> </div> https://cheroliv.com/en/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="#_1_project_initialization">1. Project Initialization</a></li> <li><a href="#_2_our_first_tdd_cycle_registering_a_task">2. Our First TDD Cycle: Registering a Task</a> <ul class="sectlevel2"> <li><a href="#_2_1_test_first_the_failing_test">2.1. Test First (The Failing Test)</a></li> <li><a href="#_2_2_code_next_making_the_test_pass">2.2. Code Next (Making the Test Pass)</a></li> </ul> </li> <li><a href="#_3_second_tdd_cycle_adding_a_dsl_extension">3. Second TDD Cycle: Adding a DSL Extension</a> <ul class="sectlevel2"> <li><a href="#_3_1_test_first">3.1. Test First</a></li> <li><a href="#_3_2_code_next">3.2. Code Next</a></li> </ul> </li> <li><a href="#_4_functional_test_validating_integration">4. Functional Test: Validating Integration</a> <ul class="sectlevel2"> <li><a href="#_4_1_integration_test_creating_a_controlled_environment">4.1. Integration Test: Creating a Controlled Environment</a></li> <li><a href="#_4_2_finalizing_the_logic">4.2. Finalizing the Logic</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>In this article, we will explore how to set up a solid development base for a Gradle plugin using a Test-Driven Development (TDD) approach. This method ensures that our code is robust, maintainable, and precisely meets the requirements from the start.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_project_initialization">1. Project Initialization</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle greatly facilitates the creation of a new plugin thanks to the command`gradle init`. By choosing to create a "Gradle Plugin" with Kotlin, we get a ready-to-use project structure, including two crucial types of tests:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Unit Tests:</strong>Located in`src/test`, they allow for the validation of isolated components of our plugin, such as the internal logic of a task or the configuration of an extension. They are fast and do not require a full Gradle execution.</p> </li> <li> <p><strong>Functional Tests:</strong>Located in`src/functionalTest`, they use`GradleRunner`to execute a complete Gradle build in a temporary test project. This allows us to verify the actual behavior of the plugin in a controlled environment.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_2_our_first_tdd_cycle_registering_a_task">2. Our First TDD Cycle: Registering a Task</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our first requirement is simple: the plugin must register a task named`printSiteConfig`.</p> </div> <div class="sect2"> <h3 id="_2_1_test_first_the_failing_test">2.1. Test First (The Failing Test)</h3> <div class="paragraph"> <p>Following TDD, we first write a test that verifies the existence of this task. In`SiteBakerPluginTest.kt`(our unit test file), we add:</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>This test fails, as we have not yet written any code in our plugin.</p> </div> </div> <div class="sect2"> <h3 id="_2_2_code_next_making_the_test_pass">2.2. Code Next (Making the Test Pass)</h3> <div class="paragraph"> <p>Now, we write the minimum amount of code necessary in`SiteBakerPlugin.kt`so that the test passes:</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>We run the tests again, and they pass. Our first feature is validated.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_second_tdd_cycle_adding_a_dsl_extension">3. Second TDD Cycle: Adding a DSL Extension</h2> <div class="sectionbody"> <div class="paragraph"> <p>The next requirement is to allow users to configure our plugin via a DSL block in their`build.gradle.kts`. We want a`site { …​ }`block where a configuration path can be specified.</p> </div> <div class="sect2"> <h3 id="_3_1_test_first">3.1. Test First</h3> <div class="paragraph"> <p>We add a test to verify that the`site`extension is correctly registered and that a value can be assigned to it.</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>This test fails because neither the`SiteExtension`class nor the extension registration exists.</p> </div> </div> <div class="sect2"> <h3 id="_3_2_code_next">3.2. Code Next</h3> <div class="paragraph"> <p>We create the`SiteBakerExtension.kt`class and update`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>The tests pass again.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_functional_test_validating_integration">4. Functional Test: Validating Integration</h2> <div class="sectionbody"> <div class="paragraph"> <p>Now that the units are tested, we must ensure that everything works together in a real build. This is the role of the functional test in`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="sect2"> <h3 id="_4_1_integration_test_creating_a_controlled_environment">4.1. Integration Test: Creating a Controlled Environment</h3> <div class="paragraph"> <p>This test will simulate a real project using our plugin. To be reliable, it must be<strong>hermetic</strong>, meaning it must not depend on existing files on the system. It must create all the conditions necessary for its execution itself.</p> </div> <div class="paragraph"> <p>The test will therefore:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Create a`build.gradle.kts`test project that uses our plugin and its DSL.</p> </li> <li> <p><strong>Create the configuration file</strong>(<code>managed-jbake-context.yml</code>) that the plugin is supposed to read. This is a crucial step for the robustness of the test.</p> </li> <li> <p>Execute the`printSiteConfig`task via`GradleRunner`.</p> </li> <li> <p>Verify that the build output is correct.</p> </li> </ol> </div> <div class="paragraph"> <p>By copying or creating this configuration file at each execution, we ensure that the test is<strong>reproducible</strong>and does not depend on an external state. This secures our tests against regressions that could be linked to file reading.</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>This test will fail as long as the`printSiteConfig`task does not actually use the extension value.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_finalizing_the_logic">4.2. Finalizing the Logic</h3> <div class="paragraph"> <p>We update the task in`SiteBakerPlugin.kt`so that it displays the configured value:</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>All tests, unit and functional, now pass.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>By following a TDD approach, we have built a plugin incrementally and securely. Each small feature is immediately validated by a test, from fast unit tests to functional tests that validate the complete integration.</p> </div> <div class="paragraph"> <p>By taking care to make our functional tests<strong>hermetic</strong>— notably by programmatically creating the necessary configuration files — we build an extremely robust safety net. This rigor effectively protects us against regressions and gives us great confidence to add more complex features later, such as parsing the YAML configuration file.</p> </div> <div class="paragraph"> <p>This base of solid tests is the most valuable asset for the future maintenance and evolution of the plugin.</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_step_1_launch_the_project_assistant">Step 1: Launch the project assistant</a></li> <li><a href="#_step_2_understanding_the_generated_structure">Step 2: Understanding the generated structure</a> <ul class="sectlevel2"> <li><a href="#_key_files_and_folders">Key files and folders</a></li> </ul> </li> <li><a href="#_step_3_building_and_testing_the_plugin">Step 3: Building and testing the plugin</a> <ul class="sectlevel2"> <li><a href="#_basic_tasks">Basic tasks</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Target audience: Beginner to intermediate developer with Gradle.</div> <p>Starting a new Gradle plugin project can seem intimidating. Fortunately, Gradle provides a powerful interactive assistant, the`init`task, which generates a complete, clean, and ready-to-use project structure. This guide will show you how to use this tool to create a healthy plugin base, explain its structure, and show you how to run the first build tasks.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_1_launch_the_project_assistant">Step 1: Launch the project assistant</h2> <div class="sectionbody"> <div class="paragraph"> <p>The`gradle init`command is the starting point. It launches a command-line assistant that asks you a series of questions to configure the project.</p> </div> <div class="paragraph"> <p>Open your terminal in an empty folder and run:</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>The assistant will guide you. Here are the choices to make for a Gradle plugin written in Kotlin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Select type of project to generate:</strong>Choose`Gradle plugin`.</p> </li> <li> <p><strong>Select implementation language:</strong>Choose`Kotlin`.</p> </li> <li> <p><strong>Select build script DSL:</strong>Choose`Kotlin`.</p> </li> <li> <p><strong>Project name:</strong>Enter a name for your project (e.g.,<code>site-baker</code>).</p> </li> <li> <p><strong>Plugin id:</strong>Give a unique identifier to your plugin (e.g.,<code>com.cheroliv.site-baker</code>).</p> </li> <li> <p><strong>Plugin class:</strong>Specify the name of the implementation class (e.g.,<code>com.cheroliv.SiteBakerPlugin</code>).</p> </li> </ol> </div> <div class="paragraph"> <p>Once finished, Gradle generates a complete file tree.</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. Initialization process diagram</div> </div> </div> </div> <div class="sect1"> <h2 id="_step_2_understanding_the_generated_structure">Step 2: Understanding the generated structure</h2> <div class="sectionbody"> <div class="paragraph"> <p>The assistant creates a multi-module project structure, separating the root project from the plugin source code itself.</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="_key_files_and_folders">Key files and folders</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts</code>: This file at the root defines the modules included in the build. Here, it includes the`plugin`sub-project.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] ---- rootProject.name = "site-baker" include("plugin") ----</p> </div> <div class="ulist"> <ul> <li> <p><code>plugin/build.gradle.kts</code>: This is the heart of your plugin configuration. It applies the`java-gradle-plugin`plugin, declares dependencies, and configures the plugin metadata.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] ---- plugins { <code>java-gradle-plugin</code> alias(libs.plugins.kotlin.jvm) }</p> </div> <div class="paragraph"> <p>gradlePlugin { val siteBaker by plugins.creating { id = "com.cheroliv.site-baker" implementationClass = "com.cheroliv.SiteBakerPlugin" } } ----</p> </div> <div class="ulist"> <ul> <li> <p><code>src/main/</code>: Contains the source code of your plugin.</p> </li> <li> <p><code>src/test/</code>: Contains unit tests. They run quickly and in isolation.</p> </li> <li> <p><code>src/functionalTest/</code>: Contains functional tests. These tests use`GradleRunner`to execute a full version of Gradle on a test project, thus simulating real-world usage of your plugin.</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_step_3_building_and_testing_the_plugin">Step 3: Building and testing the plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>The generated project includes the<strong>Gradle Wrapper</strong>(<code>gradlew</code>). This is the recommended way to run Gradle, as it ensures that all developers use the same version, ensuring reproducible builds.</p> </div> <div class="sect2"> <h3 id="_basic_tasks">Basic tasks</h3> <div class="ulist"> <ul> <li> <p><strong>Build the project:</strong></p> </li> </ul> </div> <div class="paragraph"> <p>This command compiles your code, runs all tests (unit and functional), and assembles your plugin’s JAR. [source,bash] ---- ./gradlew build ----</p> </div> <div class="ulist"> <ul> <li> <p><strong>Run all checks:</strong></p> </li> </ul> </div> <div class="paragraph"> <p>The`check`task is an alias that runs all verification tasks, including`test` et <code>functionalTest</code>. [source,bash] ---- ./gradlew check ----</p> </div> <div class="ulist"> <ul> <li> <p><strong>Run only unit tests:</strong></p> </li> </ul> </div> <div class="paragraph"> <p>For quick feedback during development. [source,bash] ---- ./gradlew test ----</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>The`./gradlew :test`command, which explicitly targets the root project, will fail because the latter contains no tests. On the other hand: * `./gradlew test`works because Gradle runs the`test`task on all sub-projects that possess it (here, the`plugin`module). * `./gradlew :plugin:test`is the most explicit command to run the tests of the`plugin`module only.</p> </div> </td> </tr> </table> </div> <div class="ulist"> <ul> <li> <p><strong>Run only functional tests:</strong></p> </li> </ul> </div> <div class="paragraph"> <p>Slower, they are useful for validating overall behavior. [source,bash] ---- ./gradlew functionalTest ----</p> </div> <div class="paragraph"> <p>The test results are generated in the`plugin/build/reports/tests/`folder. You can open the`index.html`file in your browser for a detailed report.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>In a few minutes,`gradle init`has provided you with a solid, modern, and complete project base for your plugin development. You have a clear structure, preconfigured unit and functional tests, and a reproducible build system thanks to the Gradle Wrapper.</p> </div> <div class="paragraph"> <p>You are now ready to open the`SiteBakerPlugin.kt`file and start adding your plugin’s business logic!</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_1_the_jdk_gradles_engine">1. The JDK: Gradle’s Engine</a> <ul class="sectlevel2"> <li><a href="#_which_version_to_choose">Which version to choose?</a></li> <li><a href="#_installation_via_sdkman_recommended">Installation via SDKMAN! (Recommended)</a> <ul class="sectlevel3"> <li><a href="#_install_sdkman"><strong>Install SDKMAN!</strong></a></li> <li><a href="#_install_a_jdk_version"><strong>Install a JDK version</strong></a></li> <li><a href="#_verify_the_installation"><strong>Verify the installation</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_2_the_ide_intellij_idea">2. The IDE: IntelliJ IDEA</a></li> <li><a href="#_3_gradle_the_build_tool">3. Gradle: The Build Tool</a> <ul class="sectlevel2"> <li><a href="#_installation_via_sdkman">Installation via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_install_gradle"><strong>Install Gradle</strong></a></li> <li><a href="#_verify_the_installation_2"><strong>Verify the installation</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_the_static_site_generator">4. JBake: The Static Site Generator</a> <ul class="sectlevel2"> <li><a href="#_installation_via_sdkman_2">Installation via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_install_jbake"><strong>Install JBake</strong></a></li> <li><a href="#_verify_the_installation_3"><strong>Verify the installation</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_5_the_gradle_wrapper_the_absolute_best_practice">5. The Gradle Wrapper: The Absolute Best Practice</a></li> <li><a href="#_6_docker_and_portainer_for_reproducible_builds_optional">6. Docker and Portainer: For Reproducible Builds (Optional)</a> <ul class="sectlevel2"> <li><a href="#_installing_docker_engine">Installing Docker Engine</a> <ul class="sectlevel3"> <li><a href="#_install_docker_via_the_official_script"><strong>Install Docker via the official script:</strong></a></li> <li><a href="#_manage_docker_without_sudo_recommended"><strong>Manage Docker without <code>sudo</code> (recommended):</strong></a></li> </ul> </li> <li><a href="#_manage_docker_with_portainer_gui">Manage Docker with Portainer (GUI)</a> <ul class="sectlevel3"> <li><a href="#_create_a_volume_for_portainer_data"><strong>Create a volume for Portainer data:</strong></a></li> <li><a href="#_launch_the_portainer_container"><strong>Launch the Portainer container:</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Target audience: Developers wishing to start creating Gradle plugins.</div> <p>To develop Gradle plugins effectively, a well-configured development environment is indispensable. A good setup will save you time, reduce frustrations, and ensure the consistency of your builds.</p> </div> <div class="olist arabic"> <div class="title">This guide focuses on four essential pillars:</div> <ol class="arabic"> <li> <p>Le <strong>JDK</strong>(Java Development Kit), because Gradle and JBake run on the JVM.</p> </li> <li> <p>Un <strong>IDE</strong>modern (IntelliJ IDEA) with good support for Kotlin and Gradle.</p> </li> <li> <p><strong>Gradle</strong>itself, to initialize projects.</p> </li> <li> <p><strong>JBake</strong>, the engine of our static site.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/gradle-env.svg" alt="gradle env" width="492" height="213"> </div> <div class="title">Figure 1. Development environment components</div> </div> </div> </div> <div class="sect1"> <h2 id="_1_the_jdk_gradles_engine">1. The JDK: Gradle’s Engine</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle is an application that runs on the Java Virtual Machine (JVM). Consequently, installing a JDK is an absolute prerequisite.</p> </div> <div class="sect2"> <h3 id="_which_version_to_choose">Which version to choose?</h3> <div class="paragraph"> <p>It is recommended to use an LTS (Long-Term Support) version of Java. Currently,<strong>JDK 17</strong> ou <strong>JDK 21</strong>are excellent choices.</p> </div> </div> <div class="sect2"> <h3 id="_installation_via_sdkman_recommended">Installation via SDKMAN! (Recommended)</h3> <div class="paragraph"> <p>SDKMAN! is a great tool for managing versions of many SDKs, including Java and Gradle.</p> </div> <div class="sect3"> <h4 id="_install_sdkman"><strong>Install 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="_install_a_jdk_version"><strong>Install a JDK version</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="_verify_the_installation"><strong>Verify the installation</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">java -version</code></pre> </div> </div> <div class="paragraph"> <p>You should see the version you just installed displayed.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_the_ide_intellij_idea">2. The IDE: IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>For the development of Gradle plugins with the Kotlin DSL,<strong>IntelliJ IDEA</strong>is the tool of choice. Its integration with Gradle and Kotlin is unmatched.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Community Edition:</strong>Free and largely sufficient to get started.</p> </li> <li> <p><strong>Ultimate Edition:</strong>Paid, it offers advanced features for web and database development.</p> </li> </ul> </div> <div class="paragraph"> <p>Download the version that suits you from the JetBrains site: <a href="https://www.jetbrains.com/idea/download/" class="bare">https://www.jetbrains.com/idea/download/</a></p> </div> <div class="paragraph"> <p>The IDE will automatically detect your`build.gradle.kts` et `settings.gradle.kts`files, offering you powerful autocompletion, code navigation, and built-in debugging tools.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle_the_build_tool">3. Gradle: The Build Tool</h2> <div class="sectionbody"> <div class="paragraph"> <p>Even though each project will use its own version of Gradle via the Gradle Wrapper, it is useful to have a global installation of Gradle for tasks such as initializing new projects (<code>gradle init</code>).</p> </div> <div class="sect2"> <h3 id="_installation_via_sdkman">Installation via SDKMAN!</h3> <div class="paragraph"> <p>Just like for the JDK, SDKMAN! simplifies the installation of Gradle.</p> </div> <div class="sect3"> <h4 id="_install_gradle"><strong>Install Gradle</strong></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="_verify_the_installation_2"><strong>Verify the installation</strong></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>This command will display the versions of Gradle, Kotlin, Groovy, and the JDK being used.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_the_static_site_generator">4. JBake: The Static Site Generator</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake is the tool we will use to transform our source files (like this one) into a static website. Having a local installation is practical for previewing changes.</p> </div> <div class="sect2"> <h3 id="_installation_via_sdkman_2">Installation via SDKMAN!</h3> <div class="paragraph"> <p>As with the other tools, SDKMAN! is the simplest method.</p> </div> <div class="sect3"> <h4 id="_install_jbake"><strong>Install JBake</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install jbake</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verify_the_installation_3"><strong>Verify the installation</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>This command will display the JBake version and the Java environment information it uses.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_the_gradle_wrapper_the_absolute_best_practice">5. The Gradle Wrapper: The Absolute Best Practice</h2> <div class="sectionbody"> <div class="paragraph"> <p>Once your project is created (which we will see in the next article), you should no longer use the global`gradle`command. Instead, you will use the<strong>Gradle Wrapper</strong>(<code>./gradlew</code>), a script included in your project.</p> </div> <div class="paragraph"> <p>Why?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Reproducibility:</strong>The Wrapper ensures that every person working on the project (including your CI/CD server) uses exactly the<strong>same version of Gradle</strong>, thus eliminating build errors due to different environments.</p> </li> <li> <p><strong>Simplicity:</strong>No need to install Gradle manually to contribute to a project.</p> </li> </ul> </div> <div class="paragraph"> <p>Simply clone the repository and run`./gradlew`.</p> </div> <div class="paragraph"> <p>A typical command will look like this:</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_and_portainer_for_reproducible_builds_optional">6. Docker and Portainer: For Reproducible Builds (Optional)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Although not strictly necessary for writing a plugin, Docker and Portainer are modern DevOps tools that greatly facilitate the creation of reproducible builds and the management of your environment.</p> </div> <div class="sect2"> <h3 id="_installing_docker_engine">Installing Docker Engine</h3> <div class="paragraph"> <p>Docker allows you to package your application and its dependencies into a container.</p> </div> <div class="sect3"> <h4 id="_install_docker_via_the_official_script"><strong>Install Docker via the official script:</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="_manage_docker_without_sudo_recommended"><strong>Manage Docker without <code>sudo</code> (recommended):</strong></h4> <div class="paragraph"> <p>Add your user to the`docker`group.</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="_manage_docker_with_portainer_gui">Manage Docker with Portainer (GUI)</h3> <div class="paragraph"> <p>Portainer is a lightweight web interface for managing your Docker containers.</p> </div> <div class="sect3"> <h4 id="_create_a_volume_for_portainer_data"><strong>Create a volume for Portainer data:</strong></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="_launch_the_portainer_container"><strong>Launch the Portainer container:</strong></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>You can now access the Portainer interface on`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Your environment is now ready! You have a JDK, the most suitable IDE, Gradle, and JBake. With the addition of Docker, you are also set to create containerized and reproducible builds. This solid foundation will allow you to focus on the essentials: developing powerful and useful plugins.</p> </div> <div class="paragraph"> <p>In the next article, we will use the`gradle init`command to generate the structure of our first plugin project.</p> </div> </div> </div> https://cheroliv.com/en/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="#_integration_with_poetry">Integration with Poetry</a> <ul class="sectlevel2"> <li><a href="#_poetry_installation">Poetry Installation</a></li> <li><a href="#_project_initialization">Project Initialization</a></li> <li><a href="#_adding_and_installing_dependencies">Adding and installing dependencies</a></li> <li><a href="#_publishing_with_poetry">Publishing with Poetry</a></li> </ul> </li> <li><a href="#_reproducible_builds_with_docker">Reproducible Builds with Docker</a> <ul class="sectlevel2"> <li><a href="#_dockerfile_example">Dockerfile Example</a></li> <li><a href="#_integration_into_github_actions">Integration into GitHub Actions</a></li> </ul> </li> <li><a href="#_conditional_publishing">Conditional Publishing</a></li> <li><a href="#_dependency_automation_with_renovate_and_dependabot">Dependency Automation with Renovate and Dependabot</a> <ul class="sectlevel2"> <li><a href="#_dependabot">Dependabot</a></li> <li><a href="#_renovate">Renovate</a></li> </ul> </li> <li><a href="#_plantuml_diagrams">PlantUML Diagrams</a> <ul class="sectlevel2"> <li><a href="#_use_case_advanced_cicd">Use Case – Advanced CI/CD</a></li> <li><a href="#_sequence_conditional_publishing">Sequence – Conditional Publishing</a></li> <li><a href="#_states_cicd_pipeline">States – CI/CD Pipeline</a></li> <li><a href="#_deployment_cicd_architecture">Deployment – CI/CD Architecture</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>In the first two parts of this series, we have: - Established a functional CI/CD pipeline for a Python application with GitHub Actions and PyPI. - Industrialized this pipeline with multi-version tests, progressive publishing via Test PyPI, and quality and security tools.</p> </div> <div class="paragraph"> <p>In this third part, we are going to go<strong>beyond simple publishing on PyPI</strong>to build a complete, robust, and professional CI/CD chain with: - <strong>Poetry</strong>for modern packaging and optimized dependency management. - <strong>Docker</strong>to create reproducible and multi-platform builds. - <strong>Conditional Publishing</strong>to manage scenarios such as release candidates. - <strong>Automation Tools</strong>(Renovate, Dependabot) to keep the pipeline up to date effortlessly.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integration_with_poetry">Integration with Poetry</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry replaces old packaging tools (setup.py, requirements.txt) by centralizing dependency and build management in`pyproject.toml`.</p> </div> <div class="sect2"> <h3 id="_poetry_installation">Poetry Installation</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="_project_initialization">Project Initialization</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>This generates a`pyproject.toml`file:</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="_adding_and_installing_dependencies">Adding and installing dependencies</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="_publishing_with_poetry">Publishing with Poetry</h3> <div class="paragraph"> <p>Poetry natively handles publishing:</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>This command automatically uses the information present in`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_reproducible_builds_with_docker">Reproducible Builds with Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>To ensure identical executions in development, CI/CD, and production, Docker integrates perfectly with Poetry.</p> </div> <div class="sect2"> <h3 id="_dockerfile_example">Dockerfile Example</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>This guarantees: - A frozen Python environment. - Locked dependencies via`poetry.lock`. - An image executable on any system supporting Docker.</p> </div> </div> <div class="sect2"> <h3 id="_integration_into_github_actions">Integration into 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="_conditional_publishing">Conditional Publishing</h2> <div class="sectionbody"> <div class="paragraph"> <p>In a professional pipeline, you must be able to publish only in certain cases: - Release candidates to Test PyPI. - Stable versions to PyPI. - Docker builds triggered only for`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>This approach avoids accidental publications.</p> </div> </div> </div> <div class="sect1"> <h2 id="_dependency_automation_with_renovate_and_dependabot">Dependency Automation with Renovate and Dependabot</h2> <div class="sectionbody"> <div class="paragraph"> <p>To prevent your dependencies from becoming obsolete, integrate automatic update tools.</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 opens PRs every week to update Python and GitHub Actions dependencies.</p> </div> </div> <div class="sect2"> <h3 id="_renovate">Renovate</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 allows for finer control: dependency grouping, scheduling, and advanced rules.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plantuml_diagrams">PlantUML Diagrams</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_use_case_advanced_cicd">Use Case – Advanced CI/CD</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="_sequence_conditional_publishing">Sequence – Conditional Publishing</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="_states_cicd_pipeline">States – CI/CD Pipeline</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="_deployment_cicd_architecture">Deployment – CI/CD Architecture</h3> <div class="imageblock"> <div class="content"> <img src="images/deployment-cicd.svg" alt="deployment cicd" width="535" height="288"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>In this third part, we have seen how to: - Modernize Python packaging with Poetry. - Guarantee reproducible builds via Docker. - Implement conditional publishing. - Automate dependency updates.</p> </div> <div class="paragraph"> <p>You now have a<strong>complete, industrialized, and secure</strong>CI/CD pipeline, ready to evolve with your projects.</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_cicd_pipeline_architecture">CI/CD Pipeline Architecture</a></li> <li><a href="#_project_structure">Project Structure</a></li> <li><a href="#_package_configuration_with_pyproject_toml">Package Configuration with <code>pyproject.toml</code></a></li> <li><a href="#_cicd_workflow_tests_and_quality">CI/CD Workflow - Tests and Quality</a></li> <li><a href="#_release_and_deployment_workflow">Release and Deployment Workflow</a></li> <li><a href="#_architecture_diagrams">Architecture Diagrams</a> <ul class="sectlevel2"> <li><a href="#_sequence_diagram_release_process">Sequence Diagram - Release Process</a></li> <li><a href="#_state_diagram_package_lifecycle">State Diagram - Package Lifecycle</a></li> <li><a href="#_deployment_diagram_cicd_infrastructure">Deployment Diagram - CI/CD Infrastructure</a></li> </ul> </li> <li><a href="#_pipeline_objects_and_models">Pipeline Objects and Models</a> <ul class="sectlevel2"> <li><a href="#_class_diagram_cicd_models">Class Diagram - CI/CD Models</a></li> </ul> </li> <li><a href="#_secrets_configuration">Secrets Configuration</a> <ul class="sectlevel2"> <li><a href="#_github_actions_secrets">GitHub Actions Secrets</a></li> <li><a href="#_pypi_token_generation">PyPI Token Generation</a></li> </ul> </li> <li><a href="#_local_development_scripts">Local Development Scripts</a> <ul class="sectlevel2"> <li><a href="#_makefile">Makefile</a></li> <li><a href="#_versioning_script">Versioning Script</a></li> </ul> </li> <li><a href="#_best_practices_and_recommendations">Best Practices and Recommendations</a> <ul class="sectlevel2"> <li><a href="#_semantic_versioning">Semantic Versioning</a></li> <li><a href="#_branching_strategy">Branching Strategy</a></li> <li><a href="#_testing_and_coverage">Testing and Coverage</a></li> <li><a href="#_security">Security</a></li> </ul> </li> <li><a href="#_monitoring_and_observability">Monitoring and Observability</a> <ul class="sectlevel2"> <li><a href="#_pipeline_metrics">Pipeline Metrics</a></li> <li><a href="#_notifications">Notifications</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_additional_resources">Additional Resources</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objective: Transform a simple pipeline into a robust industrial pipeline, respecting modern packaging and software engineering standards.</div> <p>In the first part of this series, we built a simple but effective CI/CD pipeline to automate tests and the publication of a Python package on PyPI.</p> </div> <div class="paragraph"> <p>It is now time to professionalize this pipeline. In this second part, we will:</p> </div> <div class="ulist"> <ul> <li> <p>Migrate to the modern <code>pyproject.toml</code> standard,</p> </li> <li> <p>Add quality and security tools (Black, Mypy, Bandit, Safety),</p> </li> <li> <p>Implement multi-version tests,</p> </li> <li> <p>Integrate progressive deployment via Test PyPI,</p> </li> <li> <p>Automate versioning and improve pipeline monitoring.</p> </li> </ul> </div> <div class="paragraph"> <p>Get ready to move from a functional pipeline to a professional CI/CD infrastructure.</p> </div> <div class="paragraph"> <p>Deploying a Python application on PyPI requires a robust CI/CD pipeline that automates testing, building, and publishing packages. This article details the setup of a complete pipeline using GitHub Actions for a Python CLI application, based on the best practices of the modern Python ecosystem.</p> </div> </div> </div> <div class="sect1"> <h2 id="_cicd_pipeline_architecture">CI/CD Pipeline Architecture</h2> <div class="sectionbody"> <div class="paragraph"> <p>The pipeline we will build follows a multi-step approach:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-091564f47a4d2a33138535f3dd22ac5f.png" alt="Diagram" width="865" height="604"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_project_structure">Project Structure</h2> <div class="sectionbody"> <div class="paragraph"> <p>A Python CLI application ready for distribution must follow a standardized structure:</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="_package_configuration_with_pyproject_toml">Package Configuration with <code>pyproject.toml</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The file`pyproject.toml`is the modern standard for configuring Python packages:</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="_cicd_workflow_tests_and_quality">CI/CD Workflow - Tests and Quality</h2> <div class="sectionbody"> <div class="paragraph"> <p>The main workflow (<code>ci.yml</code>) executes tests across multiple Python versions:</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="_release_and_deployment_workflow">Release and Deployment Workflow</h2> <div class="sectionbody"> <div class="paragraph"> <p>The release workflow (<code>release.yml</code>) handles automatic publication on 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="_architecture_diagrams">Architecture Diagrams</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sequence_diagram_release_process">Sequence Diagram - Release Process</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-bd44022bf678f779601e03d0fe6fe79a.png" alt="Diagram" width="942" height="832"> </div> </div> </div> <div class="sect2"> <h3 id="_state_diagram_package_lifecycle">State Diagram - Package Lifecycle</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-256d69965bd3ae9f9ec6a94e0b8a2cb9.png" alt="Diagram" width="525" height="740"> </div> </div> </div> <div class="sect2"> <h3 id="_deployment_diagram_cicd_infrastructure">Deployment Diagram - CI/CD Infrastructure</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-c98f3aea7b4624720be032e8bf13134c.png" alt="Diagram" width="682" height="604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pipeline_objects_and_models">Pipeline Objects and Models</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_class_diagram_cicd_models">Class Diagram - CI/CD Models</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-a1f7fbde71d52336a328963ccb10d4ec.png" alt="Diagram" width="814" height="635"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_secrets_configuration">Secrets Configuration</h2> <div class="sectionbody"> <div class="paragraph"> <p>For the pipeline to work, you must configure the following secrets in GitHub:</p> </div> <div class="sect2"> <h3 id="_github_actions_secrets">GitHub Actions Secrets</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="_pypi_token_generation">PyPI Token Generation</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="_local_development_scripts">Local Development Scripts</h2> <div class="sectionbody"> <div class="paragraph"> <p>To facilitate development, create utility scripts:</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="_versioning_script">Versioning Script</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="_best_practices_and_recommendations">Best Practices and Recommendations</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_semantic_versioning">Semantic Versioning</h3> <div class="paragraph"> <p>Use semantic versioning (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>: incompatible changes</p> </li> <li> <p><code>MINOR</code>: compatible new features</p> </li> <li> <p><code>PATCH</code>: compatible bug fixes</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_branching_strategy">Branching Strategy</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="_testing_and_coverage">Testing and Coverage</h3> <div class="ulist"> <ul> <li> <p>Minimum code coverage: 85%</p> </li> <li> <p>Unit tests for business logic</p> </li> <li> <p>Integration tests for adapters</p> </li> <li> <p>End-to-end tests for CLIs</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_security">Security</h3> <div class="ulist"> <ul> <li> <p>Automatic dependency scanning (Safety)</p> </li> <li> <p>Static code analysis (Bandit)</p> </li> <li> <p>Secrets never in the code</p> </li> <li> <p>Use of specific PyPI tokens</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoring_and_observability">Monitoring and Observability</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pipeline_metrics">Pipeline Metrics</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="_notifications">Notifications</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>This complete CI/CD pipeline for Python offers:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Full Automation</strong>: from code validation to publication</p> </li> <li> <p><strong>Security</strong>: automatic scans and secure secrets management</p> </li> <li> <p><strong>Quality</strong>: multi-version tests, linting and code coverage</p> </li> <li> <p><strong>Reliability</strong>: progressive deployment via Test PyPI</p> </li> <li> <p><strong>Traceability</strong>: artifacts, reports and GitHub releases</p> </li> </ul> </div> <div class="paragraph"> <p>Adopting these practices ensures a robust and professional delivery process for your Python CLI applications, facilitating long-term maintenance and evolution of your projects.</p> </div> </div> </div> <div class="sect1"> <h2 id="_additional_resources">Additional Resources</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">GitHub Actions Documentation</a></p> </li> <li> <p><a href="https://pypi.org/help/">PyPI Help Documentation</a></p> </li> <li> <p><a href="https://semver.org/">Semantic Versioning Specification</a></p> </li> <li> <p><a href="https://keepachangelog.com/">Keep a Changelog</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_pipeline_architecture">Pipeline Architecture</a></li> <li><a href="#_continuous_integration_ci_pipeline_configuration">Continuous Integration (CI) Pipeline Configuration</a> <ul class="sectlevel2"> <li><a href="#_ci_workflow_structure">CI Workflow Structure</a></li> <li><a href="#_ci_steps_analysis">CI Steps Analysis</a> <ul class="sectlevel3"> <li><a href="#_1_triggers_on">1. Triggers (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objective: Guide the reader through the setup of a minimalist but functional CI/CD pipeline for a Python application, with automatic deployment to PyPI.</div> <p>Automating development processes has become essential in modern projects. A well-designed CI/CD pipeline not only allows for the early detection of regressions in the development cycle but also fully automates the deployment process.</p> </div> <div class="paragraph"> <p>In this article, we will explore how to set up a complete pipeline with GitHub Actions for a Python application, from continuous integration (CI) to continuous deployment (CD) on PyPI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_pipeline_architecture">Pipeline Architecture</h2> <div class="sectionbody"> <div class="paragraph"> <p>Our pipeline consists of two distinct workflows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>CI Pipeline</strong>: Executed on every push and pull request</p> </li> <li> <p><strong>CD Pipeline</strong>: Triggered only during GitHub releases</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/ci-cd-overview.svg" alt="ci cd overview" width="394" height="648"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_continuous_integration_ci_pipeline_configuration">Continuous Integration (CI) Pipeline Configuration</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ci_workflow_structure">CI Workflow Structure</h3> <div class="paragraph"> <p>The CI workflow is designed to validate every contribution to the code. Here is its complete configuration:</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="_ci_steps_analysis">CI Steps Analysis</h3> <div class="sect3"> <h4 id="_1_triggers_on">1. Triggers (<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 ---- The pipeline triggers on: - Every push to the branch`main` - Every pull request to`main` This approach ensures that the main code remains stable and that every contribution is validated before integration. ==== 2. Execution Environment ```yaml ---- runs-on: ubuntu-latest ---- Ubuntu Latest offers a good compromise between performance, cost, and compatibility for most Python projects. ==== 3. Code Checkout ```yaml ---- - name: Checkout code uses: actions/checkout@v4 ---- The action`checkout@v4`retrieves the source code from the repository. Version v4 brings performance and security improvements. ==== 4. Python Configuration ```yaml ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' ---- Using`'3.x'`allows for the automatic use of the latest stable version of Python 3, simplifying maintenance. ==== 5. Dependency Installation ```yaml ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- This step: - Updates pip to the latest version - Installs project dependencies - Adds development tools (linting and tests) ==== 6. Linting with Ruff ```yaml ---- - name: Run Linting (Ruff) run: ruff check . ---- **Ruff**is an ultra-fast Python linter written in Rust. It combines the features of several tools (Flake8, Black, isort) into a single high-performance tool. ==== 7. Running Tests ```yaml ---- - name: Run Tests (Pytest) run: pytest ---- Pytest executes the entire test suite, ensuring that changes do not introduce regressions. == Deployment (CD) Pipeline Configuration === CD Workflow Structure The CD workflow triggers only during GitHub releases and automates publication to 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/* ---- === CD Steps Analysis ==== 1. Release Trigger ```yaml ---- on: release: types: - published ---- The CD pipeline only triggers upon the publication of a GitHub release. This approach ensures precise control over deployments. ==== 2. Build Tools Installation ```yaml ---- pip install setuptools wheel twine ---- - **setuptools**: Python packaging tools - **wheel**: Modern Python distribution format - **twine**: Secure tool for uploading to PyPI ==== 3. Authentication Configuration ```yaml ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} ---- Authentication uses a PyPI API token stored as a GitHub secret, which is more secure than classic credentials. ==== 4. Build and Publication ```yaml ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: Creates a source distribution - `bdist_wheel`: Creates a wheel (binary distribution) - `twine upload`: Publishes the distributions to PyPI == Python Package Configuration === setup.py Structure For the pipeline to work, your project must include a`setup.py`file: [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", ], }, ) ---- === Key Points of setup.py 1. **Metadata**: Name, version, author, description 2. **Dependencies**: List of required packages 3. **Entry Points**: Exposed CLI commands 4. **Classifiers**: Metadata for PyPI == Securing with GitHub Secrets === PyPI Token Configuration 1. **Create an API token on PyPI**: - Log in to PyPI - Go to Account Settings > API tokens - Create a new token with the appropriate permissions 1. **Add the secret in GitHub**: - Repository Settings > Secrets and variables > Actions - Create a new secret named`PYPI_API_TOKEN` - Paste your PyPI token [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "GitHub Repository" 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 ---- == Complete Deployment Workflow === Deployment Sequence [plantuml, deployment-sequence, svg] ---- @startuml !theme plain actor Developer as dev participant "Local Git" as git participant "GitHub" as github participant "GitHub Actions" as actions participant PyPI participant "End Users" 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 ---- === Pipeline States [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 ---- == Best Practices and Optimizations === 1. Version Management Use semantic Git tags: ```bash ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 ---- === 2. Matrix Tests To test on multiple Python versions: ```yaml ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. Dependency Caching Speed up builds with caching: ```yaml ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} ---- === 4. Deployment Environments Use GitHub environments for controlled deployments: ```yaml ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == Use Case and Architecture === Use Case Diagram [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "Developer" as dev actor "GitHub Actions" as ga actor "End User" as user package "CI/CD System" { usecase "Run Linting" as lint usecase "Execute Tests" as test usecase "Build Package" as build usecase "Publish to PyPI" as publish usecase "Create Release" 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 ---- === Deployment Architecture [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "GitHub" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "CI/CD Pipeline" { [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 ---- == Monitoring and Debugging === Logs and Monitoring GitHub Actions provides detailed logs for each step. To debug: 1. **Examine the logs**of each step 2. **Enable debug**with`ACTIONS_STEP_DEBUG` 3. **Use artifacts**to save build files ```yaml ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ ---- === Notifications Add Slack or email notifications: ```yaml ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == Conclusion Setting up a robust CI/CD pipeline with GitHub Actions radically transforms the development experience. By automating linting, testing, and deployment, you: - **Reduce errors**in production - **Accelerate cycles**of development - **Improve confidence**in your releases - **Facilitate collaboration**within the team This pipeline can be adapted to different types of Python projects by adjusting the linting tools, test frameworks, or deployment destinations. The initial investment in configuring these workflows is quickly offset by the time saved and the reduction of manual errors during deployments. == Additional Resources - https://docs.github.com/en/actions[GitHub Actions Documentation] - https://packaging.python.org/[Python Packaging Guide] - https://docs.pytest.org/[Pytest Documentation] - https://docs.astral.sh/ruff/[Ruff Documentation] - https://twine.readthedocs.io/[Twine Documentation] ✅ Functional pipeline achieved! You now have a simple CI/CD pipeline that allows you to automate your tests and publish your Python package to PyPI directly from GitHub Actions. However, this pipeline remains intentionally minimalist. It does not yet cover certain aspects essential in a professional context: Multi-version Python tests, Automatic security analysis, Progressive deployment via Test PyPI, Pipeline monitoring and metrics, Versioning automation and integration of modern best practices (pyproject.toml). In the next part, we will move to the next level. You will learn how to transform this basic pipeline into a true industrial deployment chain, robust and secure, ready for production Python projects.</code></pre> </div> </div> </div> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_context_and_current_challenges">Context and Current Challenges</a> <ul class="sectlevel2"> <li><a href="#_evolution_of_musical_apis">Evolution of Musical APIs</a></li> <li><a href="#_log_driven_development_approach">Log Driven Development Approach</a></li> </ul> </li> <li><a href="#_conceptual_architecture">Conceptual Architecture</a></li> <li><a href="#_technical_stack_and_functional_paradigm">Technical Stack and Functional Paradigm</a> <ul class="sectlevel2"> <li><a href="#_technological_choices">Technological Choices</a></li> <li><a href="#_applied_functional_principles">Applied Functional Principles</a></li> </ul> </li> <li><a href="#_agile_methodology_and_backlog">Agile Methodology and Backlog</a> <ul class="sectlevel2"> <li><a href="#_main_epics">Main Epics</a> <ul class="sectlevel3"> <li><a href="#_epic_1_discord_bot_infrastructure">Epic 1: Discord Bot Infrastructure</a></li> <li><a href="#_epic_2_spotify_integration">Epic 2: Spotify Integration</a></li> <li><a href="#_epic_3_youtube_integration">Epic 3: YouTube Integration</a></li> <li><a href="#_epic_4_musical_features">Epic 4: Musical Features</a></li> </ul> </li> <li><a href="#_detailed_user_stories">Detailed User Stories</a> <ul class="sectlevel3"> <li><a href="#_us1_1_bot_initialization">US1.1: Bot Initialization</a></li> <li><a href="#_us2_1_intelligent_spotify_search">US2.1: Intelligent Spotify Search</a></li> <li><a href="#_us3_1_resilient_youtube_extraction">US3.1: Resilient YouTube Extraction</a></li> </ul> </li> </ul> </li> <li><a href="#_log_driven_development_approach_2">Log Driven Development Approach</a> <ul class="sectlevel2"> <li><a href="#_logging_strategy">Logging Strategy</a></li> <li><a href="#_log_structure">Log Structure</a></li> <li><a href="#_log_design_example">Log Design Example</a></li> </ul> </li> <li><a href="#_validation_architecture_with_pydantic">Validation Architecture with Pydantic</a> <ul class="sectlevel2"> <li><a href="#_data_models">Data Models</a></li> </ul> </li> <li><a href="#_functional_error_handling">Functional Error Handling</a> <ul class="sectlevel2"> <li><a href="#_monads_and_error_handling">Monads and Error Handling</a></li> </ul> </li> <li><a href="#_restriction_bypass_strategy">Restriction Bypass Strategy</a> <ul class="sectlevel2"> <li><a href="#_multi_source_approach">Multi-Source Approach</a></li> </ul> </li> <li><a href="#_iterative_development_plan">Iterative Development Plan</a> <ul class="sectlevel2"> <li><a href="#_sprint_planning">Sprint Planning</a></li> <li><a href="#_quality_metrics">Quality Metrics</a></li> </ul> </li> <li><a href="#_deployment_and_monitoring">Deployment and Monitoring</a> <ul class="sectlevel2"> <li><a href="#_production_architecture">Production Architecture</a></li> <li><a href="#_proactive_monitoring">Proactive Monitoring</a></li> </ul> </li> <li><a href="#_conclusion_and_perspectives">Conclusion and Perspectives</a> <ul class="sectlevel2"> <li><a href="#_next_steps">Next Steps</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduction"><a class="anchor" href="#_introduction"></a>Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>Developing a Discord bot integrating Spotify and YouTube APIs represents a modern technical challenge, particularly in the face of recent platform restrictions and evolutions. This article presents a methodological approach based on<strong>Log Driven Development</strong>(LDD), an extension of Test Driven Development, applied within a functional paradigm with Python.</p> </div> <div class="paragraph"> <p>Our objective: to create a robust, maintainable, and scalable bot, capable of navigating the current constraints of musical APIs while offering a fluid user experience on Discord.</p> </div> </div> </div> <div class="sect1"> <h2 id="_context_and_current_challenges"><a class="anchor" href="#_context_and_current_challenges"></a>Context and Current Challenges</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_evolution_of_musical_apis"><a class="anchor" href="#_evolution_of_musical_apis"></a>Evolution of Musical APIs</h3> <div class="paragraph"> <p>Musical platforms have considerably tightened their access policies:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Spotify</strong>: Restrictions on metadata access, quota limitations</p> </li> <li> <p><strong>YouTube</strong>: Reinforced anti-bot policy, complexification of authentication</p> </li> <li> <p><strong>Discord</strong>: New security and performance requirements</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_log_driven_development_approach"><a class="anchor" href="#_log_driven_development_approach"></a>Log Driven Development Approach</h3> <div class="paragraph"> <p>LDD extends TDD by placing logs at the heart of development:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Definition of logs</strong>before implementation</p> </li> <li> <p><strong>Validation through observation</strong>of expected behaviors</p> </li> <li> <p><strong>Complete traceability</strong>of data flows</p> </li> <li> <p><strong>Proactive debugging</strong>by anticipating errors</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conceptual_architecture"><a class="anchor" href="#_conceptual_architecture"></a>Conceptual Architecture</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-3f14e5db3c058a87a04a62794fbd33ec.png" alt="Diagram" width="777" height="618"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_technical_stack_and_functional_paradigm"><a class="anchor" href="#_technical_stack_and_functional_paradigm"></a>Technical Stack and Functional Paradigm</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_technological_choices"><a class="anchor" href="#_technological_choices"></a>Technological Choices</h3> <div class="paragraph"> <p>Our stack is centered around functional programming:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>Side-effect management and function composition</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>Type-safe data validation and serialization</p> </dd> <dt class="hdlist1"><strong>Asyncio</strong></dt> <dd> <p>Asynchronous programming for APIs</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>Structured logging for LDD</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_applied_functional_principles"><a class="anchor" href="#_applied_functional_principles"></a>Applied Functional Principles</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-7047ce80aa562f0267016ac6134cdcc5.png" alt="Diagram" width="701" height="554"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_agile_methodology_and_backlog"><a class="anchor" href="#_agile_methodology_and_backlog"></a>Agile Methodology and Backlog</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_main_epics"><a class="anchor" href="#_main_epics"></a>Main Epics</h3> <div class="paragraph"> <p>Our development is organized around 4 major epics:</p> </div> <div class="sect3"> <h4 id="_epic_1_discord_bot_infrastructure"><a class="anchor" href="#_epic_1_discord_bot_infrastructure"></a>Epic 1: Discord Bot Infrastructure</h4> <div class="paragraph"> <p><strong>Business value</strong>: Solid and extensible base</p> </div> <div class="paragraph"> <p><strong>Acceptance criteria</strong>: - Stable Discord connection with reconnection management - Modular command system - Integrated structured logging - Centralized error handling</p> </div> </div> <div class="sect3"> <h4 id="_epic_2_spotify_integration"><a class="anchor" href="#_epic_2_spotify_integration"></a>Epic 2: Spotify Integration</h4> <div class="paragraph"> <p><strong>Business value</strong>: Access to musical metadata</p> </div> <div class="paragraph"> <p><strong>Acceptance criteria</strong>: - Secure OAuth2 authentication - Track search with intelligent cache - API quota management - Fallback on network errors</p> </div> </div> <div class="sect3"> <h4 id="_epic_3_youtube_integration"><a class="anchor" href="#_epic_3_youtube_integration"></a>Epic 3: YouTube Integration</h4> <div class="paragraph"> <p><strong>Business value</strong>: Access to audio content</p> </div> <div class="paragraph"> <p><strong>Acceptance criteria</strong>: - Legal bypass of restrictions - Optimized audio extraction - Management of private/deleted videos - Compliance with YouTube ToS</p> </div> </div> <div class="sect3"> <h4 id="_epic_4_musical_features"><a class="anchor" href="#_epic_4_musical_features"></a>Epic 4: Musical Features</h4> <div class="paragraph"> <p><strong>Business value</strong>: Complete user experience</p> </div> <div class="paragraph"> <p><strong>Acceptance criteria</strong>: - High-quality audio playback - Intelligent playback queue - Discord voice commands - Cross-platform synchronization</p> </div> </div> </div> <div class="sect2"> <h3 id="_detailed_user_stories"><a class="anchor" href="#_detailed_user_stories"></a>Detailed User Stories</h3> <div class="sect3"> <h4 id="_us1_1_bot_initialization"><a class="anchor" href="#_us1_1_bot_initialization"></a>US1.1: Bot Initialization</h4> <div class="paragraph"> <p><strong>As a</strong> developer <strong>I want</strong> a Discord bot that connects reliably <strong>In order to</strong> guarantee service availability</p> </div> <div class="paragraph"> <p><strong>DoD (Definition of Done)</strong>: - [ ] Bot connects automatically on startup - [ ] Structured logs document each step - [ ] Automatic reconnection in case of disconnection - [ ] Integration tests pass</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_intelligent_spotify_search"><a class="anchor" href="#_us2_1_intelligent_spotify_search"></a>US2.1: Intelligent Spotify Search</h4> <div class="paragraph"> <p><strong>As a</strong> Discord user <strong>I want</strong> to search for tracks via Spotify <strong>In order to</strong> discover and share music</p> </div> <div class="paragraph"> <p><strong>DoD</strong>: - [ ] Command`/search`functional - [ ] Relevant results with metadata - [ ] Local cache to optimize requests - [ ] Graceful handling of API errors</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_resilient_youtube_extraction"><a class="anchor" href="#_us3_1_resilient_youtube_extraction"></a>US3.1: Resilient YouTube Extraction</h4> <div class="paragraph"> <p><strong>As a</strong> system <strong>I want</strong> to extract YouTube audio reliably <strong>In order to</strong> maintain service continuity</p> </div> <div class="paragraph"> <p><strong>DoD</strong>: - [ ] Extraction without violating ToS - [ ] Optimal audio quality - [ ] Management of geographical restrictions - [ ] Detailed logs of operations</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_log_driven_development_approach_2"><a class="anchor" href="#_log_driven_development_approach_2"></a>Log Driven Development Approach</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_logging_strategy"><a class="anchor" href="#_logging_strategy"></a>Logging Strategy</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-33bca791609096cfd7cfaef40f1259bd.png" alt="Diagram" width="687" height="633"> </div> </div> </div> <div class="sect2"> <h3 id="_log_structure"><a class="anchor" href="#_log_structure"></a>Log Structure</h3> <div class="paragraph"> <p>Our LDD approach uses structured logs with semantic levels:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>TRACE</strong></dt> <dd> <p>Detailed data flow</p> </dd> <dt class="hdlist1"><strong>DEBUG</strong></dt> <dd> <p>Internal states of functions</p> </dd> <dt class="hdlist1"><strong>INFO</strong></dt> <dd> <p>Successful business operations</p> </dd> <dt class="hdlist1"><strong>WARN</strong></dt> <dd> <p>Degraded but managed situations</p> </dd> <dt class="hdlist1"><strong>ERROR</strong></dt> <dd> <p>Errors requiring intervention</p> </dd> <dt class="hdlist1"><strong>CRITICAL</strong></dt> <dd> <p>System failures</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_log_design_example"><a class="anchor" href="#_log_design_example"></a>Log Design Example</h3> <div class="paragraph"> <p>Before implementing the Spotify search function, we define its 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="_validation_architecture_with_pydantic"><a class="anchor" href="#_validation_architecture_with_pydantic"></a>Validation Architecture with Pydantic</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_data_models"><a class="anchor" href="#_data_models"></a>Data Models</h3> <div class="paragraph"> <p>Our functional approach prioritizes upstream validation:</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="_functional_error_handling"><a class="anchor" href="#_functional_error_handling"></a>Functional Error Handling</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_monads_and_error_handling"><a class="anchor" href="#_monads_and_error_handling"></a>Monads and Error Handling</h3> <div class="paragraph"> <p>The use of PyMonade allows for elegant error management:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-74aeddca6a901c6ae59215771b0f5f3e.png" alt="Diagram" width="494" height="494"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_restriction_bypass_strategy"><a class="anchor" href="#_restriction_bypass_strategy"></a>Restriction Bypass Strategy</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_multi_source_approach"><a class="anchor" href="#_multi_source_approach"></a>Multi-Source Approach</h3> <div class="paragraph"> <p>Facing API restrictions, we adopt a diversification strategy:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-87c462fe6bc8a10c764f1467ebf0bcc9.png" alt="Diagram" width="665" height="744"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_iterative_development_plan"><a class="anchor" href="#_iterative_development_plan"></a>Iterative Development Plan</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sprint_planning"><a class="anchor" href="#_sprint_planning"></a>Sprint Planning</h3> <div class="paragraph"> <p>Our development follows a 2-week sprint cycle:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>Sprint 1-2</strong></dt> <dd> <p>Infrastructure and Discord Bot Core</p> </dd> <dt class="hdlist1"><strong>Sprint 3-4</strong></dt> <dd> <p>Spotify Integration with LDD</p> </dd> <dt class="hdlist1"><strong>Sprint 5-6</strong></dt> <dd> <p>YouTube Integration and bypasses</p> </dd> <dt class="hdlist1"><strong>Sprint 7-8</strong></dt> <dd> <p>Advanced musical features</p> </dd> <dt class="hdlist1"><strong>Sprint 9-10</strong></dt> <dd> <p>Optimization and production</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_quality_metrics"><a class="anchor" href="#_quality_metrics"></a>Quality Metrics</h3> <div class="paragraph"> <p>Each sprint is evaluated on:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Log coverage</strong>: >90% of critical paths</p> </li> <li> <p><strong>API Reliability</strong>: <1% unhandled errors</p> </li> <li> <p><strong>Performance</strong>: <500ms average response time</p> </li> <li> <p><strong>Maintainability</strong>: Cyclomatic complexity <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_deployment_and_monitoring"><a class="anchor" href="#_deployment_and_monitoring"></a>Deployment and Monitoring</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_production_architecture"><a class="anchor" href="#_production_architecture"></a>Production Architecture</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-80438472ae398e8719f794b90482b959.png" alt="Diagram" width="938" height="381"> </div> </div> </div> <div class="sect2"> <h3 id="_proactive_monitoring"><a class="anchor" href="#_proactive_monitoring"></a>Proactive Monitoring</h3> <div class="paragraph"> <p>LDD facilitates intelligent monitoring:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Alerts based on log patterns</strong></p> </li> <li> <p><strong>Behavioral anomaly detection</strong></p> </li> <li> <p><strong>Real-time business metrics</strong></p> </li> <li> <p><strong>Debugging assisted by log correlation</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_and_perspectives"><a class="anchor" href="#_conclusion_and_perspectives"></a>Conclusion and Perspectives</h2> <div class="sectionbody"> <div class="paragraph"> <p>This methodological approach combines the benefits of the functional paradigm with the robustness of Log Driven Development. It allows us to:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Anticipate problems</strong>thanks to logs designed upstream</p> </li> <li> <p><strong>Maintain quality</strong>via continuous validation</p> </li> <li> <p><strong>Adapt quickly</strong>to API changes</p> </li> <li> <p><strong>Ensure complete</strong>traceability of operations</p> </li> </ol> </div> <div class="paragraph"> <p>Iterative development and modular architecture guarantee scalability in the face of changing constraints of musical platforms.</p> </div> <div class="sect2"> <h3 id="_next_steps"><a class="anchor" href="#_next_steps"></a>Next Steps</h3> <div class="ulist"> <ul> <li> <p><strong>Phase 1</strong>: Core implementation with PyMonade</p> </li> <li> <p><strong>Phase 2</strong>: Spotify integration with intelligent cache</p> </li> <li> <p><strong>Phase 3</strong>: Resilient YouTube solution</p> </li> <li> <p><strong>Phase 4</strong>: Advanced features and optimization</p> </li> </ul> </div> <div class="paragraph"> <p>This solid conceptual foundation will allow us to navigate technical challenges while delivering an exceptional user experience.</p> </div> <hr> <div class="paragraph"> <p><strong>This article will be followed by a technical series detailing the implementation of each component with code examples and functional patterns.</strong></p> </div> </div> </div> </div> https://cheroliv.com/en/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="#_objective_of_this_guide">Objective of this guide</a></li> <li><a href="#_prerequisites">Prerequisites</a></li> <li><a href="#_install_and_configure_tools">Install and configure tools</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_to_detect_sensors"><code>lm-sensors</code> to detect sensors</a></li> <li><a href="#_tlp_intelligent_power_manager"><code>tlp</code>: intelligent power manager</a></li> <li><a href="#_cpufrequtils_limit_cpu_frequencies"><code>cpufrequtils</code>: limit CPU frequencies</a></li> <li><a href="#_auto_cpufreq_simplified_dynamic_management"><code>auto-cpufreq</code>: simplified dynamic management</a></li> <li><a href="#_thermald_automatic_thermal_protection"><code>thermald</code>: automatic thermal protection</a></li> </ul> </li> <li><a href="#_real_time_monitoring">Real-time monitoring</a> <ul class="sectlevel2"> <li><a href="#_sensors_via_command_line"><code>sensors</code> via command line</a></li> <li><a href="#_gui_option_psensor">GUI Option: <code>psensor</code></a></li> </ul> </li> <li><a href="#_additional_tips">Additional tips</a></li> <li><a href="#_clean_the_system_to_limit_overloads">Clean the system to limit overloads</a></li> <li><a href="#_to_go_further">To go further</a></li> <li><a href="#_conclusion">📚 Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Do you feel that your laptop is overheating abnormally under Ubuntu? This article offers a complete<strong>software</strong>approach to<strong>cool</strong>, <strong>monitor</strong> et <strong>control the temperature</strong>of your machine.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objective_of_this_guide">Objective of this guide</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Reduce the overall temperature of the computer</p> </li> <li> <p>Optimize power management</p> </li> <li> <p>Monitor critical components (CPU, GPU, etc.)</p> </li> <li> <p>Avoid slowdowns due to<strong>thermal throttling</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="_prerequisites">Prerequisites</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>An Ubuntu machine (20.04 or higher recommended)</p> </li> <li> <p>Internet connection</p> </li> <li> <p>Command line skills (beginner to intermediate level)</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_install_and_configure_tools">Install and configure tools</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_to_detect_sensors"><code>lm-sensors</code> to detect sensors</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>Answer`YES`all the questions from`sensors-detect`to detect modules.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_intelligent_power_manager"><code>tlp</code>: intelligent power manager</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="363" height="390"> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_limit_cpu_frequencies"><code>cpufrequtils</code>: limit CPU frequencies</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install cpufrequtils cpufreq-info sudo cpufreq-set -g powersave</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>powersave</code>: limits frequency spikes</p> </li> <li> <p><code>performance</code>: favors performance at the expense of temperature</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_simplified_dynamic_management"><code>auto-cpufreq</code>: simplified dynamic management</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_automatic_thermal_protection"><code>thermald</code>: automatic thermal protection</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="_real_time_monitoring">Real-time monitoring</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_via_command_line"><code>sensors</code> via command line</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="_gui_option_psensor">GUI Option: <code>psensor</code></h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install psensor</code></pre> </div> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>Simple graphical interface for CPU, GPU, fans.</p> </div> </blockquote> </div> </div> </div> </div> <div class="sect1"> <h2 id="_additional_tips">Additional tips</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Close tabs and heavy applications (e.g., browsers)</p> </li> <li> <p>Avoid intense use on battery</p> </li> <li> <p>Monitor processes 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="_clean_the_system_to_limit_overloads">Clean the system to limit overloads</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="_to_go_further">To go further</h2> <div class="sectionbody"> <div class="paragraph"> <p>You can create a custom`systemd`service to automatically apply certain settings at startup. Would you like an example in a future article? Let me know!</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">📚 Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>By combining these simple tools, you will gain:</p> </div> <div class="ulist"> <ul> <li> <p>Controlled CPU temperature</p> </li> <li> <p>Less fan noise</p> </li> <li> <p>Better battery life</p> </li> </ul> </div> <div class="paragraph"> <p>Remember to monitor your temperatures regularly to prevent any overheating.</p> </div> <div class="paragraph"> <p><em><em>_ Better safe than melting your CPU. </em>_</em></p> </div> </div> </div> https://cheroliv.com/en/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="#_the_battlefield_one_mockup_three_browsers_multiple_renderings">The battlefield: one mockup, three browsers, multiple renderings</a></li> <li><a href="#_problem_1_the_flying_card_of_the_hero_section">Problem 1: The flying card of the "Hero" section</a></li> <li><a href="#_problem_2_the_cannibal_navigation_bar">Problem 2: The cannibal navigation bar</a></li> <li><a href="#_problem_3_anarchic_typography">Problem 3: Anarchic typography</a></li> <li><a href="#_problem_4_the_overflowing_navigation_bar">Problem 4: The overflowing navigation bar</a></li> <li><a href="#_problem_5_the_invisible_hamburger_menu">Problem 5: The invisible hamburger menu</a></li> <li><a href="#_conclusion_lessons_from_a_relentless_debugging_session">Conclusion: lessons from a relentless debugging session</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>Reading time:</strong> about 7 minutes <strong>Level:</strong> Intermediate</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>In this detailed practical case, we will dissect the most common and sometimes most frustrating browser compatibility issues encountered when creating a UI mockup with Bootstrap 5.2. From Flexbox management to the subtlety of font rendering, discover our debugging journey to transform a shaky design under Firefox into a pixel-perfect experience across all browsers.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_the_battlefield_one_mockup_three_browsers_multiple_renderings">The battlefield: one mockup, three browsers, multiple renderings</h2> <div class="sectionbody"> <div class="paragraph"> <p>Every front-end developer knows this feeling. After hours of work, the mockup is finally perfect. Alignments are sharp, typography is elegant, animations are fluid. You breathe a sigh of satisfaction, admire your work on Chrome (or Brave, or Edge), then, to be thorough, you open the project in Firefox. And there, disaster strikes. Elements overflowing, broken alignments, fonts with anarchic sizes…​ the beautiful harmony has vanished.</p> </div> <div class="paragraph"> <p>This is precisely the scenario we faced while developing a new portfolio interface. The specifications were simple: a modern, responsive home page with a theme selector (light, dark, and high contrast), using <strong>vanilla JavaScript</strong> and the latest version of <strong>Bootstrap 5.2</strong>.</p> </div> <div class="paragraph"> <p>This article is not a list of miracle solutions. It is the logbook of our debugging session, a dive into the "why" of rendering differences between the Blink engines (Chromium, Brave) and Gecko (Firefox), and a demonstration that robust and modern solutions are always better than hasty patches.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/usecase-debugging-firefox.svg" alt="usecase debugging firefox" width="1045" height="401"> </div> <div class="title">Figure 1. Use Case Diagram: The debugging process</div> </div> <div class="imageblock"> <div class="content"> <img src="./images/components-solution-architecture.svg" alt="components solution architecture" width="1286" height="188"> </div> <div class="title">Figure 2. Component Diagram: Front-end solution architecture</div> </div> </div> </div> <div class="sect1"> <h2 id="_problem_1_the_flying_card_of_the_hero_section">Problem 1: The flying card of the "Hero" section</h2> <div class="sectionbody"> <div class="paragraph"> <p>The first bug was also the most visible. The home section ("hero") consists of two columns: on the left, the main title; on the right, a presentation card.</p> </div> <div class="ulist"> <ul> <li> <p><strong>The symptom:</strong>On Chrome and Brave, the two columns were perfectly centered vertically. On Firefox, the right card inexplicably dropped below the left text.</p> </li> <li> <p><strong>The investigation:</strong>The HTML code seemed simple and correct, using standard Bootstrap classes.</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>Our custom CSS for`.hero-section`defined`display: flex` et <code>align-items: center</code>, and the class`min-vh-100`indeed gave a minimum line height (<code>div.row</code>). So, why did Firefox refuse to center the columns?</p> </div> <div class="ulist"> <ul> <li> <p><strong>The root cause:</strong>This is a textbook case of how rendering engines interpret implicit heights. The`<section>`had a`min-height`, but no`height`explicit height. To apply`align-items-center`inside`div.row`, Firefox needs to know the reference height of this container. Since its parents (<code>div.container</code> et la `<section>`itself) did not have a<strong>strict</strong>height, Firefox was lost. The Blink engine, being more permissive, manages to "guess" the intention and center the elements. Gecko, more faithful to the specification, does not.</p> </li> <li> <p><strong>The solution:</strong>Make the height explicit. We forced the`.container` et le <code>.row`to occupy 100% of their respective parent’s height using the Bootstrap utility class`h-100</code>.</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>When a`align-items`Flexbox does not work as expected on the vertical axis, always check that the container has a height (<code>height</code> ou <code>min-height</code>) defined and, if the problem persists (especially on Firefox), ensure that intermediate parent containers propagate this height.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_problem_2_the_cannibal_navigation_bar">Problem 2: The cannibal navigation bar</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Once the "Hero" section was aligned, another problem appeared: the navigation bar, with its`fixed-top`class, overlapped the title. A`padding-top: 80px`had been applied to the "Hero" section as a solution.</div> <ul> <li> <p><strong>The symptom:</strong> Le `padding`was sufficient on Chrome, but not on Firefox, where the title was still partially hidden.</p> </li> <li> <p><strong>The root cause:</strong>Using a "magic number" (<code>80px</code>) is a very bad practice. The height of an element like a navigation bar can vary by a few pixels from one browser to another due to subtle differences in font rendering, spacing, or even user options. Relying on a fixed value is a recipe for a fragile design.</p> </li> <li> <p><strong>The solution:</strong>A dynamic and infallible solution in JavaScript. We wrote a small script to:</p> </li> <li> <p>Measure the <strong>actual</strong> height of the navigation bar after the page renders.</p> </li> <li> <p>Apply this measured height as`padding-top`to the "Hero" section.</p> </li> <li> <p>Re-run this function on every window resize to adapt to changes (such as switching to the hamburger menu).</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. Sequence Diagram: Dynamic padding adjustment</div> </div> <div class="paragraph"> <p>In parallel, we of course removed the`padding-top: 80px;`rule from our`styles.css`file.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problem_3_anarchic_typography">Problem 3: Anarchic typography</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">The next issue was the most damaging to the brand image: the size of the main title.</div> <ul> <li> <p><strong>The symptom:</strong>On Firefox, the font of the title "Developer Trainer…​" was gigantic, almost shocking, while it was harmonious on other browsers.</p> </li> <li> <p><strong>The root cause:</strong>The title used a Bootstrap`display-4`class. These classes use responsive font sizes, often based on the`rem`unit and media queries. Once again, Firefox’s rendering algorithm, combined with the "Inter" font, resulted in a much larger size calculation on our 1920x1080 resolution.</p> </li> <li> <p><strong>The solution:</strong>Taking back control with the CSS`clamp()<code>function. This function is a revolution for fluid typography. It allows defining a font size with three values: a minimum size, a "preferred" size (which adapts to the viewport width,`vw</code>), and a maximum size.</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>With`clamp()`, we were able to tell the browser: "Let the font grow with the screen, but<strong>never</strong>exceed the limit of`2.5rem`". This instantly harmonized the rendering across all browsers, giving us absolute control over the final aesthetic.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problem_4_the_overflowing_navigation_bar">Problem 4: The overflowing navigation bar</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">This is the problem that gave us the most trouble and finally revealed the deep nature of rendering micro-differences.</div> <ul> <li> <p><strong>The symptom:</strong>On a 1920x1080 screen, the last menu links ("Blog", "Contact") were pushed off the screen to the right, but only on Firefox.</p> </li> <li> <p><strong>The root cause:</strong>After several unsuccessful attempts (changing Bootstrap breakpoints from`lg` à <code>xl`then`xxl</code>), we understood. The cause was not Bootstrap’s logic, but a simple width calculation. On Firefox, the sum of the widths of all links, including their`padding` et `margin`down to the sub-pixel, was <strong>slightly</strong> greater than 1920 pixels. On Chrome, this same sum was <strong>slightly</strong> less. We were missing a few pixels.</p> </li> <li> <p><strong>The solution:</strong>A surgical reduction of spacing. Since targeting Firefox specifically with obsolete CSS "hacks" was out of the question, the only clean solution was to find a common style that works everywhere. We therefore slightly reduced the horizontal margins and padding of each navigation link.</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>This reduction, almost invisible to the naked eye on a single element, collectively gained us the necessary space for all links to fit within the frame on Firefox, while maintaining a nearly identical appearance on other browsers.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problem_5_the_invisible_hamburger_menu">Problem 5: The invisible hamburger menu</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">The final problem, and no less important, concerned mobile accessibility.</div> <ul> <li> <p><strong>The symptom:</strong>In responsive mode (hamburger menu), the menu icon was invisible on the "dark" and "high-contrast" themes.</p> </li> <li> <p><strong>The root cause:</strong>The Bootstrap 5 menu icon is a`background-image`(an SVG encoded in a URL). By default, its stroke color is dark, optimized for a light background. It does not automatically adapt to theme changes.</p> </li> <li> <p><strong>The solution:</strong>Using Bootstrap CSS variables to override the icon. We defined a new SVG icon, but this time with a white stroke (<code>#ffffff</code>), and applied it specifically when the`dark` ou `high-contrast`themes are active.</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>The customization of Bootstrap components like this is increasingly done via overriding CSS variables (<code>--bs-component-property</code>), which is the cleanest and most sustainable method.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_lessons_from_a_relentless_debugging_session">Conclusion: lessons from a relentless debugging session</h2> <div class="sectionbody"> <div class="paragraph"> <p>This journey, although sometimes frustrating, is rich with lessons. Each solved problem reinforces a fundamental truth of web development:<strong>nothing replaces rigorous multi-browser testing</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: Synthesis of debugging and lessons learned</div> </div> <div class="olist arabic"> <div class="title">Here are the lessons we take away:</div> <ol class="arabic"> <li> <p><strong>Firefox is an ally:</strong>Its greater fidelity to CSS standards forces us to write more robust and less ambiguous code.</p> </li> <li> <p><strong>Avoid "magic numbers":</strong>Fixed values (like`padding-top: 80px`) are time bombs. Always prefer dynamic solutions (JavaScript) or relative ones (Flexbox, Grid).</p> </li> <li> <p><strong>Master your typography:</strong>Use`clamp()`for total control over responsive font sizes.</p> </li> <li> <p><strong>Think in "components":</strong>To customize Bootstrap, override its CSS variables rather than multiplying rules that overwrite the framework.</p> </li> <li> <p><strong>Do not target a specific browser:</strong>The solution is almost never to create a "hack" for one specific browser, but to find a common style that works everywhere.</p> </li> </ol> </div> <div class="paragraph"> <p>In the end, the mockup is now solid, predictable, and ready to be integrated into a templating system. Each bug fixed was not a failure, but a step toward higher quality code.</p> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_isolating_unit_tests_for_a_gradle_plugin">The Problem: Isolating Unit Tests for a Gradle Plugin</a> <ul class="sectlevel2"> <li><a href="#_problem_architecture">Problem Architecture</a></li> <li><a href="#_the_temptation_of_a_false_good_idea">The Temptation of a False Good Idea</a></li> </ul> </li> <li><a href="#_the_solution_simulating_the_property_with_extrapropertiesextension">The Solution: Simulating the Property with <code>ExtraPropertiesExtension</code></a> <ul class="sectlevel2"> <li><a href="#_step_1_understanding_extrapropertiesextension">Step 1: Understanding ExtraPropertiesExtension</a></li> <li><a href="#_step_2_test_setup_preparation">Step 2: Test Setup - Preparation</a></li> <li><a href="#_step_3_property_injection">Step 3: Property Injection</a></li> <li><a href="#_step_4_solution_flow_diagram">Step 4: Solution Flow Diagram</a></li> <li><a href="#_step_5_beforeafter_comparison">Step 5: Before/After Comparison</a></li> <li><a href="#_step_6_managing_multiple_test_cases">Step 6: Managing Multiple Test Cases</a></li> <li><a href="#_final_solution_architecture">Final Solution Architecture</a></li> </ul> </li> <li><a href="#_advantages_of_this_approach">Advantages of this Approach</a></li> <li><a href="#_best_practices_and_tips">Best Practices and Tips</a> <ul class="sectlevel2"> <li><a href="#_creating_a_utility_method">Creating a Utility Method</a></li> <li><a href="#_property_validation">Property Validation</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div class="sect1"> <h2 id="_the_problem_isolating_unit_tests_for_a_gradle_plugin">The Problem: Isolating Unit Tests for a Gradle Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>When writing unit tests for a Gradle plugin, a common challenge is managing dependencies on project configuration, such as properties defined in the <code>gradle.properties</code> file.`gradle.properties`In our case, the plugin`jbake.ghpages`had to read a property`site_config_path`to function correctly. The unit test for the task`initialize`needed to verify the plugin’s behavior in the presence of this property.</p> </div> <div class="paragraph"> <p>The fundamental problem is that unit tests, by design, must be <strong>isolated</strong>. Using`ProjectBuilder`from Gradle creates an instance of`Project`in memory, completely disconnected from a real project on the file system. Consequently, this test instance does not automatically read the <code>gradle.properties</code> file`gradle.properties`and therefore has no knowledge of the property`site_config_path`.</p> </div> <div class="sect2"> <h3 id="_problem_architecture">Problem Architecture</h3> <div class="paragraph"> <p>The following diagram illustrates the disconnection between the test environment and the file system:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/test-isolation-problem.svg" alt="test isolation problem" width="833" height="295"> </div> </div> </div> <div class="sect2"> <h3 id="_the_temptation_of_a_false_good_idea">The Temptation of a False Good Idea</h3> <div class="paragraph"> <p>An initial approach might be to create a dummy <code>gradle.properties</code> file`gradle.properties`in the test resources.</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>However, this method is doomed to fail because`ProjectBuilder`is not designed to scan the file system for configuration files. The test would remain isolated and ignore this file.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_solution_simulating_the_property_with_extrapropertiesextension">The Solution: Simulating the Property with <code>ExtraPropertiesExtension</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The elegant solution to this problem is not to <strong>read</strong> the file, but to <strong>simulate</strong> the presence of the property directly within the`Project`test object. Gradle provides a powerful mechanism for this: <strong>extra properties</strong>.</p> </div> <div class="sect2"> <h3 id="_step_1_understanding_extrapropertiesextension">Step 1: Understanding ExtraPropertiesExtension</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`is a key-value container attached to every Gradle model object. It allows adding properties dynamically to a project, a task, or any other Gradle extension.</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="_step_2_test_setup_preparation">Step 2: Test Setup - Preparation</h3> <div class="paragraph"> <p>Let’s start by creating the basic structure of our unit test:</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="_step_3_property_injection">Step 3: Property Injection</h3> <div class="paragraph"> <p>Here is the detailed process for injecting the property into the test project:</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="_step_4_solution_flow_diagram">Step 4: Solution Flow Diagram</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="_step_5_beforeafter_comparison">Step 5: Before/After Comparison</h3> <div class="imageblock"> <div class="content"> <img src="./images/before-after-comparison.svg" alt="before after comparison" width="1304" height="399"> </div> </div> </div> <div class="sect2"> <h3 id="_step_6_managing_multiple_test_cases">Step 6: Managing Multiple Test Cases</h3> <div class="paragraph"> <p>To test different scenarios, let’s create several tests with varied configurations:</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="_final_solution_architecture">Final Solution Architecture</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="_advantages_of_this_approach">Advantages of this Approach</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Complete Isolation</strong>: The test does not depend on any external file. It is self-contained and can run reliably in any environment (local, CI/CD, etc.).</p> </li> <li> <p><strong>Clarity and Intent</strong>: The test explicitly declares the prerequisites for its execution. Anyone reading the test immediately sees that the plugin requires the property`site_config_path`to function.</p> </li> <li> <p><strong>Maintainability</strong>: If the property name changes, it only needs to be updated in one place in the test, without having to manipulate test configuration files.</p> </li> <li> <p><strong>Flexibility</strong>: It becomes trivial to test different scenarios by simply changing the value of the property injected into each test (valid value, invalid, absent, etc.).</p> </li> <li> <p><strong>Performance</strong>: No file reading; everything happens in memory, making the tests faster.</p> </li> <li> <p><strong>Reproducibility</strong>: Tests are deterministic because they do not depend on the state of the file system.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_best_practices_and_tips">Best Practices and Tips</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_creating_a_utility_method">Creating a Utility Method</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="_property_validation">Property Validation</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Rather than struggling to make a unit test environment read configuration files, the best practice is to simulate the required state. Using`ExtraPropertiesExtension`to programmatically define Gradle properties is the cleanest and most robust method for performing effective and reliable plugin unit tests.</p> </div> <div class="paragraph"> <p>This technique transforms an external dependency problem into a simple dependency injection, at the very heart of the Test-Driven Development (TDD) philosophy. It offers total control over the test environment while maintaining the isolation necessary for high-quality unit tests.</p> </div> <div class="paragraph"> <p>The diagrams and examples presented in this article show how this approach can be implemented progressively and methodically, allowing for the creation of a robust and maintainable test suite for your Gradle plugins.</p> </div> </div> </div> https://cheroliv.com/en/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="#_centralizing_configurations_with_allprojects_and_subprojects">Centralizing Configurations with <code>allprojects</code> and <code>subprojects</code></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> <li><a href="#">}</a></li> <li><a href="#_sourcekotlin_2">[source,kotlin]</a></li> <li><a href="#_abstract_class_reportjbakefunctionalteststask_abstractjbakeexectask_init_description_opens_the_functional_test_report_in_firefox_reportrelativepath_buildreportstestsfunctionaltestindex_html">abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "Opens the functional test report in Firefox." reportRelativePath = "build/reports/tests/functionalTest/index.html" } }</a></li> <li><a href="#_sourcekotlin_3">[source,kotlin]</a></li> <li><a href="#_tasks_registerreportjbaketeststaskreportbuildsrctests_the_path_is_already_defined_in_the_class_it_will_point_to_buildsrc_reports">tasks.register\<ReportJbakeTestsTask\>("reportBuildSrcTests") { // The path is already defined in the class, it will point to buildSrc reports }</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Automating build tasks is crucial for any software project, and Gradle, with its Kotlin DSL, offers exceptional flexibility. During our conversation, we explored how to centralize and reuse build logic, particularly for test reports, by leveraging<strong>allprojects</strong>, <strong>buildSrc</strong>, and custom tasks in Kotlin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_centralizing_configurations_with_allprojects_and_subprojects">Centralizing Configurations with <code>allprojects</code> and <code>subprojects</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>The blocks`allprojects` et `subprojects`in your`build.gradle.kts`root are fundamental for applying common configurations across your multi-module project.</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: Applies the configuration to the<strong>root project and all its sub-projects</strong>. Ideal for defining a`group`, a`version`, or common`repositories`. *<code>subprojects { …​ }</code>: Applies the configuration<strong>only to sub-projects</strong>, excluding the root project. Perfect for applying module-specific plugins (such as`java` ou <code>kotlin-jvm</code>) or common dependencies to your libraries.</p> </div> <div class="paragraph"> <p>Here is an illustrative example:</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>\==<code>buildSrc</code>: The Swiss Army Knife of Build Logic</p> </div> <div class="paragraph"> <p>When your task logic becomes complex or needs to be reused,<strong>buildSrc</strong>is the preferred solution. It is a special Gradle module that is compiled before the main build scripts, making its classes available on the classpath of your entire build.</p> </div> <div class="paragraph"> <p>\=== Why use`buildSrc`for Tasks?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Reusability</strong>: A task defined in`buildSrc`can be applied to any project in the build.</p> </li> <li> <p><strong>Organization</strong>: Centralizes build code, making it cleaner and more maintainable.</p> </li> <li> <p><strong>Type Safety and Autocompletion</strong>: Kotlin code in`buildSrc`is compiled, providing error checking and IDE autocompletion, improving the development experience.</p> </li> </ul> </div> <div class="paragraph"> <p>\=== Flow Diagram`buildSrc`(PlantUML Code)</p> </div> <div class="paragraph"> <p>To generate this diagram, copy the code below and paste it into a tool supporting 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 "Gradle Build Process" { component "buildSrc" as BS { file "MyCustomTask.kt" as T file "MyConventionPlugin.kt" as P } component "Root Project" as RP component "Subproject A" as SA component "Subproject B" as SB }</p> </div> <div class="paragraph"> <p>T --\> P : "is defined in" P --\> RP : "is applied to" P --\> SA : "is applied to" P --\> SB : "is applied to"</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contains" RP --|\> SB : "contains"</p> </div> <div class="paragraph"> <p>RP -up-\> BS : "depends on (for build logic)" SA -up-\> BS : "depends on (for build logic)" SB -up-\> BS : "depends on (for build logic)"</p> </div> <div class="paragraph"> <p>note right of T Custom task classes (e.g., OpenTestReportTask) end note</p> </div> <div class="paragraph"> <p>note right of P Convention plugins that register tasks end note</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>\== Creating Abstract Report Tasks</p> </div> <div class="paragraph"> <p>To manage test reports, we designed a modular approach using an abstract task class in`buildSrc`. Depending on your needs, this class can inherit from`DefaultTask` ou de <code>Exec</code>.</p> </div> <div class="paragraph"> <p>\=== Abstract Task`OpenTestReportTask`(inheriting from`DefaultTask`)</p> </div> <div class="paragraph"> <p>This approach is recommended if you need custom Kotlin logic that interacts with the file system or other Gradle APIs, and then launches an external command.</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}") } ---- ## } \=== Concrete Implementations These classes inherit from the abstract task and define the specific report path. ## [source,kotlin] package com.yourpackage abstract class ReportUnitTestsTask : OpenTestReportTask() { init { description = "Opens the unit test report in Firefox." reportPath = "build/reports/tests/test/index.html" } } package com.yourpackage ## abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "Opens the functional test report in Firefox." reportPath = "build/reports/tests/functionalTest/index.html" } } \=== Task Registration In the`build.gradle.kts`of your root project: ## [source,kotlin] ## tasks.register\<com.yourpackage.ReportUnitTestsTask\>("reportTests") {} tasks.register\<com.yourpackage.ReportFunctionalTestsTask\>("reportFunctionalTests") {} \=== UML Diagram of Report Tasks (PlantUML Code) Copy the code below and paste it into a tool supporting PlantUML. ## [source,plantuml] @startuml skinparam handwritten true skinparam monochrome true abstract class DefaultTask { } abstract class Exec { \+ commandLine(args: String...) \+ exec() } abstract class OpenTestReportTask extends DefaultTask { \+ group: String = "verification" \+ description: String \+ dependsOn("check") \+ abstract reportPath: String \+ openReport() : void } abstract class AbstractJbakeExecTask extends Exec { \+ group: String = "verification" \+ description: String \+ dependsOn("check") \+ abstract reportRelativePath: String \+ exec() : void } class ReportUnitTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/test/index.html" } class ReportFunctionalTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/functionalTest/index.html" } class ReportJbakeTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/test/index.html" } class ReportJbakeFunctionalTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/functionalTest/index.html" } OpenTestReportTask \<-- ReportUnitTestsTask OpenTestReportTask \<-- ReportFunctionalTestsTask AbstractJbakeExecTask \<-- ReportJbakeTestsTask AbstractJbakeExecTask \<-- ReportJbakeFunctionalTestsTask DefaultTask \<|-- OpenTestReportTask Exec \<|-- AbstractJbakeExecTask DefaultTask \<|-- Exec ## @enduml \== Abstract Task`AbstractJbakeExecTask`(inheriting from`Exec`) If your task mainly consists of executing an external command with variable arguments, inheriting directly from**Exec**is more direct. ## [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() {</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>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 }</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="">}</h2> <div class="sectionbody"> <div class="paragraph"> <p>\=== Concrete Implementations for`Exec`</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin_2">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>package com.yourpackage</p> </div> <div class="paragraph"> <p>abstract class ReportJbakeTestsTask : AbstractJbakeExecTask() { init { description = "Opens the Jbake unit test report in Firefox." reportRelativePath = "build/reports/tests/test/index.html" } }</p> </div> <div class="paragraph"> <p>package com.yourpackage</p> </div> </div> </div> <div class="sect1"> <h2 id="_abstract_class_reportjbakefunctionalteststask_abstractjbakeexectask_init_description_opens_the_functional_test_report_in_firefox_reportrelativepath_buildreportstestsfunctionaltestindex_html">abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "Opens the functional test report in Firefox." reportRelativePath = "build/reports/tests/functionalTest/index.html" } }</h2> <div class="sectionbody"> <div class="paragraph"> <p>\== Task Visibility`buildSrc`</p> </div> <div class="paragraph"> <p>The tasks and classes you define in<strong>buildSrc</strong>are:</p> </div> <div class="paragraph"> <p><strong>*Visible and usable</strong>by all projects in your main build (root and sub-projects). This is why you can use`com.yourpackage.ReportUnitTestsTask`in`allprojects { …​ }`. <strong>*Not executable</strong>directly as buildSrc tasks (for example,<code>gradle :buildSrc:reportTests`would not work if the task is not registered specifically in`buildSrc/build.gradle.kts</code>).`buildSrc`is a compilation module, not an executable application module for these main build tasks.</p> </div> <div class="paragraph"> <p>\=== Running a report for`buildSrc`tests itself</p> </div> <div class="paragraph"> <p>Si <code>buildSrc`has its own tests and generates reports, you can register a report task directly in`buildSrc/build.gradle.kts</code>:</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin_3">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>plugins { <code>kotlin-jvm</code> }</p> </div> <div class="paragraph"> <p>repositories { mavenCentral() }</p> </div> <div class="paragraph"> <p>tasks.withType\<Test\> { useJUnitPlatform() reports.html.outputLocation.set(layout.buildDirectory.dir("reports/tests")) }</p> </div> <div class="paragraph"> <p>import com.yourpackage.ReportJbakeTestsTask // Import your task class</p> </div> </div> </div> <div class="sect1"> <h2 id="_tasks_registerreportjbaketeststaskreportbuildsrctests_the_path_is_already_defined_in_the_class_it_will_point_to_buildsrc_reports">tasks.register\<ReportJbakeTestsTask\>("reportBuildSrcTests") { // The path is already defined in the class, it will point to buildSrc reports }</h2> <div class="sectionbody"> <div class="paragraph"> <p>You can then run:`./gradlew :buildSrc:test`followed by`./gradlew :buildSrc:reportBuildSrcTests`.</p> </div> <div class="paragraph"> <p>By adopting these practices, you will build Gradle Kotlin DSL build systems that are not only powerful, but also incredibly modular, maintainable, and easy to understand.</p> </div> </div> </div> https://cheroliv.com/en/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="#_objective">Objective</a></li> <li><a href="#_declarative_configuration">Declarative Configuration</a></li> <li><a href="#_plugin_architecture">Plugin Architecture</a></li> <li><a href="#_dsl_extension_definition">DSL Extension Definition</a></li> <li><a href="#_custom_task_definition">Custom Task Definition</a></li> <li><a href="#_gitadapter_interface">GitAdapter Interface</a></li> <li><a href="#_concrete_implementation_with_jgit">Concrete Implementation with JGit</a></li> <li><a href="#_kotlin_dsl_configuration">Kotlin DSL Configuration</a></li> <li><a href="#_unit_tests_with_mockito">Unit Tests with Mockito</a> <ul class="sectlevel2"> <li><a href="#_dependencies">Dependencies</a></li> <li><a href="#_testing_git_behavior">Testing Git Behavior</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_next_steps">Next Steps</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>This post presents the complete design and testing process (TDD) of a Gradle plugin written in Kotlin DSL. This plugin automates the generation of static sites with <strong>JBake</strong> and <strong>Git deployment</strong> via <strong>JGit</strong>, all from a YAML configuration file.</p> </div> </div> </div> <div class="sect1"> <h2 id="_objective">Objective</h2> <div class="sectionbody"> <div class="paragraph"> <p>Create a Gradle plugin:</p> </div> <div class="ulist"> <ul> <li> <p>configurable in Kotlin DSL;</p> </li> <li> <p>capable of:</p> </li> <li> <p>generating a static site using JBake;</p> </li> <li> <p>deploying to a remote Git repository via JGit;</p> </li> <li> <p>integrable into a CI/CD workflow;</p> </li> <li> <p>tested according to a TDD approach.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_declarative_configuration">Declarative Configuration</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is an example of a YAML configuration to model in our 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>This configuration is represented via a Gradle extension declarable in Kotlin DSL.</p> </div> </div> </div> <div class="sect1"> <h2 id="_plugin_architecture">Plugin Architecture</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="_dsl_extension_definition">DSL Extension Definition</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="_custom_task_definition">Custom Task Definition</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="_gitadapter_interface">GitAdapter Interface</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="_concrete_implementation_with_jgit">Concrete Implementation with 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="_kotlin_dsl_configuration">Kotlin DSL Configuration</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="_unit_tests_with_mockito">Unit Tests with Mockito</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dependencies">Dependencies</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="_testing_git_behavior">Testing Git Behavior</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="783" height="326"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>The separation of responsibilities via`GitAdapter`allows for the full application of TDD in Gradle plugin development:</p> </div> <div class="ulist"> <ul> <li> <p>Git calls are abstracted and testable;</p> </li> <li> <p>the DSL configuration is clean and clear;</p> </li> <li> <p>the plugin remains agnostic of the actual implementation.</p> </li> </ul> </div> <div class="paragraph"> <p>This approach ensures high testability and extensibility (towards GitHub API, GitLab, etc.).</p> </div> </div> </div> <div class="sect1"> <h2 id="_next_steps">Next Steps</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Integrate JBake generation as a`BakeAdapter`</p> </li> <li> <p>Add integration tests with`GradleRunner`</p> </li> <li> <p>Support the automatic loading of`site.yml`files via SnakeYAML</p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_what_is_asciidoc">What is AsciiDoc?</a> <ul class="sectlevel2"> <li><a href="#_why_choose_asciidoc">Why choose AsciiDoc?</a></li> </ul> </li> <li><a href="#_use_case_diagram">Use Case Diagram</a></li> <li><a href="#_mind_map_diagram">Mind Map Diagram</a></li> <li><a href="#_flow_diagram">Flow Diagram</a></li> <li><a href="#_basic_structure_of_an_asciidoc_file">Basic Structure of an AsciiDoc File</a></li> <li><a href="#_fundamental_syntax">Fundamental Syntax</a> <ul class="sectlevel2"> <li><a href="#_headings_and_sections">Headings and Sections</a></li> <li><a href="#_bold_italic_and_monospace_text">Bold, Italic, and Monospace Text</a></li> <li><a href="#_bulleted_and_numbered_lists">Bulleted and Numbered Lists</a></li> <li><a href="#_links_and_images">Links and Images</a></li> <li><a href="#_code_blocks">Code Blocks</a></li> <li><a href="#_tables">Tables</a></li> <li><a href="#_notes_and_admonitions">Notes and Admonitions</a></li> </ul> </li> <li><a href="#_using_attributes_and_variables">Using Attributes and Variables</a></li> <li><a href="#_common_use_cases">Common Use Cases</a></li> <li><a href="#_best_practices">Best Practices</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_for_further_reading">For Further Reading</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Target audience:</em> Developers, technical writers, and anyone wishing to write technical documentation or rich articles.</div> <p>AsciiDoc is a lightweight markup language designed for writing structured technical documents, articles, books, or even presentations. It stands out for its readability, syntactic richness, and its ability to generate various formats (HTML, PDF, DocBook, etc.). In this article, we will explore the essential syntax of AsciiDoc and provide tips for a quick start.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_is_asciidoc">What is AsciiDoc?</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc is a document description language, similar to Markdown but more powerful. It allows for the effective structuring of text, headings, lists, tables, code blocks, and much more. Its versatility makes it a popular choice for open source project documentation, book writing, and web publishing.</p> </div> <div class="sect2"> <h3 id="_why_choose_asciidoc">Why choose AsciiDoc?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Readable and intuitive syntax.</p> </li> <li> <p>Native support for complex structures (tables, notes, admonitions, etc.).</p> </li> <li> <p>Multi-format generation (HTML, PDF, ePub, DocBook…).</p> </li> <li> <p>Easy integration with static site generators like JBake or Antora.</p> </li> <li> <p>Advanced customization with attributes and extensions.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_use_case_diagram">Use Case Diagram</h2> <div class="sectionbody"> <div class="paragraph"> <p>A use case diagram presents the main interactions between users and the system. Here is a simple example for a documentation system:</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="_mind_map_diagram">Mind Map Diagram</h2> <div class="sectionbody"> <div class="paragraph"> <p>The mind map is ideal for exploring concepts related to AsciiDoc and their relationships:</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="_flow_diagram">Flow Diagram</h2> <div class="sectionbody"> <div class="paragraph"> <p>A flow diagram describes the process of generating an AsciiDoc document:</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="_basic_structure_of_an_asciidoc_file">Basic Structure of an AsciiDoc File</h2> <div class="sectionbody"> <div class="paragraph"> <p>An AsciiDoc file generally begins with a title, optional attributes, and then the structured content. Here is a minimal example:</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="_fundamental_syntax">Fundamental Syntax</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_headings_and_sections">Headings and Sections</h3> <div class="paragraph"> <p>AsciiDoc supports several levels of headings:</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="_bold_italic_and_monospace_text">Bold, Italic, and Monospace Text</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="_bulleted_and_numbered_lists">Bulleted and Numbered Lists</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_and_images">Links and Images</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">Lien standard : https://asciidoc.org[AsciiDoc] Image : image::images/logo.png[AsciiDoc Logo]</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_code_blocks">Code Blocks</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("Hello AsciiDoc!")</p> </div> </div> <div class="sect2"> <h3 id="_tables">Tables</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="_notes_and_admonitions">Notes and Admonitions</h3> <div class="paragraph"> <p>AsciiDoc provides visual information blocks:</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="_using_attributes_and_variables">Using Attributes and Variables</h2> <div class="sectionbody"> <div class="paragraph"> <p>Custom attributes allow for the reuse of values or the configuration of behaviors:</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="_common_use_cases">Common Use Cases</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Open source project documentation (README, technical guides) - Writing books and ebooks - Automatic generation of static websites (JBake, Antora) - Technical presentations</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_best_practices">Best Practices</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Use consistent headings and an automatic table of contents (:toc:). - Favor admonitions to draw attention to key points. - Structure your files to facilitate maintenance. - Take advantage of annotated code blocks to illustrate examples.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc is a powerful and accessible tool for writing any technical documentation or structured article. Its rich syntax, combined with multi-format generation, makes it a choice ally for demanding developers and writers. Try AsciiDoc in your next project and discover the difference!</p> </div> </div> </div> <div class="sect1"> <h2 id="_for_further_reading">For Further Reading</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Official Documentation: <a href="https://asciidoc.org" class="bare">https://asciidoc.org</a> - Asciidoctor: <a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - JBake and 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>Share your experiences and tips in the comments!</p> </div> </div> </div> https://cheroliv.com/en/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="#_the_problem_nat_and_private_addresses">The problem: NAT and private addresses</a></li> <li><a href="#_step_1_identify_your_public_ip_address">Step 1: Identify your public IP address</a></li> <li><a href="#_step_2_know_the_local_ip_address_of_your_ubuntu_machine">Step 2: Know the local IP address of your Ubuntu machine</a></li> <li><a href="#_step_3_configure_port_forwarding_on_your_box">Step 3: Configure port forwarding on your box</a> <ul class="sectlevel2"> <li><a href="#_access_to_the_administration_interface">Access to the administration interface</a></li> <li><a href="#_redirection_configuration">Redirection configuration</a></li> </ul> </li> <li><a href="#_step_4_service_configuration_on_ubuntu">Step 4: Service configuration on Ubuntu</a></li> <li><a href="#_step_5_ubuntu_firewall_configuration">Step 5: Ubuntu firewall configuration</a></li> <li><a href="#_step_6_test_and_validation">Step 6: Test and validation</a> <ul class="sectlevel2"> <li><a href="#_test_from_the_local_network">Test from the local network</a></li> <li><a href="#_test_from_the_outside">Test from the outside</a></li> </ul> </li> <li><a href="#_best_practices_and_security">Best practices and security</a> <ul class="sectlevel2"> <li><a href="#_basic_securing">Basic securing</a></li> <li><a href="#_connection_monitoring">Connection monitoring</a></li> <li><a href="#_using_a_reverse_proxy">Using a reverse proxy</a></li> </ul> </li> <li><a href="#_alternatives_to_port_forwarding">Alternatives to port forwarding</a> <ul class="sectlevel2"> <li><a href="#_cloud_solutions">Cloud solutions</a></li> <li><a href="#_vps_and_reverse_proxy">VPS and reverse proxy</a></li> </ul> </li> <li><a href="#_troubleshooting">Troubleshooting</a> <ul class="sectlevel2"> <li><a href="#_common_problems">Common problems</a></li> <li><a href="#_network_debug">Network debug</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="ulist"> <div class="title">Target audience: Intermediate</div> <ul> <li> <p><strong>Assumed prerequisites</strong>: basic knowledge of Ubuntu, the terminal, basic networking concepts</p> </li> <li> <p><strong>Technical concepts</strong>: NAT, port forwarding, firewall, reverse proxy</p> </li> <li> <p><strong>System commands</strong>: terminal usage, network configuration</p> </li> <li> <p><strong>Advanced sections</strong>: monitoring, security, cloud alternatives</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_the_problem_nat_and_private_addresses">The problem: NAT and private addresses</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Problem statement: Are you developing a web application on your Ubuntu machine and want to make it accessible from outside your home network? You’ve come to the right place! In this article, we will see how to expose a local service (for example on port 8080) to the Internet by configuring port forwarding on your internet box.</div> <p>By default, your internet box uses NAT (Network Address Translation) to share a single public IP address among all devices on your home network. Your local machines use private IP addresses (192.168.x.x, 10.x.x.x, etc.) which are not routable on the Internet.</p> </div> <div class="paragraph"> <p>When you launch a service on your Ubuntu machine (for example a web server on port 8080), it is only accessible from your local network. To make it accessible from the Internet, we must configure a port redirection.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_1_identify_your_public_ip_address">Step 1: Identify your public IP address</h2> <div class="sectionbody"> <div class="paragraph"> <p>First, let’s retrieve the public IP address of your Internet connection:</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>This IP address is the one that internet users will use to access your service.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_2_know_the_local_ip_address_of_your_ubuntu_machine">Step 2: Know the local IP address of your Ubuntu machine</h2> <div class="sectionbody"> <div class="paragraph"> <p>Your Ubuntu machine has a private IP address on your local network. To find it:</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>Note this address (for example`192.168.1.100`), we will need it for the configuration.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_3_configure_port_forwarding_on_your_box">Step 3: Configure port forwarding on your box</h2> <div class="sectionbody"> <div class="paragraph"> <p>Configuration varies depending on your box model, but the principle remains the same:</p> </div> <div class="sect2"> <h3 id="_access_to_the_administration_interface">Access to the administration interface</h3> <div class="paragraph"> <p>Open your browser and go to the web interface of your box:</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>SFR Box</strong>:`192.168.1.1`</p> </li> <li> <p><strong>Bbox Bouygues</strong>:`192.168.1.254`</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_redirection_configuration">Redirection configuration</h3> <div class="paragraph"> <p>Look for the section dedicated to port forwarding (names vary):</p> </div> <div class="ulist"> <ul> <li> <p>"Port redirection"</p> </li> <li> <p>"NAT/PAT"</p> </li> <li> <p>"Port Forwarding"</p> </li> <li> <p>"Game servers"</p> </li> </ul> </div> <div class="paragraph"> <p>Create a new rule with these parameters:</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">Field</th> <th class="tableblock halign-left valign-top">Value</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Name/Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">"Ubuntu Web Service" (or another explicit name)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">External port (or public port)</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">Internal IP address</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Your Ubuntu machine’s IP (e.g.: 192.168.1.100)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Internal port (or private port)</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">Protocol</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">Status</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Enabled</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_step_4_service_configuration_on_ubuntu">Step 4: Service configuration on Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ensure that your service listens on all interfaces, not just on 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>To verify that your service is listening correctly:</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>You should see something like`0.0.0.0:8080`and not`127.0.0.1:8080`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_step_5_ubuntu_firewall_configuration">Step 5: Ubuntu firewall configuration</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu uses UFW (Uncomplicated Firewall) by default. Check its status and allow the port if necessary:</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="_step_6_test_and_validation">Step 6: Test and validation</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_test_from_the_local_network">Test from the local network</h3> <div class="paragraph"> <p>First, test the access from another machine on your local network:</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="_test_from_the_outside">Test from the outside</h3> <div class="paragraph"> <p>Now, test from the Internet using your public IP:</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>You can also use online tools such as:</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="_best_practices_and_security">Best practices and security</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_basic_securing">Basic securing</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="_connection_monitoring">Connection monitoring</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="_using_a_reverse_proxy">Using a reverse proxy</h3> <div class="paragraph"> <p>For better security and flexibility, consider using a reverse proxy like 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="_alternatives_to_port_forwarding">Alternatives to port forwarding</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_cloud_solutions">Cloud solutions</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>: temporary secure tunnel</p> </li> <li> <p><strong>Cloudflare Tunnel</strong>: free and secure solution</p> </li> <li> <p><strong>serveo.net</strong>: simple SSH tunnel</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_and_reverse_proxy">VPS and reverse proxy</h3> <div class="paragraph"> <p>For professional use, consider using a VPS with a reverse proxy pointing to your local infrastructure via VPN.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_troubleshooting">Troubleshooting</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_common_problems">Common problems</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">Problem</th> <th class="tableblock halign-left valign-top">Solution</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Service inaccessible from the outside</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Verify the port forwarding configuration and that the service listens on 0.0.0.0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">"Connection refused"</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The service is not started or is listening on 127.0.0.1 only</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">"Connection timeout"</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Firewall problem (box or Ubuntu) or misconfigured port forwarding</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Public IP changes regularly</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configure a dynamic DNS (DynDNS, No-IP, etc.)</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_network_debug">Network debug</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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Exposing a local service on the Internet requires careful configuration of port forwarding, security, and monitoring. While this approach is perfect for development or personal projects, consider more robust alternatives (VPS, CDN, cloud services) for production use.</p> </div> <div class="paragraph"> <p>The important thing is to always keep security in mind: use strong passwords, update your system regularly, and monitor access to your exposed services.</p> </div> <div class="paragraph"> <p>Feel free to share your experiences and questions in the comments!</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_the_context_bakery_gradle_plugin">The Context: Bakery Gradle Plugin</a></li> <li><a href="#_problem_1_verifying_the_wrong_mock">Problem #1: Verifying the wrong mock</a> <ul class="sectlevel2"> <li><a href="#_the_diagnosis">The diagnosis</a></li> <li><a href="#_the_solution">The solution</a></li> </ul> </li> <li><a href="#_problem_2_cascading_unfinishedstubbingexception">Problem #2: Cascading UnfinishedStubbingException</a> <ul class="sectlevel2"> <li><a href="#_the_diagnosis_2">The diagnosis</a></li> <li><a href="#_the_solution_2">The solution</a></li> </ul> </li> <li><a href="#_problem_3_the_configuration_file_does_not_exist">Problem #3: The configuration file does not exist</a> <ul class="sectlevel2"> <li><a href="#_the_diagnosis_3">The diagnosis</a></li> <li><a href="#_the_solution_3">The solution</a></li> </ul> </li> <li><a href="#_problem_4_afterevaluate_and_nullpointerexception">Problem #4: afterEvaluate and NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_the_diagnosis_4">The diagnosis</a></li> <li><a href="#_the_solution_4">The solution</a></li> </ul> </li> <li><a href="#_the_complete_solution">The complete solution</a></li> <li><a href="#_lessons_learned">Lessons learned</a> <ul class="sectlevel2"> <li><a href="#_1_verify_the_correct_mock">1. Verify the correct mock</a></li> <li><a href="#_2_avoid_nested_mocks">2. Avoid nested mocks</a></li> <li><a href="#_3_mock_evaluation_callbacks">3. Mock evaluation callbacks</a></li> <li><a href="#_4_test_path_resolution">4. Test path resolution</a></li> </ul> </li> <li><a href="#_final_test_architecture">Final test architecture</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_resources">Resources</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>While developing the Gradle plugin<strong>Bakery</strong>for my JBake blog, I encountered a seemingly simple problem: a unit test that failed with the error`Wanted but not invoked`. What seemed like a trivial bug turned out to be a perfect textbook case for understanding the subtleties of mocking with Mockito and Kotlin.</p> </div> <div class="paragraph"> <p>In this article, I will take you through a methodical debugging journey, where each solution reveals a new problem, until the final resolution.</p> </div> </div> </div> <div class="sect1"> <h2 id="_the_context_bakery_gradle_plugin">The Context: Bakery Gradle Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>The Bakery plugin is a wrapper around JBake that facilitates the publication of static sites. Here is its simplified structure:</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>The test that was failing was simple:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val project = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(project.plugins).apply(JBakePlugin::class.java) }</code></pre> </div> </div> <div class="paragraph"> <p>The error:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Wanted but not invoked: pluginContainer.apply(class org.jbake.gradle.JBakePlugin); Actually, there were zero interactions with this mock.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problem_1_verifying_the_wrong_mock">Problem #1: Verifying the wrong mock</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_diagnosis">The diagnosis</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>The problem: Mockito cannot track interactions on`project.plugins`because it is just a getter that returns the real mock`mockPluginContainer`. The verification must be done directly on the mock instance.</p> </div> </div> <div class="sect2"> <h3 id="_the_solution">The solution</h3> <div class="paragraph"> <p>Modify`createMockProject()`to return both objects:</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>And adapt the test:</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="_problem_2_cascading_unfinishedstubbingexception">Problem #2: Cascading UnfinishedStubbingException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_diagnosis_2">The diagnosis</h3> <div class="paragraph"> <p>Once the first fix was applied, a new error appeared:</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>The problematic code used the Mockito-Kotlin DSL syntax:</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="_the_solution_2">The solution</h3> <div class="paragraph"> <p>Create<strong>all</strong>mocks outside of any stubbing block, then configure them with`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>Golden Rule</strong>: Never call`mock()`inside a mock configuration block. Always create the mocks first, then configure them.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problem_3_the_configuration_file_does_not_exist">Problem #3: The configuration file does not exist</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_diagnosis_3">The diagnosis</h3> <div class="paragraph"> <p>Even with the correct mocks, the test still failed because the plugin could not find the configuration file:</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="530" height="373"> </div> </div> </div> <div class="sect2"> <h3 id="_the_solution_3">The solution</h3> <div class="paragraph"> <p>Configure the mocks so that the path resolution works:</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="604" height="189"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problem_4_afterevaluate_and_nullpointerexception">Problem #4: afterEvaluate and NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_diagnosis_4">The diagnosis</h3> <div class="paragraph"> <p>The plugin applies JBake in an`afterEvaluate`block, and accesses`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>The mock of`buildDirectory.dir()<code>returned`null</code>.</p> </div> </div> <div class="sect2"> <h3 id="_the_solution_4">The solution</h3> <div class="paragraph"> <p>Mock`afterEvaluate`so that it executes immediately, and fully configure`buildDirectory`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val mockBuildDirectory = mock<DirectoryProperty>() val buildDir = File(projectDir, "build") // Mocker dir() pour retourner un Provider valide whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // Mocker afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) // ✅ Exécution synchrone null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/after-evaluate-flow.svg" alt="after evaluate flow" width="777" height="357"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_the_complete_solution">The complete solution</h2> <div class="sectionbody"> <div class="paragraph"> <p>Here is the final`createMockProject()`function, which resolves all the problems:</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>And the final test that passes:</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="_lessons_learned">Lessons learned</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/lessons-learned.svg" alt="lessons learned" width="748" height="472"> </div> </div> <div class="sect2"> <h3 id="_1_verify_the_correct_mock">1. Verify the correct mock</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_avoid_nested_mocks">2. Avoid nested mocks</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_mock_evaluation_callbacks">3. Mock evaluation callbacks</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_test_path_resolution">4. Test path resolution</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="_final_test_architecture">Final test architecture</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/test-architecture.svg" alt="test architecture" width="707" height="598"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>What seemed to be a simple test problem turned out to be an excellent case study on:</p> </div> <div class="ulist"> <ul> <li> <p>The subtleties of Mockito with Kotlin</p> </li> <li> <p>The importance of mocking the right objects</p> </li> <li> <p>Managing asynchronous callbacks in tests</p> </li> <li> <p>Path resolution in Gradle plugins</p> </li> </ul> </div> <div class="paragraph"> <p>Methodical debugging, by understanding each layer of the problem, led to a robust and maintainable solution.</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>Tip for your tests</strong>: If you encounter "Wanted but not invoked" with Mockito, always ask yourself: 1. Am I verifying the right mock? 2. Are all my mocks created outside of configuration blocks? 3. Are my callbacks actually executing? 4. Are my paths resolving correctly?</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_resources">Resources</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/mockito/mockito-kotlin">Mockito-Kotlin Documentation</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Gradle Plugin Development Guide</a></p> </li> <li> <p><a href="https://jbake.org/">JBake Static Site Generator</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Have you encountered similar problems in your tests? Share your experience in the comments!</em></p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_what_is_the_either_monad">What is the Either monad?</a> <ul class="sectlevel2"> <li><a href="#_why_use_either">Why use Either?</a></li> </ul> </li> <li><a href="#_context">Context</a></li> <li><a href="#_the_different_approaches">The different approaches</a> <ul class="sectlevel2"> <li><a href="#_the_classic_approach_using_when">The classic approach using `when</a></li> <li><a href="#_using_fold_for_a_more_concise_approach">Using <code>fold</code> for a more concise approach</a></li> <li><a href="#_transformation_with_map_and_mapleft">Transformation with <code>map</code> and `mapLeft</a></li> <li><a href="#_error_handling_with_getorelse">Error handling with `getOrElse</a></li> <li><a href="#_side_actions_with_onleft_and_onright">Side actions with <code>onLeft</code> and `onRight</a></li> <li><a href="#_chaining_operations_with_flatmap">Chaining operations with `flatMap</a></li> <li><a href="#_bidirectional_transformation_with_bimap">Bidirectional transformation with `bimap</a></li> <li><a href="#_swap_sides_with_swap">Swap sides with `swap</a></li> <li><a href="#_using_tap_and_tapleft">Using <code>tap</code> and <code>tapLeft</code>:</a></li> <li><a href="#_using_recover">Using <code>recover</code>:</a></li> </ul> </li> <li><a href="#_practical_use_cases">Practical use cases</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_to_go_further">To go further</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><em>Reading time:</em> 12 to 15 minutes.</p> </div> <div class="paragraph"> <p><em>Target audience:</em> Intermediate to advanced Kotlin developers.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>In the world of functional programming in Kotlin, the Arrow library offers powerful tools for managing errors and alternative cases. Among these tools, the monad`Either`it is distinguished by its ability to represent two possible states: success (Right) or failure (Left). But how can we navigate effectively between these two states? This is what we will explore in this article.</p> </div> </div> </div> <div class="sect1"> <h2 id="_what_is_the_either_monad">What is the Either monad?</h2> <div class="sectionbody"> <div class="paragraph"> <p>The monad`Either`is a data structure that represents two mutually exclusive possibilities. In Kotlin with Arrow, it is often used to handle the success and failure cases of an operation, offering an elegant alternative to traditional exceptions.</p> </div> <div class="sect2"> <h3 id="_why_use_either">Why use Either?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Explicit error handling: Forces the developer to consider failure cases.</p> </li> <li> <p>Functional composition: Facilitates the chaining of operations that may fail.</p> </li> <li> <p>Type-safety : Les erreurs sont typées, ce qui aide à les gérer de manière plus précise.</p> </li> <li> <p>No exceptions: Avoid side effects and unexpected interruptions to the execution flow.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_context">Context</h2> <div class="sectionbody"> <div class="paragraph"> <p>Imagine that you are developing a REST API withhttps://spring.io/projects/spring-boot/[Spring Boot, windows=read-later] et <a href="https://kotlinlang.org/">Kotlin</a>, using the libraryhttps://arrow-kt.io/[Arrow,windows=read-later]You have a function`findOneUserByEmail`which returns a`Either<Throwable, User>`. Comment pouvez-vous traiter ce résultat de manière élégante et fonctionnelle ?</p> </div> <div class="paragraph"> <p>We have a User class:</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="_the_different_approaches">The different approaches</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_classic_approach_using_when">The classic approach using `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>This method, while simple and readable, does not take full advantage of Arrow’s functional capabilities.</p> </div> </div> <div class="sect2"> <h3 id="_using_fold_for_a_more_concise_approach">Using <code>fold</code> for a more concise approach</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`allows for defining actions for both cases (Left and Right) in a concise and elegant manner.</p> </div> </div> <div class="sect2"> <h3 id="_transformation_with_map_and_mapleft">Transformation with <code>map</code> and `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>This approach allows for transforming the values contained within Either while preserving its structure, making it ideal for more complex processing chains.</p> </div> </div> <div class="sect2"> <h3 id="_error_handling_with_getorelse">Error handling with `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`offers elegant error handling by allowing a default value to be provided.</p> </div> </div> <div class="sect2"> <h3 id="_side_actions_with_onleft_and_onright">Side actions with <code>onLeft</code> and `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>These methods allow you to perform actions on each side without modifying the Either, perfect for logging or light side effects.</p> </div> </div> <div class="sect2"> <h3 id="_chaining_operations_with_flatmap">Chaining operations with `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`is useful for chaining operations that themselves return`Either</code>, thus avoiding the`Either`nested.</p> </div> </div> <div class="sect2"> <h3 id="_bidirectional_transformation_with_bimap">Bidirectional transformation with `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`allows both the left and right sides to be transformed in a single operation.</p> </div> </div> <div class="sect2"> <h3 id="_swap_sides_with_swap">Swap sides with `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`is useful when you want to reverse the sides of a`Either</code>, for example to adapt the interface of one function to another.</p> </div> </div> <div class="sect2"> <h3 id="_using_tap_and_tapleft">Using <code>tap</code> and <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 to`onLeft` et <code>onRight</code>, but these methods return the original Either, which is useful for chaining operations.</p> </div> </div> <div class="sect2"> <h3 id="_using_recover">Using <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>This method allows you to transform an Either.Left into an Either.Right by providing a replacement value.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_practical_use_cases">Practical use cases</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Use`fold`for simple operations requiring case-by-case processing. - Prefer`map` et <code>mapLeft`for data transformations without changing the structure of the`Either</code>. - Opt for`flatMap`when chaining operations that may fail. - Use`recover`to provide a default value in case of an error. - Choose`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) for side effects such as logging. - Use`bimap`to transform both sides into a single operation. - Apply`swap`when you need to adapt the interface of one function to another.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Each of these approaches has its advantages depending on the context of use. Methods such as`fold`, <code>map</code>/<code>mapLeft</code>, et `recover`are particularly useful when you want to chain multiple operations or transform data in a functional manner.</p> </div> <div class="paragraph"> <p>The monad`Either`Arrow offers remarkable flexibility for handling success and error cases in your Kotlin applications. By mastering these different approaches, you will be able to write more robust, readable, and functional code.</p> </div> <div class="paragraph"> <p>In your next project, feel free to explore these techniques to get the most out of functional programming with Kotlin and Arrow!</p> </div> </div> </div> <div class="sect1"> <h2 id="_to_go_further">To go further</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Official Arrow documentation:https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[Arrow Either]- Kotlin Coroutines with Arrow:https://arrow-kt.io/docs/fx/[Arrow Fx Coroutines]</p> </li> </ul> </div> <div class="paragraph"> <p>Don’t forget to share your experiences and favorite techniques for working with`Either` dans les commentaires ci-dessous !</p> </div> </div> </div> https://cheroliv.com/en/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="#_introduction">Introduction</a></li> <li><a href="#_using_the_find_command">Using the <code>find</code> command</a> <ul class="sectlevel2"> <li><a href="#_additional_options_for_find">Additional options for `find</a></li> </ul> </li> <li><a href="#_using_the_locate_command">Using the <code>locate</code> command</a></li> <li><a href="#_using_the_grep_command_to_search_for_text_in_files">Using the <code>grep</code> command to search for text in files</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><em>Reading time:</em> 5 to 7 minutes.</p> </div> <div class="paragraph"> <p><em>Audience:</em> Beginners and intermediates.</p> </div> <div class="paragraph"> <p>The problem: Searching for files in a Linux operating system via the terminal.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>In this article, we will explore how to search for a file under Ubuntu using a Zsh terminal. Zsh (Z shell) is a powerful command-line interpreter widely used for its flexibility and advanced features.</p> </div> <div class="paragraph"> <p>Ubuntu, a popular Linux distribution, offers several command-line tools for searching for files. We will see how to use commands such as`find`, <code>locate</code> et `grep`to locate files quickly and efficiently in the terminal.</p> </div> </div> </div> <div class="sect1"> <h2 id="_using_the_find_command">Using the <code>find</code> command</h2> <div class="sectionbody"> <div class="paragraph"> <p>The order`find`allows you to search for files in a specific directory and its subdirectories. Its basic syntax is as follows:</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>Here is a practical example where we are looking for a file named`example.txt`in the directory`/home`(No text provided for translation)</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>This command will traverse all subdirectories of`/home`and display the full path of the file if it is found.</p> </div> <div class="paragraph"> <p>*Online Ordering Manual`find`(The text to translate was not provided. Please provide the French text.)<a href="https://man.archlinux.org/man/find.1.fr/">man find</a>Please provide the text you would like me to translate.</p> </div> <div class="sect2"> <h3 id="_additional_options_for_find">Additional options for `find</h3> <div class="paragraph"> <p>The order`find`is very powerful and has many options. Here are some useful examples:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Search by file type</strong>To search for files only, use`-type f`, and to search for directories, use`-type d`. -<strong>Search by size</strong>You can also filter files by size using the option`-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="_using_the_locate_command">Using the <code>locate</code> command</h2> <div class="sectionbody"> <div class="paragraph"> <p>The order`locate`is faster than`find`because it uses a pre-indexed database of the files present on the system. You must first update this database with the following command:</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>Next, you can search for a file like this:</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>I usehttps://fr.wikipedia.org/wiki/Z_Shell[zsh]withhttps://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], it turns out that the order`locate`is not accessible from`zsh`but quite possible since`bash`, to remedy this, the argument`-c`of the order`bash`allows you to run a command`bash`from another type of terminal.</p> </div> <div class="paragraph"> <p>Here I am looking for the files that end with the pattern`001.pdf`in the user directory</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">bash -c "locate ~/*001.pdf"</code></pre> </div> </div> <div class="paragraph"> <p><strong>Online Ordering Manual`locate`(The text to translate is empty).https://man.archlinux.org/man/locate.1.fr/[man locate,windows=read-later]</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_using_the_grep_command_to_search_for_text_in_files">Using the <code>grep</code> command to search for text in files</h2> <div class="sectionbody"> <div class="paragraph"> <p>If you want to search for a specific text within a file, you can use`grep`For example, to search for the occurrence of the word "Ubuntu" in all files`.txt`from the current directory, 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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Searching for files under Ubuntu via a Zsh terminal can be done using several powerful tools.`find`is flexible and offers a multitude of options, while`locate`allows for a quick search using a pre-built database. Finally,`grep`allows you to find text occurrences within files.</p> </div> <div class="paragraph"> <p>These commands offer you a complete range of tools to make your file searches more efficient and tailored to your needs, and each of these commands has a manual accessible via the command.<code>man</code></p> </div> </div> </div> https://cheroliv.com/en/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="#_the_keyboard">The keyboard:</a> <ul class="sectlevel2"> <li><a href="#_the_ctrl_key">the <Ctrl> key</a></li> </ul> </li> <li><a href="#_permission_authorization">Permission (authorization)</a></li> <li><a href="#_file_search">File Search</a></li> </ul> </div> <div class="sect1"> <h2 id="_the_keyboard">The keyboard:</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_the_ctrl_key">the <Ctrl> key</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>+https://blogmotion.fr/systeme/astuces-bash-linux-16175[another link]</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_permission_authorization">Permission (authorization)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD is used to change the permissions of a file.</p> </div> <div class="paragraph"> <p>PERMISSION COMMAND</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 = User G = Group W = World</p> </div> <div class="paragraph"> <p>r = readable w = writable x = executable - = no permission</p> </div> <div class="paragraph"> <p>Another way to look at permissions:</p> </div> <div class="paragraph"> <p>400 read by owner 040 read by group 004 read by anybody (other) 200 write by owner 020 write by group 002 write by anybody 100 execute by owner 010 execute by group 001 execute by anybody</p> </div> <div class="paragraph"> <p>To obtain a combination, simply add them together. For example, to be read, written, and executed by the owner, read and executed by the group, and executed by anyone, you would add 400+200+100+040+010+001 to get 751.</p> </div> </div> </div> <div class="sect1"> <h2 id="_file_search"><a href="/blog/2024/0074_seach_file_linux_post.html">File Search</a></h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/en/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 <div class="paragraph"> <p><em>Reading time: 10 sec</em></p> </div> <div class="paragraph"> <p>The problem: How to expose port 8820 of the Ubuntu subsystem where the host is Windows? Ubuntu is started by the command`wsl --install`.</p> </div> <div class="paragraph"> <p>Reference:https://www.it-connect.fr/wsl-2-port-forwarding-comment-acceder-a-sa-machine-virtuelle-a-distance/[wsl-2-port-forwarding]</p> </div> https://cheroliv.com/en/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"> <p><em>Reading time: 3 min</em> Pandoc, a universal document converter</p> </div> <div class="paragraph"> <p>Pandoc is an open-source word processing software that can be used to convert documents between different formats. There are several ways to install Pandoc.</p> </div> </div> </div> <div class="sect1"> <h2 id="_installation_from_the_download_page"><strong>Installation from the download page</strong></h2> <div class="sectionbody"> <div class="paragraph"> <p>To install Pandoc from the download page, proceed as follows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Go to the Pandoc download page:https://pandoc.org/installing.html/[<a href="https://pandoc.org/installing.html" class="bare">https://pandoc.org/installing.html</a>]</p> </li> <li> <p>Download the package installer for your operating system.</p> </li> <li> <p>Run the installer to install Pandoc.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Installation from a zip file</strong></p> </div> <div class="paragraph"> <p>To install Pandoc from a zip file, proceed as follows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Download the zip file containing the Pandoc binaries and documentation.</p> </li> <li> <p>Unzip the zip file.</p> </li> <li> <p>Move the binaries to a directory of your choice.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Installation using Chocolatey</strong></p> </div> <div class="paragraph"> <p>To install Pandoc using Chocolatey, proceed as follows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Open a command prompt.</p> </li> <li> <p>Run the following command:</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>Installation using winget</strong></p> </div> <div class="paragraph"> <p>To install Pandoc using winget, proceed as follows:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Open a command prompt.</p> </li> <li> <p>Run the following command:</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>Recommendations</strong></p> </div> <div class="paragraph"> <p>By default, Pandoc creates PDFs using LaTeX. It is recommended to install LaTeX via MiKTeX. With the option`--pdf-engine`however, you can specify other programs for this task.</p> </div> <div class="paragraph"> <p><strong>Warning</strong></p> </div> <div class="paragraph"> <p>Using multiple installation methods may result in two separate installations of Pandoc. It is recommended to properly uninstall Pandoc before switching to an alternative installation method.</p> </div> <div class="paragraph"> <p><strong>Installation on Linux via WSL</strong></p> </div> <div class="paragraph"> <p>Check if the version of pandoc in your package manager is outdated. Pandoc can be found in the repositories of Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, gentoo, and Void.</p> </div> <div class="paragraph"> <p>To get the latest version, we offer a binary package for the amd64 architecture on the download page.</p> </div> <div class="paragraph"> <p>The executable is statically linked and has no dynamic dependencies or dependencies on external data files. Note: due to static linking, the pandoc binary in this package cannot use Lua filters that require external Lua modules written in C.</p> </div> <div class="paragraph"> <p>A tarball and a deb installer are provided. To install the 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>Example at the time of writing:</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`is the path to the downloaded deb. This will install the executable`pandoc`and the man page.</p> </div> <div class="paragraph"> <p>If you are using an RPM-based distribution, you may be able to install the deb from our download page using alien.</p> </div> <div class="paragraph"> <p>On any distribution, you can install from the tarball in`$DEST`(for example,<code>/usr/local/</code> ou <code>$HOME/.local</code>) by doing:</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`is the path to the downloaded zipped tarball. For versions of Pandoc prior to 2.0, which do not provide a tarball, try instead:</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>Vous pouvez également installer à partir de la source, en utilisant les instructions ci-dessous sous <code>Compilation à partir de la source</code>. Notez que la plupart des distributions ont la plate-forme Haskell dans leurs dépôts de paquets. Par exemple, sur Debian/Ubuntu, vous pouvez l’installer avec</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>By default, Pandoc creates PDFs using LaTeX. We recommend installing TeX Live via your package manager. (On Debian/Ubuntu,<code>apt-get install texlive</code>). With the option`--pdf-engine`however, you can specify other programs for this task.</p> </div> </div> </div> https://cheroliv.com/en/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"> <p><em>Reading time: 2 min</em> Create a complete implementation of the kotlin.Triple class in JavaScript, TypeScript, and Python using functional programming.</p> </div> <div class="paragraph"> <p><strong>Note:</strong>The types`Maybe`, <code>Either</code>, `Result`are not part of the base language in JavaScript or TypeScript, so we must implement them ourselves.</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>To create a Python implementation using`pydantic`for type validation and`pymonad`for monads:</p> </div> <div class="paragraph"> <p>Install dependencies:</p> </div> <div class="listingblock"> <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="paragraph"> <p>In this example:</p> </div> <div class="ulist"> <ul> <li> <p><code>pydantic`to define the class`Triple`with typed fields. - The method`divide_by`uses the monad`Either</code> de `pymonad`to handle potential errors resulting from division by zero. - Custom validation to ensure that the value of`b`is not equal to zero. If it is equal to zero, an exception is thrown, and`pymonad`catch this exception to return a result`Left`indicating the error.</p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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="_table_of_contents">Table of Contents</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>reading time: 30 min</em></p> </div> <div class="ulist"> <ul> <li> <p>Introduction</p> </li> <li> <p>Basic structure in Google Apps Script</p> </li> <li> <p>Types and Variables in Google Apps Script</p> </li> <li> <p>Constants, Variables, and Letters in Google Apps Script</p> </li> <li> <p>Operations and Operators in Google Apps Script</p> </li> <li> <p>Var, Let and Const in Google Apps Script</p> </li> <li> <p>Control Structures in Google Apps Script</p> </li> <li> <p>Loops in Google Apps Script</p> </li> <li> <p><a href="#_objects_in_google_apps_script">Objects in Google Apps Script</a></p> </li> <li> <p>Functions in Google Apps Script</p> </li> <li> <p>Parameters and Scopes in Google Apps Script</p> </li> <li> <p>Rest and Propagation Operators in Google Apps Script</p> </li> <li> <p><a href="#Assignment by Decomposition in Google Apps Script">[Assignment by Decomposition in Google Apps Script]</a></p> </li> <li> <p>Collections and Declarative Programming in Google Apps Script</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script (GAS) is a scripting development platform associated with various Google services such as Google Sheets, Google Docs, and Google Forms. It allows for the automation of tasks, the addition of custom features, and the integration of Google services.</p> </div> <div class="paragraph"> <p>In this memo, we will explore the primary concepts of Google Apps Script using concrete examples. We will cover notions such as variables, loops, functions, and many others, adapting them to the specific context of GAS.</p> </div> </div> </div> <div class="sect1"> <h2 id="_basic_structure_in_google_apps_script">Basic structure in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>To begin, let’s examine the basic structure of a Google Apps script.</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="_types_and_variables_in_google_apps_script">Types and Variables in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script uses JavaScript as its programming language. Data types and variables work similarly to standard JavaScript.</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="_operations_and_operators_in_google_apps_script">Operations and Operators in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>The operations and operators in Google Apps Script are the same as in 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_and_const_in_google_apps_script">Var, Let and Const in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>In GAS, the concepts of`var`, <code>let</code>, et `const`are used to declare variables. However, it is essential to understand their differences and implications.</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="_control_structures_in_google_apps_script">Control Structures in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Control structures such as`if`, <code>else</code>, <code>while</code> et `for`are used to manage the execution flow in 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="_parameters_and_scopes_in_google_apps_script">Parameters and Scopes in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Parameters and scopes play a crucial role in developing GAS scripts. Understand how they work to avoid unexpected behavior.</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="_constants_variables_and_letters_in_google_apps_script">Constants, Variables, and Letters in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Understanding the difference between`const`, <code>var</code>, et `let`is essential for the effective use of variables in 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="_loops_in_google_apps_script">Loops in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Loops, such as`for` et <code>while</code>, are essential for iterating over elements and performing repetitive operations.</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="_objects_in_google_apps_script">Objects in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Objects are used to structure data. In GAS, many built-in objects facilitate interaction with Google services.</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="_constants_variables_and_letters_in_google_apps_script_2">Constants, Variables, and Letters in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Understanding the difference between`const`, <code>var</code>, et `let`is essential for the effective use of variables in 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="_functions_in_google_apps_script">Functions in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Functions are fundamental elements in programming. In GAS, they can be declared and called in different ways.</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="_pause_and_propagation_operators_in_google_apps_script">Pause and Propagation Operators in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>The rest operators (<code>…​</code>) and propagation (<code>…​</code>) are useful for manipulating arrays and objects concisely.</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="_destructuring_assignment_in_google_apps_script">Destructuring Assignment in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Destructuring assignment is a powerful feature that allows for the concise extraction of values from objects and arrays.</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="_collections_and_declarative_programming_in_google_apps_script">Collections and Declarative Programming in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script supports data structures such as arrays, as well as functional programming concepts and declarative (vs. imperative) iteration, such as`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="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>This memo covered the fundamental concepts of Google Apps Script, illustrating them with concrete code examples. Use this knowledge to automate your daily tasks, customize your documents, and take full advantage of the features of Google Apps Script.</p> </div> </div> </div> https://cheroliv.com/en/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>Duration: 30 minutes</p> </div> </div> </div> <div class="sect1"> <h2 id="_objectives">Objectives</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Understand the basics of Google Apps Script in Forms - Learn how to access the script editor and execute a command via a trigger</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_time_out">Time-out</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Introduction to Google Form Script</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Quick overview of Google Form Script - Presentation of the main features</p> </li> </ul> </div> </li> <li> <p><strong>Creation of a Google Form and an associated Script</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Creating a simple form with Google Forms - Introduction to the associated script editor</p> </li> </ul> </div> </li> <li> <p><strong>Execute an instruction</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>"On start" trigger configuration - "On submit" trigger configuration - Writing a script to execute an instruction - Quick tests to verify correct operation in the log</p> </li> </ul> </div> </li> <li> <p><strong>Analysis of Results and Best Practices</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Verification of the results of executing an instruction - Discussion on a script example and how automation can save time</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_prerequisites">Prerequisites</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Have a Google account and access to Google Forms and Google Sheets</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_equipment">Equipment</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Computer with a web browser and internet connection</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_note">Note</h2> <div class="sectionbody"> <div class="paragraph"> <p>This express training provides a quick introduction to automation with Google Form Script. For a more in-depth understanding, longer training courses are recommended.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_introduction_to_google_form_script">1 - Introduction to Google Form Script</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_quick_overview_of_google_form_script">Slide 1: Quick Overview of Google Form Script</h3> <div class="ulist"> <ul> <li> <p>Google Form Script is a scripting platform integrated into Google Forms. - It allows for the addition of custom features and the automation of tasks.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_2_presentation_of_main_features">Slide 2: Presentation of main features</h3> <div class="ulist"> <ul> <li> <p>Script Editor: The built-in script editor for writing Google Apps Script scripts. - Triggers: Events such as "on submit" that activate the execution of scripts.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_3_advantages_of_using_google_form_script">Slide 3: Advantages of using Google Form Script</h3> <div class="ulist"> <ul> <li> <p>Customization: Create custom forms with unique features. - Automation: Automate actions in response to form submissions. - Integration: Integrate scripts with other Google services for a richer experience.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_note_for_the_presenter">Note for the presenter:</h3> <div class="paragraph"> <p>These features offer considerable potential for customizing and automating forms. The remainder of this training will explore the creation of specific scripts and automations in more detail.</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr</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="_creating_a_google_form_and_an_associated_script_5_min"><strong>Creating a Google Form and an Associated Script</strong> (5 min)</h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/en/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="_install_python_on_windows">Install python on windows</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">python on 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="_running_python">Running python</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Reference:</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="_install_requirement">install requirement</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="_initiation">initiation</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">python OOP</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_gof_design_patterns_in_python">GoF Design Patterns in Python</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">implementation 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">implementation 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">complete book</a></p> </div> <div class="paragraph"> <p>GoF design patterns are a set of 23 design patterns that were described in the book "Design Patterns: Elements of Reusable Object-Oriented Software".</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Here is a list of GoF design patterns</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">Name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Factory Method</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Creates objects without specifying the exact class to be instantiated.</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">Creates families of related or dependent objects without specifying their concrete class.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Builder</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Separates the construction of a complex object from its representation so that the same construction process can create different representations.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Prototype</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Creates new objects by copying an existing prototype.</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">Restricts the instantiation of a class to a single object.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Adapter</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Converts the interface of a class into another interface that the client expects.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Bridge</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Decouples an abstraction from its implementation so that the two can vary independently.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Composite</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Composes objects into tree structures to represent part-whole hierarchies.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Decorator</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dynamically attaches additional responsibilities to an object.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Facade</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Provides a unified interface to a set of interfaces in a subsystem.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Flyweight</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reduces the cost of creation and use of lightweight objects.</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">Provides a surrogate or placeholder for another object to control access to it.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Chain of Responsibility</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Allows more than one object to handle a request.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Command</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Encapsulates a request in an object, thereby allowing clients to be parameterized with different requests, queues, or logs, and to support undoable operations.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Interpreter</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gives a representation of a language’s grammar and uses this representation to interpret sentences in that language.</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">Provides a way to sequentially access the elements of an aggregate object without exposing its underlying representation.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mediator</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reduces complex dependencies between objects by making them communicate only via a mediator object.</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">Provides the ability to restore an object to its previous state (without violating encapsulation).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Observer</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Defines a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>State</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Allows an object to change its behavior when its internal state changes.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Strategy</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Defines a family of algorithms, encapsulates each of them, and makes them interchangeable.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Template Method</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Defines the skeleton of an algorithm in a method, deferring some steps to subclasses.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Visitor</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Allows defining a new operation to be performed on a structure of objects without changing the classes of the objects on which it operates.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_functional_programming">Functional programming</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">Library</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/jasondelaat/pymonad" class="bare">https://github.com/jasondelaat/pymonad</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad is an implementation of monadic data structures in Python based on programming languages such as Haskell and F# with implementations for the most commonly used monad types in functional programming.https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[article]</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 is a Python library for functional programming that provides tools for working with pure functions and iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://toolz.readthedocs.io/en/latest/" class="bare">https://toolz.readthedocs.io/en/latest/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz is a Python library for functional programming that provides tools for working with pure functions and iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/kachayev/fn.py" class="bare">https://github.com/kachayev/fn.py</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py is a Python library for functional programming that provides tools for working with pure functions and iterables.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coconut</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 adds several features to Python for functional programming, including pattern matching.https://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[conversation sof]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_side_effects">side effects</h3> </div> <div class="sect2"> <h3 id="_loops">loops</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/en/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/en/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/en/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>GitHub repository:https://github.com/cheroliv/ts-codebase[ts-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_ts"><span class="underline">Intro typescript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">Types in TypeScript</a></p> </li> <li> <p>functions</p> </li> <li> <p><a href="#data_struct">Data structure</a></p> </li> <li> <p><a href="#enums_tuples">Enums and tuples</a></p> </li> <li> <p><a href="#void_never">Void and Never</a></p> </li> <li> <p><a href="#class_interface">Classes and interfaces</a></p> </li> <li> <p><a href="#tsconfig">The tsconfig.json file</a></p> </li> <li> <p><a href="#modules">Modules</a></p> </li> <li> <p>promises</p> </li> <li> <p><a href="#async-await">async/await</a></p> </li> <li> <p><a href="#generics">Credits</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">Types in 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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">Functions</h2> <div class="sectionbody"> <div class="paragraph"> <p>Functions are reusable blocks of code.</p> </div> <div class="paragraph"> <p>Example of dimension:</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">Data structure</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">Enums and tuples</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="void_never">Void and 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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">Classes and 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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">The tsconfig.json file</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">Modules</h2> <div class="sectionbody"> <div class="paragraph"> <p>Modules allow the code to be organized into multiple files.</p> </div> <div class="paragraph"> <p>Example of rating:</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="promises">Promises</h2> <div class="sectionbody"> <div class="paragraph"> <p>Promises are used to perform asynchronous operations.</p> </div> <div class="paragraph"> <p>Example of rating:</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>async/await simplifies promise management.</p> </div> <div class="paragraph"> <p>Example of rating:</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">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generics">Credits</h2> <div class="sectionbody"> <div class="paragraph"> <p>Generics allow for the creation of reusable components with dynamic types.</p> </div> <div class="paragraph"> <p>Example of rating:</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/en/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">Table of contents</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">Good links</a></p> </li> <li> <p><a href="#repo">Repository and code sample</a></p> </li> <li> <p><a href="#toc_start"><span class="underline">CSS Start</span></a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">Good links</h3> <div class="paragraph"> <p><a href="#toc">Table of contents</a></p> </div> </div> <div class="sect2"> <h3 id="repo">Repository and code sample</h3> <div class="paragraph"> <p>GitHub repository:https://github.com/cheroliv/css-codebase[css-codebase, window = "_blank]</p> </div> </div> <div class="sect2"> <h3 id="toc_start"><span class="underline">CSS Start</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#start_intro">[start_intro]</a></p> </li> <li> <p><a href="#start_texts">[start_texts]</a></p> </li> <li> <p><a href="#background_start">[background_start]</a></p> </li> <li> <p><a href="#start_boxes">[start_boxes]</a></p> </li> <li> <p><a href="#flexbox_start">Flexbox</a></p> </li> <li> <p><a href="#grid_start">Grid</a></p> </li> <li> <p><a href="#abs_start_pos">[abs_start_pos]</a></p> </li> <li> <p><a href="#responsive_start">[responsive_start]</a></p> </li> <li> <p><a href="#start_conclusion">Debug & Conclusion</a></p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">Table of contents</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="intro_start">Intro & Setup</h2> <div class="sectionbody"> <div class="paragraph"> <p>Intro based on this video:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/iSWjmVcfQGg?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> <div class="paragraph"> <p>GitHub repository:https://github.com/cheroliv/css-codebase/début_css/[start css, window = "_blank]</p> </div> <div class="paragraph"> <p>memo source: + 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>Link the style.css file to the html page:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"></head> <link rel="stylesheet" href="style.css" /> </head></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">The texts</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_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start_background">Background</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; /* 100VH = 100% de la taille de l'écran (viewport height) min afin de ne pas bloquer la possibilité d'avoir un plus grand */ min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_boxes">The 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_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="flexbox_start">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_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="grid_start">Grid</h2> <div class="sectionbody"> <div class="paragraph"> <p>To distribute elements in a slightly more complex manner than with flexbox, using a grid system, among others.</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_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">Absolute position</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_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start_responsive">Responsive</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; /* pour etre plus responsive on peut passer la taille en vw(view port width) pour qu'elle s'adapte à la taille de l'ecran*/ font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; /* permet en media query de la centrer en petit écran*/ display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } .absolute { position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: translateX(-50%); top: 100px; } /* RESPONSIVE: a partir des tailles d'ecran permet de surcharger les reglages definis plus haut */ @media screen and (max-width: 900px) { .grid-container { display: block; } .grid-container img { width: 40%; } } @media screen and (max-width: 610px) { .flexbox ul { flex-direction: column; align-items: center; } form { grid-template-columns: 1fr; grid-template-rows: 1fr; grid-template-areas: "i1" "i2" "ta" "bt"; } input, textarea { font-size: 0.8rem; } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start_conclusion">Debug & Conclusion</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* all elements: supprime les comportements par défaut*/ * { /* les marges à zéro*/ margin: 0; /* les parge internes(padding) à zéro*/ padding: 0; /* tous les bords avec un cadre rouge de 2px. qui est ou et qui fait quoi...*/ border: 2px solid red; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_start"><span class="underline">CSS Start</span></a></p> </div> </div> </div> https://cheroliv.com/en/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="#_good_links">Good links</a></li> <li><a href="#_repository_and_code_sample">Repository and code sample</a></li> </ul> </div> <div class="sect1"> <h2 id="_good_links">Good 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>: HTML Cheatsheet</p> </li> </ul> </div> <div class="ulist"> <div class="title">font</div> <ul> <li> <p><a href="https://fontawesome.com" target=""_blank">fontawesome.com</a>: icon library</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a>: Native HTML icons</p> </li> </ul> </div> <div class="paragraph"> <p>special characters and escapes</p> </div> <div class="ulist"> <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="_repository_and_code_sample">Repository and code sample</h2> <div class="sectionbody"> <div class="paragraph"> <p>GitHub repository:https://github.com/cheroliv/html-codebase[html-codebase, window = "_blank]</p> </div> <div class="paragraph"> <p>memo source: + 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/en/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>GitHub repository:https://github.com/cheroliv/js-codebase[js-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">Intro Javascript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p>Please provide the text you would like me to translate.</p> </li> <li> <p><a href="#arrays">Arrays</a></p> </li> <li> <p><a href="#functions">The functions</a></p> </li> <li> <p><a href="#param_x_scope">Settings and scopes</a></p> </li> <li> <p>objects</p> </li> <li> <p>loops</p> </li> <li> <p><a href="#const_var_let">Const, var and let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">Rest and spread operators</a></p> </li> <li> <p>destructuring</p> </li> <li> <p>import_export</p> </li> <li> <p><a href="#classes">Use of classes</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start">Variables, arithmetic operators and strings</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">The functions</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">Settings and scopes</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">The objects</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objects.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les objects */ var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; var hugo = { firstName: authors[7][0], lastName: authors[7][1], country: authors[7][2], }; var book = { author: hugo, title: "Les misérables" }; console.log(hugo); console.log(book); //accéder à un membre de l'objet par point console.log(hugo.country); //accéder à un membre de l'objet par crochet console.log(book["title"]); console.log(book.author.lastName); console.log(book["author"]["firstName"]); //ajouter une clé a un objet hugo.gender = "non binary"; console.assert(hugo.gender === "non binary"); //mettre à jour une clé hugo.gender = "male"; console.assert(hugo.gender !== "non binary"); console.assert(hugo["gender"] === "male"); //supprimer une clé delete hugo.gender; //verfier que l'objet ne contient pas la clé gender console.assert(!Object.keys(hugo).includes("gender")); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="_the_loops">The loops</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var and 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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">Rest and spread operators</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">Destructuring</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">Import and export of modules</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">Intro Javascript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">Use of 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">Intro Javascript</span></a></p> </div> </div> </div> https://cheroliv.com/en/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="_scoping">scoping</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_workshop_1_vision">Workshop 1: Vision</h3> <div class="sect3"> <h4 id="_1_the_qqoqcp_pattern_who_what_where_when_how_why">1. The “QQOQCP” pattern – Who, What, Where, When, How, Why</h4> </div> <div class="sect3"> <h4 id="_2_the_product_vision_board">2. The Product Vision Board</h4> <div class="sect4"> <h5 id="_target_group">Target Group</h5> <div class="paragraph"> <p>Who are the users who use the product or offer? (direct, indirect)</p> </div> </div> <div class="sect4"> <h5 id="_needs">Needs</h5> <div class="paragraph"> <p>What are the 5 primary needs of the application’s key users?</p> </div> </div> <div class="sect4"> <h5 id="_product">Product</h5> <div class="paragraph"> <p>What is my value proposition? What are the 5 main features of the product that address the needs</p> </div> </div> <div class="sect4"> <h5 id="_business_goal">Business Goal</h5> <div class="paragraph"> <p>What are the success criteria?</p> </div> </div> <div class="sect4"> <h5 id="_vision">Vision</h5> <div class="paragraph"> <p>When the 4 columns are complete, you will need to fill in the vision part of the Product Vision Board in one complete sentence.</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_workshop_2_personasuser_journeys">Workshop 2: Personas/User Journeys</h3> <div class="paragraph"> <p>Define a user journey for each persona:</p> </div> <div class="ulist"> <ul> <li> <p>Who will use my service? (Target)</p> </li> <li> <p>What do they want to do? (Goal)</p> </li> <li> <p>How will they do it? (User Journey)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_workshop_3_zoning_storyboard_sitemap">Workshop 3: Zoning, Storyboard, Sitemap</h3> <div class="sect3"> <h4 id="_1_zoning">1. Zoning</h4> </div> <div class="sect3"> <h4 id="_2_storyboard">2. StoryBoard</h4> </div> <div class="sect3"> <h4 id="_3_sitemap">3. SiteMap</h4> </div> </div> <div class="sect2"> <h3 id="_workshop_4_wireframemoodboard">Workshop 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="_workshop_5_story_mapping_user_stories">Workshop 5: Story Mapping/ User stories</h3> <div class="sect3"> <h4 id="_story_mapping_us_prioritization">Story mapping (US prioritization)</h4> </div> <div class="sect3"> <h4 id="_as_a_user_type_i_want_a_goal_so_that_a_reason">As a <user type>, I want <a goal> so that <a reason>.</h4> </div> </div> <div class="sect2"> <h3 id="_workshop_6_backlog">Workshop 6: Backlog</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">backlogs</a></p> </div> </div> <div class="sect2"> <h3 id="_workshop_7_technique_and_architecture">Workshop 7: Technique and Architecture</h3> </div> </div> </div> https://cheroliv.com/en/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="_good_links">Good links</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">kotlinlang playground</a>+</p> </div> <div class="paragraph"> <p><a href="https://arrow-kt.io/">arrow.kt</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/MVIKotlin/">MVI:Model View Intent</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">Essenty</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">Decompose</a>+</p> </div> </div> </div> <div class="sect1"> <h2 id="_miscellaneous_code_snippets">Miscellaneous code snippets</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_map_reduce">map reduce</h3> <div class="paragraph"> <p>Convert a list of bytes to a list of strings and summarize the list of strings<br> into a string containing the concatenation. How to log the sent request(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_and_sealed_classes">enum and sealed classes</h3> <div class="paragraph"> <p>post:<a href="0038_training_kotlin_enum_sealed_class_post" target="_blank" rel="noopener">training kotlin enum sealed class</a></p> </div> </div> <div class="sect2"> <h3 id="_functional_interface_and_method_reference">functional interface and method reference</h3> <div class="paragraph"> <p>An entity can be transformed into a domain model or dto using a method reference(functional style- 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>ahttps://stackoverflow.com/a/22245383/837404[good explanation]</p> </div> </div> <div class="sect2"> <h3 id="_capturing_standard_output">Capturing standard output</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="_what_is_the_difference_in_kotlin_between_apply_run_let_also_use_and_with">What is the difference in kotlin between apply, run, let, also, use and with ?</h3> <div class="paragraph"> <p><strong>Comparison of Kotlin functions and Use of Lambda Reference Forms</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_apply">apply</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Introduction Kotlin functions`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`offer different ways to handle objects. Each has its own use cases and behaviors. Furthermore, lambda reference forms allow the code to be more readable and reusable by referencing existing lambda functions.</div> <p>The function`apply`is used to configure an object during its creation. It returns the object it was called on.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</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>Example with 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>The function`run`is used to execute a block of code on an object and returns the result of the code block.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</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>Example with lambda:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_let">let</h2> <div class="sectionbody"> <div class="paragraph"> <p>The function`let`is used to execute a block of code on an object and returns the result of the code block.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let(::processObject)</code></pre> </div> </div> <div class="paragraph"> <p>Example with 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="_also">also</h2> <div class="sectionbody"> <div class="paragraph"> <p>The function`also`is used to perform an additional action on an object and returns the object it was called on.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</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>Example with 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>The function`use`is used to work with resources that must be closed after use. It automatically calls the`close`function at the end of the block.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</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>Example with 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="_with">with</h2> <div class="sectionbody"> <div class="paragraph"> <p>The function`with`is used to call multiple methods on an object without repeating its name and returns the result of the last expression.</p> </div> <div class="paragraph"> <p>Example with lambda reference:</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>Example with 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>By using lambda reference forms or`{}`blocks, you can encapsulate logic into separate functions, thereby improving code readability and reusability.</p> </div> </div> </div> <div class="sect1"> <h2 id="_let_function_in_kotlin">let Function in Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Does let return the object with the side effects performed on it or in the initial input state of the function(let)?</div> <p>The`let`function in Kotlin is used to perform operations on an object and return a different result. However, it is important to note that the`let`function does not modify the initial state of the object it is called on.</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>Signature</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>Usage</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The`let`function is commonly used to apply transformations to an object and obtain a result based on those transformations.</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>Result</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">The value returned by the`let`function is the result of the lambda expression passed as an argument, generally the result of the operations performed on the object.</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>Side Effects</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Although the`let`function may have side effects on the object when used within the lambda expression, it does not modify the initial state of the object itself.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Thus, the`let`function is an elegant way to perform operations on an object while obtaining a derived result, while preserving the integrity of the original object.</p> </div> </div> </div> https://cheroliv.com/en/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">table of contents</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">strings and characters</a></p> </li> <li> <p><a href="#math">numbers and math</a></p> </li> <li> <p><a href="#date">dates and times</a></p> </li> <li> <p><a href="#java8date">java8 dates and times</a></p> </li> <li> <p><a href="#arrCol">arrays and collections</a></p> </li> <li> <p><a href="#sysProp">System.Properties</a></p> </li> <li> <p><a href="#threads">Threads</a></p> </li> <li> <p><a href="#regex">Regular Expressions</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">strings and characters</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">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="math">numbers and math</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">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">dates and times</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">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">java8 dates and times</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 introduces the new <strong><em>java.time</em></strong> package, which contains the base classes that<br> most developers work with. It also contains four sub-packages:<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> Alternative chronologies that developers using calendar systems that do not<br> follow the ISO standard will interact with. An example would be a Japanese cal<br> system.<br> <strong><em>java.time.format</em></strong><br> Contains the DateTimeFormatter used to convert date and time objects<br> into a string and also to parse strings into date and time objects.<br> <strong><em>java.time.temporal</em></strong><br> Contains the interfaces required by the base date and time classes and also<br> abstractions (such as queries and adjusters) for advanced operations with dates.<br> <strong><em>java.time.zone</em></strong><br> Classes used for the underlying time zone rules;<br> most developers will not need this package.<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">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">arrays and collections</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">table of contents</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">official System.Properties doc</a></p> </div> <div class="paragraph"> <p>here is a table of some interesting properties<br> These properties are interesting for obtaining information<br> about the JVM host system.</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>Key</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Meaning</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">Character that separates components of a file path. This is "/" on UNIX and "\" on 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">Path used to find directories and JAR archives containing class files. Elements of the class path are separated by a platform-specific character specified in the path.separator property.</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">Installation directory for Java Runtime Environment (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">JRE vendor name</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">JRE vendor URL</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">JRE version number</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">line.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sequence used by operating system to separate lines in text files</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">Operating system architecture</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">Operating system name</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">Operating system version</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">Path separator character used in 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">User working directory</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">User home directory</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">User account name</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">Threads</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">table of contents</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">Regular Expressions</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="_regex_metacharacters_table">Regex metacharacters table</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">Metacharacter</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">functionality</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Notes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Optional character—zero or one instance</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 or more of the preceding character</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">One or more of the preceding characters</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">Between M and N instances of the preceding character</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">A digit</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">A non-numeric character</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">A word character</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Digits, letters and _</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">A non-word character</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">A whitespace character</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">A non-whitespace character</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">Line break character</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">Tab character</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">Any character</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Does not include the new line in 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">Any character contained within brackets</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Called a character class</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[^ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Any character not contained within brackets</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Called an inverted character class</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Build a group of pattern elements</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Called a group (or capturing group)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Define alternative possibilities</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implements logical OR</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Start of string $ End of string</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>completehttps://www.codeurjava.com/2015/05/les-expressions-regulieres-avec-regex.html[with]</p> </div> </div> </div> </div> https://cheroliv.com/en/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="#_show_help">Show help</a></li> <li><a href="#_set_jvm_system_property_d_system_prop">Set JVM system property: <code>-D, --system-prop</code></a></li> <li><a href="#_set_project_property_for_the_build_script_pmypropmyvalue">Set project property for the build script: <code>-Pmyprop=myvalue</code></a></li> <li><a href="#_specifies_the_gradle_startup_directory_the_default_value_is_the_current_directory">Specifies the Gradle startup directory. The default value is the current directory.</a></li> <li><a href="#_override_the_param_component_property_via_the_command_line">Override the 'param_component' property via the command line:</a></li> <li><a href="#_add_a_folder_to_a_source_set_in_a_normal_project_with_kotlin_dsl">Add a folder to a source-set in a normal project with kotlin dsl</a></li> <li><a href="#_add_a_folder_to_a_source_set_in_an_android_project_with_groovy_dsl">Add a folder to a source-set in an android project with groovy dsl</a></li> <li><a href="#_avoid_building_and_testing_a_sub_module">Avoid building and testing a sub-module</a></li> <li><a href="#_tar_a_folder">Tar a folder</a></li> <li><a href="#_show_build_dependencies">Show build dependencies</a></li> <li><a href="#_example_of_using_reduce_concatenating_a_list_into_a_string">Example of using reduce: concatenating a list into a string</a></li> <li><a href="#_retrieve_the_description_of_a_specific_task">Retrieve the description of a specific task</a></li> <li><a href="#_to_run_a_task_from_the_root_workingdir_prefix_the_task_with_a">To run a task from the root workingDir, prefix the task with a <code>:</code></a></li> <li><a href="#_to_rerun_failed_tasks_use_the_rerun_tasks_option">To rerun failed tasks, use the <code>--rerun-tasks</code> option</a></li> <li><a href="#_run_a_task_in_a_specific_project_from_another_directory">Run a task in a specific project from another directory</a></li> </ul> </div> <div class="sect1"> <h2 id="_show_help">Show help</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="_set_jvm_system_property_d_system_prop">Set JVM system property: <code>-D, --system-prop</code></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="_set_project_property_for_the_build_script_pmypropmyvalue">Set project property for the build script: <code>-Pmyprop=myvalue</code></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="_specifies_the_gradle_startup_directory_the_default_value_is_the_current_directory">Specifies the Gradle startup directory. The default value is the current directory.</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="_override_the_param_component_property_via_the_command_line">Override the 'param_component' property via the command line:</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="_add_a_folder_to_a_source_set_in_a_normal_project_with_kotlin_dsl">Add a folder to a source-set in a normal project with kotlin dsl</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sourceSets { getByName("test"){ java.srcDir("src/scripts/groovy") } getByName("test"){ java.srcDir("src/scripts/kscript") } getByName("test"){ java.srcDir("src/test/javascript") } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_add_a_folder_to_a_source_set_in_an_android_project_with_groovy_dsl">Add a folder to a source-set in an android project with 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="_avoid_building_and_testing_a_sub_module">Avoid building and testing a sub-module</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">Move files</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_a_folder">Tar a folder</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="_show_build_dependencies">Show build dependencies</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="_example_of_using_reduce_concatenating_a_list_into_a_string">Example of using reduce: concatenating a list into a 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="_retrieve_the_description_of_a_specific_task">Retrieve the description of a specific task</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="_to_run_a_task_from_the_root_workingdir_prefix_the_task_with_a">To run a task from the root workingDir, prefix the task with a <code>:</code></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="_to_rerun_failed_tasks_use_the_rerun_tasks_option">To rerun failed tasks, use the <code>--rerun-tasks</code> option</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="_run_a_task_in_a_specific_project_from_another_directory">Run a task in a specific project from another directory</h2> <div class="sectionbody"> <div class="paragraph"> <p>The option`-p` (ou <code>--project-dir</code>) allows specifying the path to a Gradle project and executing a task there, even if the current directory is different.</p> </div> <div class="paragraph"> <p>For example, to run the task`build`of the project located in`~/projets/mon-autre-projet`while being in another directory:</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>This is particularly useful for scripting actions across multiple projects from a central location.</p> </div> <div class="ulist"> <div class="title">see also:</div> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_warnings">ref</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_options">ref</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">discussion</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/en/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>sealed classes are not enumerations(keyword:enum).<br> Coming from Java, you might be tempted to overload your enumeration to provide features: // Java code</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-java" data-lang="java">enum PizzaOrderStatus { ORDER_RECEIVED, PIZZA_BEING_MADE, OUT_FOR_DELIVERY, COMPLETED; public PizzaOrderStatus nextStatus() { switch (this) { case ORDER_RECEIVED: return PIZZA_BEING_MADE; case PIZZA_BEING_MADE: return OUT_FOR_DELIVERY; case OUT_FOR_DELIVERY: return COMPLETED; case COMPLETED:return COMPLETED; } } }</code></pre> </div> </div> <div class="paragraph"> <p>Instead, you can use a sealed class:</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>The advantage of this approach is that we can now pass data with the 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>In general, sealed classes are good if you want to have data associated with a State.</p> </div> https://cheroliv.com/en/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="_mind_map">Mind map</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="_functional_programming">Functional programming</h2> <div class="sectionbody"> <div class="paragraph"> <p>The exercises are taken from the book:<br> Functional programing in kotlin by tutorials<br> Written by Massimo Carli<br> repo: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_syntax">Syntax</h3> <div class="sect3"> <h4 id="_firstprogramtest">FirstProgramTest</h4> <div class="paragraph"> <p>concepts: screen display, function<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>concepts: memory, variable, value, object, function extension<br> ExampleUnitTest:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt[source]+</p> </div> </div> <div class="sect3"> <h4 id="_birthdaymessagetestoutput">BirthdayMessageTestOutput</h4> <div class="paragraph"> <p>concepts: sets, loops<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">Introduction to kotlin</a><br> BirthdayMessageTestOutput:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[source]+</p> </div> </div> </div> <div class="sect2"> <h3 id="_kotlin_course">Kotlin course</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/YRjY3jRrQYY?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_tutorial_on_collections_in_java">Tutorial on collections in java</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">Collections</a></p> </div> <div class="paragraph"> <p>The core of collection interfaces<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="Collections"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_functional_basics">Functional basics</h3> <div class="sect3"> <h4 id="_declarative_x_imperative_approach">Declarative X imperative approach</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="_exercise_1_1">Exercise 1.1</h4> <div class="paragraph"> <p>Implement the <code>sumInRange</code> function, which adds the values in<br> a <code>List<String></code> within a given interval. The signature is:</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>Try it and check your answer with thehttps://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="_higher_order_functions">Higher-order functions</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="_exercise_1_2">Exercise 1.2</h4> <div class="paragraph"> <p>Implement <code>chrono</code>, which accepts a function of type`() →`<br> <code>Unit</code> as input and returns the time spent executing it. The signature is:<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>Try it and check your answer with thehttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solution, windows="_blank"].</p> </div> </div> <div class="sect3"> <h4 id="_composition">Composition</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="_pure_functions_and_testability">Pure functions and testability</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="_exception_handling">Exception handling</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="_key_points">Key points</h3> <div class="ulist"> <ul> <li> <p>While object-oriented programming means programming with objects,</p> </li> </ul> </div> <div class="paragraph"> <p>functional programming means programming with functions. You break down a problem into several sub-problems, which you model with functions.</p> </div> <div class="ulist"> <ul> <li> <p>Higher-order functions accept other functions as input or return other</p> </li> </ul> </div> <div class="paragraph"> <p>functions as return values. Category theory is the theory of composition, and you use it to understand how to compose your functions in a working program. The output value of a pure function depends only on its input parameters, and it has no side effects.</p> </div> <div class="ulist"> <ul> <li> <p>A side effect is something a function does to the outside world. This</p> </li> </ul> </div> <div class="paragraph"> <p>could be a log in the standard output or modifying the value of a global variable. Functional programming works for pure functions, but it also provides the tools to transform impure functions into pure functions. You can make an impure function pure by moving the effects to make them part of the return value.</p> </div> <div class="ulist"> <ul> <li> <p>Functional programming is all about composition.</p> </li> </ul> </div> <div class="paragraph"> <p>Error handling is a typical case of side effects, and Kotlin gives you the tools to handle them functionally.</p> </div> </div> <div class="sect2"> <h3 id="_deepen_java8_lambda_expressions_and_functional_interfaces">Deepen java8: lambda expressions and functional interfaces</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="_category_theory">Category theory</h3> <div class="paragraph"> <p>The mathematical theory of categories:</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="_function_fundamentals">Function fundamentals</h3> <div class="sect3"> <h4 id="_exercise_2_1">Exercise 2.1</h4> <div class="paragraph"> <p>Can you write an example of a function mapping distinct values<br> from the domain to non-distinct values in the range, such as f(b) and f(c) in the figure below?<br></p> </div> <div class="paragraph"> <p>Try it, then check the challenge project for a solution to see how you did.<br> You will find tips and an explanation by following the link to the <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">solution</a>.<br></p> </div> </div> <div class="sect3"> <h4 id="_exercise_2_2">Exercise 2.2</h4> <div class="paragraph"> <p>Can you write the inverse function of twice ?<br> What are the domain and range for the inverse function?<br> Check out the challenge project and Appendix B for the solution.</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>Try it and check your answer with thehttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solution, windows="_blank"].</p> </div> </div> </div> </div> </div> https://cheroliv.com/en/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="_tools">Tools</h2> <div class="sectionbody"> <div class="dlist"> <div class="title"><strong>Illustrations</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>Open source illustrations for all the ideas you can imagine and create.</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">absurd.design</a></dt> <dd> <p>Absurd illustrations that make sense.</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>Beautiful free illustrations. Weekly updates.</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>Icons, illustrations, photos, music, and design tools.</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">blush.design</a></dt> <dd> <p>Icons, illustrations, photos, music and design tools.</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>Mix and match people illustrations with a design library.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Colors</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>The ultra-fast color palette generator!</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Trends</strong></div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">pinterest</a></dt> <dd> <p>Visual discovery of ideas: images, videos, thematic collections.</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">Dribble</a></dt> <dd> <p>Platform for designers to share their creations and interact.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI and Design Systems</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">Google Material Design</a></dt> <dd> <p>Google’s design system for unified and adaptable user interfaces.</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Apple Human Interface Guidelines</a></dt> <dd> <p>Apple’s recommendations for designing intuitive iOS and macOS applications.</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>Design and collaboration platform for creating prototypes and design systems.</p> </dd> <dt class="hdlist1"><a href="https://www.frontify.com/">Frontify</a></dt> <dd> <p>Brand management and design systems platform to ensure consistency.</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">Design Systems Repo</a></dt> <dd> <p>Collection of design system resources and examples for inspiration.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Frontend Development</strong></div> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com" target="_blank" rel="noopener">htmlcheatsheet.com</a></dt> <dd> <p>HTML Cheatsheet</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com" target="_blank" rel="noopener">fontawesome.com</a></dt> <dd> <p>icon library</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank" rel="noopener">toptal.com/designers/htmlarrows/symbols</a></dt> <dd> <p>Native HTML icons</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>Essential for CSS, with articles, tutorials and modern frontend tips.</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">Frontend Mentor</a></dt> <dd> <p>Frontend coding challenges based on real-world projects to improve your skills.</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>Developer community for sharing articles, tutorials and projects.</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">CodePen</a></dt> <dd> <p>Online code editor and community for sharing code snippets and demos.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>AI-Assisted Frontend Development</strong></div> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0 converts natural language descriptions into code and user interface.</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">Uizard</a></dt> <dd> <p>Uizard focuses on transforming mockups (images, sketches) into HTML, CSS and React code.</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI allows you to describe the interface you want in natural language, and the AI generates editable Figma designs.</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ is a low-code front-end development platform that uses AI to help you build and deploy websites visually.</p> </dd> </dl> </div> </div> </div> https://cheroliv.com/en/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/">official microk8s documentation</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_installation_of_the_microk8s_package">Installation of the microk8s package:</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/en/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/en/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, useful for testing, it allows you to know where you are and the cause of the failure. + Not yet implemented, allows raising the correct exception. + There is: http://commons.apache.org/proper/commons-lang/javadocs/api-release/org/apache/commons/lang3/NotImplementedException.html[org.apache.commons.lang3.NotImplementedException]+https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-not-implemented-error/[kotlin.NotImplementedError]</p> </div> https://cheroliv.com/en/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/en/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/en/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="_source_hackernoon_com">source: <a href="https://hackernoon.com/dont-install-postgres-docker-pull-postgres-bee20e200198">hackernoon.com</a></h4> </div> https://cheroliv.com/en/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/en/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="paragraph"> <p>Please provide the text you would like me to translate.` $ ./gradlew -Pparam_component=CUSTOM `Please provide the text you would like me to translate.</p> </div> https://cheroliv.com/en/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>Please provide the text you would like me to translate.https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[xenovation]Please provide the text you would like me to translate.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="_change_remote_repository_in_git">change remote repository in git</h4> <div class="paragraph"> <p>display the current remote repo URL:</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/en/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="paragraph"> <p>Please provide the text you would like me to translate.` $ wget -r -k -np <a href="http://site.com/docs/manual/" class="bare">http://site.com/docs/manual/</a> `Please provide the text you would like me to translate.</p> </div> <div class="paragraph"> <p>To define a target folder, add the -P argument followed by the path.</p> </div> https://cheroliv.com/en/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/en/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>If you wish to extract to a particular destination folder, you can use: ` $ unzip fichier.zip -d dossier_destination <code>Please provide the text you would like me to translate.</code> Si les répertoires source et de destination sont identiques, vous pouvez simplement faire: <code>Please provide the text you would like me to translate.</code> $ unzip file.zip `Please provide the text you would like me to translate.</p> </div> </div> https://cheroliv.com/en/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="paragraph"> <p>Please provide the text you would like me to translate.` $ du -ach --exclude "./.*" /home/troll/ `Please provide the text you would like me to translate.</p> </div> </div> https://cheroliv.com/en/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="_delete_a_branch_on_github">Delete a branch on 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/en/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"> <p>Why AsciiDoc or Markdown? In this case, I am opting for AsciiDoc, as I have already written a few tickets in AsciiDoc. + AsciiDoc is a markup language that allows for the production of content by providing a layout that keeps the text readable for humans. + It is a way to standardize word processing for simple content without needing additional software.</p> </div> <div class="paragraph"> <p>Links:</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/" target=""_blank">@jmdoudoux on 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/en/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>To install a Debian package from a .deb file using the command line.</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>see here for thehttps://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[reference]+</p> </div> https://cheroliv.com/en/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>In an application project managed by the Gradle build manager, it is more convenient to have visibility of all folders involved in the application’s development, such as resource folders that are not in the conventional paths. For example, if I want the src/jbake folder to be visible as a 'resource folder', it is possible to do so by entering the project configuration in the IDE wizards. However, this option is not saved after the next reload of the Gradle project in the IDE. To implement this configuration permanently, the solution is to override the source path configuration in the build.gradle configuration file, as seen on lines 18, 19, 20, and 21: build.gradle</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>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/en/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>The subject of the ticket is the configuration of a Gradle build script. I want to be able to use a Groovy script without referencing the Gradle project to which it is attached. I want to be able to run this Groovy script outside of Gradle without the Ivy annotations for external dependency retrieval causing performance or compilation issues for the Gradle build script. To illustrate the configuration, I am relying on two scripts: a Gradle build script and a Groovy script. At the beginning of the Groovy script, on line 2, there is an instruction to pull an external dependency using the Ivy dependency manager.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>#!/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>In the build.gradle file, let’s now see how to harmonize the two dependency managers, Ivy and Gradle. The alignment between the two is handled on lines 26, 30, 37, 38, and 39. This way, I can run my Groovy script manually, and the Gradle compilation is not hindered by @Grab. The dependencies for the Groovy script do not need to be provided in Gradle. On the other hand, I cannot run the Groovy script from Gradle.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>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>ticket reference onhttps://stackoverflow.com/a/18174033/837404[stackoverflow]</p> </div> https://cheroliv.com/en/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="_the_lcm">The LCM</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">wiki LCM or Least Common Multiple</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>result:</p> </div> <div class="paragraph"> <p>gcd(96, 28) = 4 lcm(790, 990) = 78210</p> </div> </div> https://cheroliv.com/en/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>I am searching for files by name criteria: the list of files with the .h and .cpp extensions.</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>the list of files with .h and .cpp extensions + the result is saved in the file 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>I am looking for the list of files with the .chm extension and I am destroying this list.</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/en/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="_analyze_and_gather_requirements">Analyze and gather requirements</h3> </div> <div class="sect2"> <h3 id="_defining_project_management">Defining project management</h3> </div> <div class="sect2"> <h3 id="_contextualizing_the_project">Contextualizing the project</h3> </div> <div class="sect2"> <h3 id="_analyze_and_gather_requirements_2">Analyze and gather requirements</h3> <div class="sect3"> <h4 id="_formulate_the_objectives_and_deliverables">Formulate the objectives and deliverables</h4> </div> </div> <div class="sect2"> <h3 id="_decoding_a_framework_of_analysis">Decoding a framework of analysis</h3> </div> <div class="sect1"> <h2 id="_scope_the_project_with_your_team">Scope the project with your team</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/conductor.png" alt="conductor"> </div> </div> <div class="sect2"> <h3 id="_consult_the_experts_to_find_the_solution">Consult the experts to find the solution</h3> </div> <div class="sect2"> <h3 id="_choosing_a_project_management_methodology">Choosing a project management methodology</h3> <div class="imageblock"> <div class="content"> <img src="../../img/cascading_planning.png" alt="cascading planning] image::../../img/Cycle_V_details.jpeg[V-model"> </div> </div> </div> </div> </div> https://cheroliv.com/en/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>I don’t feel like installinghttps://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a>while everything is available via the command line. + To do this, we must launch the terminal and log in as the postgres user. + The postgres user is the only one who by default has the right to launch the psql application, which is the command-line client (<a href="https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande">CLI</a>) postgresql, + to be able to communicate with the database via the command line from the terminal. + To connect, open the terminal and type the following:<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>To connect and go directly to the PostgreSQL command prompt, type the following:</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>To list the databases of a PostgreSQL instance, here is the command:</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>result:</p> </div> <div class="paragraph"> <p>List of databases Name | Owner | Encoding | Collation | Character type | Access privileges</p> </div> <div class="paragraph"> <p>fiber | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech + | | | | | tech=CTc/tech fiberdev | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech + | | | | | tech=CTc/tech fiberweb | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech + | | | | | 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 + | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres + | | | | | postgres=CTc/postgres (6 lignes)</p> </div> <div class="paragraph"> <p>Press q to exit the results display; type \dn to list the schemas of a PostgreSQL instance.</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>result</p> </div> <div class="paragraph"> <p>public information_schema pg_catalog pg_toast_temp_1 pg_temp_1 pg_toast (6 rows)</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>result</p> </div> <div class="paragraph"> <p>pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog information_schema public (6 rows)</p> </div> https://cheroliv.com/en/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>The video player on my TV has its own way of moving from one file to another during continuous playback, and its playback mode is to go from 1…​mp4 to 10…​mp4, rather than from 1…​mp4 to 2…​mp4. The problem is that there are nearly 900 files and folders. Bingo: a great use case for Groovy to manipulate files, renaming them and searching for patterns in the file or folder name. Here, the goal is to change names that start with a digit where the second character is not a digit; I will add a 0 to the beginning of such names.</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/en/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>The purpose of this script is to search for files starting from a parent directory, retrieve the selection into a list, and finally copy this list of files into a destination directory using 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/en/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>Here, I will focus on loading a property in a project build.https://docs.gradle.org/current/userguide/userguide.html[gradle]+ without it being available in the code. + The property will be defined in the gradle.properties file of the ~/.gradle/gradle.properties folder + ~ is a shortcut for the HOME_PATH symbolic variable representing the user session root: thehttps://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel[personal directory]. Similarly, in a project buildhttps://maven.apache.org/guides/index.html[maven], with ~/.m2/settings.xml. The purpose of this script is to delete the files that match the patterns specified in the strCriteria variable. To do this, I will use thehttps://fr.wikipedia.org/wiki/Fermeture_(informatique)[closures]: each, findAll, collect, as well as the StringTokenizer class, which will break my criteria string into pieces to retrieve a list of strings. If one of the files in my folder to be cleaned contains one of the patterns in its name, it will be a candidate for deletion by being added to the result list. And in the last line, a small example ofhttps://en.wikipedia.org/wiki/Elvis_operator[Elvis operator]+ 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/en/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>Here is a piece of working Groovy code to replace all occurrences of a character sequence in a String, load a .properties file into a properties object, and execute a command within a String. replaceTextinFile.groovy</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/en/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>Here is a piece of working Groovy code that generates a text file containing the first 256 printable characters of the ASCII table.</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>I named the file spe_char.groovy. From the folder where the file is located, open a terminal and copy-paste to execute the script.</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>result:</p> </div> <div class="listingblock"> <div class="content"> <pre> 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 ª µ º À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ</pre> </div> </div>