# SKILL — Développement sur GrosseBertha (Synology) + versioning Forgejo

Skill universel pour toute session de développement sur l'infrastructure de
Bastien. Couvre la connexion, les conventions de patch de code, et le
versioning git via Forgejo. Réutilisable pour n'importe quel projet hébergé
sur GrosseBertha.

---

## 1. L'environnement

**GrosseBertha** — Synology DS218, ARM64, DSM 7.3.2.
- Connexion : SSH, utilisateur `Master`.
- Shell : `/bin/sh` (PAS bash — pas de `[[ ]]`, pas de tableaux bash).
- Python : `python3` v3.9 (dans un venv par projet).

Activation du venv (projet Sliding) :
```
source ~/App/Sliding/python-pptx/venv/bin/activate
```

Outils disponibles : `python3` (3.9), `pip` (avec `--break-system-packages`),
`docker` (Container Manager), `wget`, `pdftoppm`, `pdftotext` (poppler-utils),
`git`. **Indisponibles** : `unzip` (utiliser `python3 zipfile`), `fc-list`,
`fc-cache`, `setfacl`.

---

## 2. Règles de procédure — OBLIGATOIRES

Ces règles limitent la consommation de tokens et les itérations inutiles.

**2.1 — Accord avant tout code lourd.** Ne jamais générer un script de patch,
une fonction ou un fichier sans accord explicite. « Je génère ? » → attendre
« oui ».

**2.2 — Commandes terminal sur UNE SEULE LIGNE.** Le shell SSH n'accepte pas
le multiligne fiablement.
```
# CORRECT
python3 -c "import os; print(os.getcwd())"
# INCORRECT (multiligne)
```

**2.3 — Lire les lignes exactes avant de patcher.** Le fichier sur GrosseBertha
diverge souvent des fichiers de référence. Toujours :
```
sed -n 'X,Yp' ~/App/Sliding/python-pptx/render_engine.py
```
avant tout patch. Ne jamais supposer que le fichier distant correspond au
fichier projet.

**2.4 — Nettoyage unicode avant patch.** Les fichiers contiennent des tirets
unicode `─` dans les commentaires. Toujours nettoyer en début de script de
patch, sinon les patterns de remplacement échouent :
```python
import re
c = re.sub(r'[─]+', '-', c)
```

**2.5 — Valider le FICHIER FINAL, pas la variable intermédiaire.**
```python
# CORRECT
with open(SRC) as f: final = f.read()
ast.parse(final)
# INCORRECT — content peut être une variable corrompue
ast.parse(content)
```

**2.6 — Feedback visuel : PNG d'UNE slide, pas le PDF complet.** Évite la
rasterisation multi-pages inutile.

**2.7 — Résultat terminal minimal.** Bastien ne colle que l'essentiel : « OK »
ou les lignes de confirmation si succès ; uniquement le traceback si erreur.

**2.8 — Téléchargement des scripts via l'app mobile Claude.ai.** La webapp
desktop échoue sur les fichiers de plus de quelques Ko.

---

## 3. Patch de code Python — méthode de référence

Script `.py` dédié, appliqué sur GrosseBertha :

```python
import ast, shutil, re

SRC = "render_engine.py"
BAK = SRC + ".bak"
shutil.copy2(SRC, BAK)

with open(SRC, encoding="utf-8") as f:
    c = f.read()

c = re.sub(r'[─]+', '-', c)          # nettoyage unicode obligatoire

OLD = """...texte exact après nettoyage..."""
NEW = """...nouveau texte..."""

if OLD in c:
    c = c.replace(OLD, NEW)
    print("OK")
else:
    print("ECHEC -- pattern non trouve")

with open(SRC, "w", encoding="utf-8") as f:
    f.write(c)

with open(SRC, encoding="utf-8") as f:        # valider le fichier final
    final = f.read()
try:
    ast.parse(final)
    print(f"SYNTAXE OK -- {len(final.splitlines())} lignes")
except SyntaxError as e:
    shutil.copy2(BAK, SRC)
    print(f"SYNTAXE ERREUR : {e} -- backup restaure")
```

**Méthode par numéros de ligne** (si le pattern texte est fragile) : repérer
par marqueur fiable (`def ma_fonction(`) et remplacer la tranche `lines[start:end]`.

---

## 4. Sécurité — fichiers YAML de config

**Ne jamais écraser** `theme.yaml` (15 Ko), `layouts.yaml` (45 Ko),
`components.yaml`. Un LLM qui génère une version minimaliste casse tout le
pipeline. Si modification nécessaire :
1. `cp theme.yaml theme.yaml.bak`
2. Script Python ciblé sur la clé concernée uniquement
3. `ls -lh *.yaml` pour vérifier la taille après

Originaux de secours : dans les outputs Claude.ai du projet.

---

## 5. Versioning — Forgejo

Forgejo auto-hébergé en Docker. Accès : SSH port **2222** ou HTTPS port **3000**
via `forgejo.bertha-cloud.fr`. Dépôt principal : `Master/sliding-automation`.

**Workflow de commit après chaque modification validée :**
```
git add <fichiers modifiés>
git commit -m "type: description claire du changement"
git push
```

**Conventions de messages de commit :**
- `fix:` — correction de bug
- `feat:` — nouvelle fonctionnalité
- `refactor:` — nettoyage / restructuration sans changement de comportement
- `chore:` — maintenance (suppression de fichiers obsolètes, etc.)
- `docs:` — documentation

**Archiver une version (tag) :**
```
git tag -a v2.0 -m "Description de la version"
git push origin v2.0
```

**`.gitignore` type** (ne jamais versionner secrets, venv, sorties) :
```
.env
venv/
__pycache__/
*.pyc
projets/*/outputs/
projets/*/inputs/
projets/*/project_state.json
projets/*/journal.md
*.pptx
*.pdf
*.bak
*.bak_*
```

Principe : git remplace les dossiers `archive/`. Les anciennes versions vivent
dans l'historique et les tags, pas dans des copies de fichiers.

---

## 6. Container Manager / Docker

```
# Si Docker en erreur après update DSM (workaround communauté DS218)
sudo synosetkeyvalue /etc/synoinfo.conf unique synology_rtd1296_ds220j
sudo synosetkeyvalue /etc.defaults/synoinfo.conf unique synology_rtd1296_ds220j
sudo synopkg start ContainerManager
# Conteneurs
sudo docker ps
sudo docker logs <conteneur>
sudo docker restart <conteneur>
```

---

## 7. Structure des dossiers

```
~/App/Sliding/python-pptx/      ← pipeline Sliding
   render_engine_v2.py          ← moteur de rendu (diverge du fichier projet)
   facilitator_v9.py            ← orchestrateur (version active)
   prompt_injection_v2.py
   theme_v2.yaml                ← NE PAS ÉCRASER
   layouts_v2.yaml              ← NE PAS ÉCRASER
   components_v2.yaml           ← NE PAS ÉCRASER
   projets/<slug>/inputs|outputs/
   venv/

~/App/Context_continuity/       ← système de mémoire Trilium
   trilium_context.py
   trilium_api.py

/volume1/docker/trilium/        ← données Trilium (chown 1000:1000)
/volume1/web/sliding/           ← galerie layouts HTML
```