Merge pull request #870 from jmrenouard/master

V2.8.20

Author: jmrenouard

.agent/rules/00_constitution.md

@@ -0,0 +1,14 @@
+---
+trigger: always_on
+---
+
+# **AI CONTEXT SPECIFICATIONS & PROJECT CONSTITUTION**
+
+$$SYSTEM\_CRITICAL$$  
+Notice to the Agent: This document constitutes the unique and absolute source of truth for the project. Its prior consultation is imperative before any technical intervention.
+
+Make mysqltuner.pl the best performance tuning advisor
+
+Large insights
+Good advices
+Well documented solution

.agent/rules/01_objective.md

@@ -0,0 +1,23 @@
+## **2\. 🎯 OPERATIONAL OBJECTIVE**
+
+$$DYNAMIC\_CONTEXT$$
+
+* **Status:** \[IN PROGRESS\]  
+* **Priority Task:** Maintain and enhance `mysqltuner.pl`, a Perl script for MySQL/MariaDB database performance tuning. Ensure single-file architecture and high reliability through automated testing.
+
+**Success Criteria:**
+
+1. **Architecture:** No splitting of the main file; all logic resides in `mysqltuner.pl`.
+2. **Quality:** 100% of new features validated through TDD.
+3. **Docs:** Keep `README.md` and translations updated with new features and requirements.
+4. **Automation:** All tests runnable via `make test-*` or specific test scripts.
+5. **Goal:** Provide the most accurate and up-to-date performance tuning recommendations for MySQL-compatible databases.
+
+**Roadmap / Evolution Paths:**
+
+1. **Schema Validation for Rules**: Créer un script de linting pour valider que les fichiers `.agent/rules/*.md` respectent un format standard.
+2. **Source Code Annotation**: Automatiser l'ajout des tags de version directement dans les commentaires des fonctions modifiées.
+3. **Automated Doc-Link Check**: Ajouter un test qui vérifie que les liens de documentation insérés dans les commentaires du code (`# See: http://...`) sont toujours valides.
+4. **Pre-commit Hook**: Implementer un hook Git local qui lance le pre-flight check de `/git-flow`.
+5. **Automated Roadmap Tracking**: Créer un script qui extrait les points de la roadmap pour générer un rapport de progression.
+6. **Perl Tidy Integration**: Ajouter une règle exigeant l'utilisation de `perltidy` avec une configuration spécifique pour garantir la lisibilité du fichier unique.

.agent/rules/02_architecture.md

@@ -0,0 +1,25 @@
+---
+trigger: always_on
+---
+
+## **3\. 🏗️ TECHNICAL ENVIRONMENT & ARCHITECTURE**
+
+$$IMMUTABLE$$  
+Component Map:  
+Modification prohibited without explicit request.  
+
+| File/Folder | Functionality | Criticality |
+| :--- | :--- | :--- |
+| mysqltuner.pl | **Main script - SINGLE FILE ARCHITECTURE ENFORCED** | 🔴 CRITICAL |
+| Makefile | Command orchestrator (Test, Build, Lint) | LOW |
+| Dockerfile | Containerized execution environment | 🟡 MEDIUM |
+| .agent/ | Agent-specific rules and workflows | LOW |
+| documentation/ | Technical documentation and reports | 🟡 HIGH |
+| tests/ | Test suite for validator and tuning logic | 🟡 HIGH |
+
+**Technology Stack:**
+
+* **Language:** Perl (Core script)
+* **Testing:** Perl (prove, Test::More)
+* **Automation:** Makefile, Bash, Docker, Python, Per
+* **DBMS Compatibility:** MySQL, MariaDB, Percona, AWS, AWS Aurora, Docker, GCP, Azure

.agent/rules/03_execution_rules.md

@@ -0,0 +1,52 @@
+---
+trigger: always_on
+---
+
+## **4\. ⚙️ EXECUTION RULES & CONSTRAINTS**
+
+### **4.1. Formal Prohibitions (Hard Constraints)**
+
+1. **SINGLE FILE:** Spliting `mysqltuner.pl` into modules is **strictly prohibited**.
+2. **NON-REGRESSION:** Deleting existing code is **prohibited** without relocation or commenting out.
+3. **NO BACKWARDS COMPATIBILITY BY DEFAULT:** Do not add backwards compatibility unless specifically requested; update all downstream consumers.
+4. **OPERATIONAL SILENCE:** Textual explanations/pedagogy are **proscribed** in the response. Only code blocks, commands, and technical results.
+5. **TDD MANDATORY:** Use a TDD approach. _Do not assume_ that your solution is correct. Instead, _validate your solution is correct_ by first creating a test case and running the test case to _prove_ the solution is working as intended.
+6. **WEB SEARCH:** Assume your world knowledge is out of date. Use your web search tool to find up-to-date docs and information.
+
+### **4.2. Coding Guidelines**
+
+- **SOLID Principles**: Follow Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles.
+- **DRY (Don't Repeat Yourself)**: Avoid code duplication; extract common logic into reusable functions within the single file.
+- **KISS (Keep It Simple, Stupid)**: Strive for simplicity. Avoid over-engineering.
+- **Clean Code**: Write readable, self-documenting code with meaningful names and small functions.
+- **Perl Tidy**: Use `perltidy` with the project's specific configuration to ensure consistent formatting across the single-file architecture.
+- **Error Handling**: Implement robust error handling and logging. Use low-cardinality logging with stable message strings.
+
+#### **Core Best Practices:**
+
+1. **Validation Multi-Version Systématique**: Tout changement dans la logique de diagnostic doit être testé contre au moins une version "Legacy" (ex: MySQL 5.7) et une version "Moderne" (ex: MariaDB 11.4) via la suite de tests Docker (`make test-it`).
+2. **Résilience des Appels Système**: Chaque commande externe (`sysctl`, `ps`, `free`, `mysql`) doit impérativement être protégée par une vérification de l'existence du binaire et une gestion d'erreur (exit code non nul) pour éviter les sorties "polluées" dans le rapport final.
+3. **Politique "Zéro-Dépendance" CPAN**: Interdire l'usage de modules Perl qui ne font pas partie du "Core" (distribution standard Perl) afin que `mysqltuner.pl` reste un script unique, copiable et exécutable instantanément sur n'importe quel serveur sans installation préalable.
+4. **Traçabilité des Conseils (Audit Trail)**: Chaque recommandation ou conseil affiché par le script doit être documenté dans le code par un commentaire pointant vers la source officielle (Documentation MySQL/MariaDB ou KB) pour justifier le seuil choisi.
+5. **Efficience Mémoire (Parsing de Log)**: Pour le traitement des fichiers de logs (souvent volumineux), privilégier systématiquement le traitement ligne par ligne plutôt que le chargement complet en mémoire, surtout lors de la récupération via `--container`.
+6. **Standardisation @Changelog**: Maintenir le `@Changelog` en suivant strictement le format des _Conventional Commits_ (feat, fix, chore, docs) pour permettre une extraction automatisée et propre des notes de version lors des tags Git.
+
+### **4.3. Output & Restitution Format**
+
+1. **NO CHATTER:** No intro or conclusion sentences.
+2. **CODE ONLY:** Use Search_block / replace_block format for files > 50 lines.
+3. **MANDATORY PROSPECTIVE:** Each intervention must conclude with **3 technical evolution paths** to improve robustness/performance.
+4. **MEMORY UPDATE:** Include the JSON MEMORY_UPDATE_PROTOCOL block at the very end.
+
+### **4.4. Development Workflow**
+
+1. **Validation by Proof:** All changes must be verifiable via `make test-*` or dedicated test scripts.
+2. **Git Protocol:**
+
+- **STRICT PROHIBITION:** No `git commit`, `git push`, or `git tag` without using `/git-flow` or an explicit user order.
+- **Conventional Commits:** Use `feat:`, `fix:`, `chore:`, `docs:`.
+- **Versioning & Tagging:** Reserved ONLY for the `/git-flow` workflow.
+- **Atomic Operations:** Commit and tag must be synchronized via the workflow.
+- **Remote Sync:** If the last tag is not present on remote, do not increment version without explicit confirmation.
+
+1. **Changelog:** All changes MUST be traced and documented inside `@Changelog`.

.agent/rules/04_memory_protocol.md

@@ -0,0 +1,26 @@
+---
+trigger: always_on
+---
+
+## **5\. 📜 STATE MEMORY & HISTORY**
+
+### **Contextual Consistency Protocols**
+
+1. **History Update:** Add new entries to the top of Changelog if the action is correct and tested.  
+Changelog is a file at root of this projet
+insure consistency between CURRENT_VERSION.txt
+MySQLtuner version inside mysqltuner.pl (begin of script this script and begin of pod doc =pod)
+Changelog last version
+
+2. **Git Sync:** Consult git log \-n 15 to synchronize context.  
+3. **Rotation:** FIFO Rotation (Max 600 lines). Remove oldest entries beyond 600 lines.
+
+4. All changes must be added to last version in `Changelog`.
+5. No increment version if explicit git commit/tag/push via `/git-flow` or specific order from previous version hasn't been made.
+6. After Git tag and push, increment version on last digit for the next development cycle.
+
+### **History Entry example**
+
+1.0.9 2026-01-16
+
+- chore: migrate HISTORY.md into Changelog and remove HISTORY.md.

.agent/rules/autolearning.md

@@ -0,0 +1,10 @@
+---
+trigger: always_on
+---
+
+If new rules are invoqued with REMEMBER: in conversation
+Update this file with RULE: xxxx in .agent/rules/autolearning.md with this information under
+REMEMBER
+
+REMENBER:
+Rule: Don't forget to updates this file with REMEMBER: tag

.agent/workflows/doc-sync.md

@@ -0,0 +1,44 @@
+---
+description: doc-sync
+---
+
+# Doc Sync
+
+You are a specialized agent for synchronizing documentation with code.
+
+## When to use this workflow
+
+- When the user types `/doc-sync`.
+- When they ask to update the documentation after code changes.
+
+## Context
+
+- The project uses Markdown documentation in the root folder.
+- List of documentation files:
+  - [mariadb_support.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/mariadb_support.md)
+  - [mysql_support.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/mysql_support.md)
+  - [README.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/README.md)
+  - [README.fr.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/README.fr.md)
+  - [README.it.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/README.it.md)
+  - [README.ru.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/README.ru.md)
+  - [ROADMAP.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/ROADMAP.md)
+  - [CONTRIBUTING.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/CONTRIBUTING.md)
+  - [FEATURES.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/FEATURES.md)
+  - [USAGE.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/USAGE.md)
+  - [INTERNALS.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/INTERNALS.md)
+  - [CODE_OF_CONDUCT.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/CODE_OF_CONDUCT.md)
+  - [SECURITY.md](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/SECURITY.md)
+
+## Task
+
+1. Identify recently modified files (via git diff or IDE history).
+2. For each file, spot public functions / classes.
+3. Update the corresponding sections in the relevant documentation files or `README.md`.
+4. Propose a clear diff and wait for validation before writing.
+
+## Constraints
+
+- Never delete documentation sections without explicit confirmation.
+- Respect the existing style (headings, lists, examples).
+- If information is uncertain, ask a question instead of making it up.
+- **IMPORTANT**: If new documentation files (`*.md`) are added to the repository, you MUST update this list in `doc-sync.md`.

.agent/workflows/git-flow.md

@@ -0,0 +1,80 @@
+---
+description: Automate git-flow release process
+---
+
+1. **Ensure clean working tree and Pre-flight Consistency Check**
+   - Verify that `Changelog`, `CURRENT_VERSION.txt`, and `mysqltuner.pl` are synchronized.
+
+   ```bash
+   git status --porcelain
+   CURRENT_VER=$(cat CURRENT_VERSION.txt | tr -d '[:space:]')
+   SCRIPT_VER=$(grep "my \$tunerversion =" mysqltuner.pl | cut -d'"' -f2)
+   CHANGELOG_VER=$(head -n 1 Changelog | awk '{print $1}')
+
+   echo "Checking version consistency: $CURRENT_VER"
+   
+   if [ "$CURRENT_VER" != "$SCRIPT_VER" ]; then
+       echo "ERROR: CURRENT_VERSION.txt ($CURRENT_VER) does not match mysqltuner.pl ($SCRIPT_VER)"
+       exit 1
+   fi
+
+   if [ "$CURRENT_VER" != "$CHANGELOG_VER" ]; then
+       echo "ERROR: CURRENT_VERSION.txt ($CURRENT_VER) does not match Changelog ($CHANGELOG_VER)"
+       exit 1
+   fi
+   
+   echo "Consistency check passed."
+   ```
+
+   // turbo
+2. **Commit Current Changes**
+   - Commit all pending changes including `Changelog` updates for the current version.
+
+   ```bash
+   git add .
+   git commit -m "feat: release $CURRENT_VER"
+   ```
+
+   // turbo
+3. **Create Tag for Current Version with Changelog content**
+   - Extract the latest release notes and create an annotated tag.
+
+   ```bash
+   # Extract content between the first version header and the next one
+   TAG_MSG=$(awk "/^$CURRENT_VER/,/^([0-9]+\.[0-9]+\.[0-9]+)/ {if (\$0 !~ /^([0-9]+\.[0-9]+\.[0-9]+)/) print}" Changelog | sed '/^$/d')
+   git tag -a v$CURRENT_VER -m "Release $CURRENT_VER" -m "$TAG_MSG"
+   ```
+
+   // turbo
+4. **Push Branch and Tag**
+   - Push to the remote repository.
+
+   ```bash
+   git push origin main
+   git push origin v$CURRENT_VER
+   ```
+
+   // turbo
+5. **Post-Push: Increment Version for Next Cycle**
+   - Calculate the next patch version and update files.
+
+   ```bash
+   NEW_VER=$(echo $CURRENT_VER | awk -F. '{print $1"."$2"."($3+1)}')
+   echo $NEW_VER > CURRENT_VERSION.txt
+   sed -i "s/my \$tunerversion = .*/my \$tunerversion = \"$NEW_VER\";/" mysqltuner.pl
+   
+   DATE=$(date +%Y-%m-%d)
+   echo -e "$NEW_VER $DATE\n\n- \n" > tmp_changelog && cat Changelog >> tmp_changelog && mv tmp_changelog Changelog
+   ```
+
+   // turbo
+6. **Commit Version Bump**
+   - Commit the incremented version for the next development cycle.
+
+   ```bash
+   git add CURRENT_VERSION.txt mysqltuner.pl Changelog
+   git commit -m "chore: bump version to $NEW_VER"
+   git push origin main
+   ```
+
+   // turbo

.agent/workflows/git-rollback.md

@@ -0,0 +1,37 @@
+---
+description: Rollback a failed release (delete tags and revert commits)
+---
+
+1. **Delete Local and Remote Tag**
+   - Identify the tag to remove from `CURRENT_VERSION.txt`.
+
+   ```bash
+   VERSION_TO_ROLLBACK=$(cat CURRENT_VERSION.txt)
+   echo "Rolling back version v$VERSION_TO_ROLLBACK"
+   
+   git tag -d v$VERSION_TO_ROLLBACK
+   git push --delete origin v$VERSION_TO_ROLLBACK
+   ```
+
+   // turbo
+2. **Revert Release Commits**
+   - Reset the branch to the state before the release commit.
+   - **WARNING**: This uses `git reset --hard`. Ensure you don't have uncommitted work you want to keep.
+
+   ```bash
+   # Identify the commit before the release commit (assuming the last commit was the version bump)
+   # We might want to revert the last 2 commits: the bump and the release tag commit.
+   
+   # Reset to 2 commits ago
+   git reset --hard HEAD~2
+   
+   # Force push to clean remote main branch
+   # git push origin main --force
+   ```
+
+   // turbo
+3. **Notify User**
+   - The rollback is completed locally. Remote sync may require a force push.
+
+   > [!CAUTION]
+   > The local branch has been reset. If you had already pushed the version bump, you may need to run `git push origin main --force` to synchronize the remote branch.

.agent/workflows/test-it.md

@@ -0,0 +1,41 @@
+---
+description: Run MySQLTuner tests against multiple database configurations
+---
+
+# 🧪 Run Multi-DB Tests
+
+This workflow automates the execution of `mysqltuner.pl` against various database versions using Docker environments.
+
+## Prerequisite
+
+- Docker and Docker Compose installed
+- `make` installed
+- https://github.com/jmrenouard/multi-db-docker-env
+- https://github.com/jmrenouard/test_db
+
+## Steps
+
+1. **Run the test script**
+// turbo
+
+```bash
+bash build/test_envs.sh mysql84 mariadb1011
+```
+
+> [!NOTE]
+> You can pass specific configurations as arguments to the script.
+> Example: `bash build/test_envs.sh mysql57 mariadb106 percona80`
+
+1. **Check the results**
+The reports are generated in the `examples/` directory, organized by date and configuration name.
+
+- `report.txt`: Summary of the test run.
+- `mysqltuner_output.txt`: Full output from MySQLTuner.
+- `execution.log`: Standard output/error from the run.
+
+1. **Cleanup**
+The script automatically stops the containers, but you can manually ensure everything is clean:
+
+```bash
+cd vendor/multi-db-docker-env && make stop
+```