mathieu/personotes
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
personotes/COPILOT.md

19 KiB
Raw Permalink Blame History

COPILOT.md

Ce fichier documente le travail effectué avec GitHub Copilot sur le projet Personotes.

À propos du projet

Personotes est une application web légère de prise de notes en Markdown avec un backend Go et un frontend JavaScript moderne. Les notes sont stockées sous forme de fichiers Markdown avec des métadonnées YAML en front matter.

Architecture hybride:

  • Backend Go: Gestion des fichiers, indexation, API REST
  • HTMX: Interactions dynamiques avec minimum de JavaScript
  • CodeMirror 6: Éditeur Markdown sophistiqué
  • Vite: Build system moderne pour le frontend

Fonctionnalités principales

  • 📝 Éditeur CodeMirror 6 avec preview en direct et synchronisation du scroll
  • 📅 Notes quotidiennes avec calendrier interactif (Ctrl/Cmd+D)
  • ⭐ Système de favoris pour notes et dossiers
  • 🔗 Liens entre notes avec commande /ilink et recherche fuzzy
  • 🎨 8 thèmes sombres (Material Dark, Monokai, Dracula, One Dark, Solarized, Nord, Catppuccin, Everforest)
  • 🔤 8 polices avec 4 tailles (JetBrains Mono, Fira Code, Inter, etc.)
  • ⌨️ Mode Vim optionnel avec keybindings complets
  • 🔍 Recherche avancée (Ctrl/Cmd+K) avec tags, titre, chemin
  • 🌳 Arborescence drag-and-drop pour organiser les notes
  • / Commandes slash pour insertion rapide de Markdown
  • 🚀 API REST complète (/api/v1/notes) pour accès programmatique

Historique des contributions Copilot

Session du 12 novembre 2025

Création du fichier COPILOT.md

  • Contexte: L'utilisateur a demandé de mettre à jour le fichier copilot.md
  • Action: Création initiale du fichier COPILOT.md pour documenter les interactions avec GitHub Copilot
  • Inspiration: Structure basée sur CLAUDE.md et GEMINI.md existants
  • Contenu: Vue d'ensemble du projet, architecture, fonctionnalités, et structure pour documenter les contributions futures

Implémentation complète du système d'internationalisation (i18n)

  • Contexte: L'utilisateur souhaitait internationaliser l'application (français → anglais) et ajouter un sélecteur de langue
  • Objectif: Rendre l'application accessible en plusieurs langues sans casser le code existant
  • Durée: ~3 heures de travail (10 tâches accomplies)

Phase 1 - Fichiers de traduction:

  • Création de locales/en.json avec 200+ clés de traduction en anglais
  • Création de locales/fr.json avec 200+ clés de traduction en français
  • Création de locales/README.md avec guide pour contributeurs
  • Structure hiérarchique: app, menu, editor, fileTree, search, settings, errors, etc.
  • Support de l'interpolation de variables: {{filename}}, {{date}}, etc.

Phase 2 - Backend Go:

  • Création du package internal/i18n/i18n.go avec:
    • Type Translator thread-safe (RWMutex)
    • Fonction LoadFromDir() pour charger les JSON
    • Fonction T() pour traduire avec interpolation
    • Support du fallback vers langue par défaut
  • Création de internal/i18n/i18n_test.go avec tests unitaires complets
  • Intégration dans cmd/server/main.go:
    • Chargement des traductions au démarrage
    • Passage du translator au Handler
  • Ajout de l'endpoint /api/i18n/{lang} dans handler.go
  • Fonctions helper getLanguage() et t() pour détecter et traduire
  • Mise à jour de internal/api/handler_test.go pour inclure le translator

Phase 3 - Frontend JavaScript:

  • Création de frontend/src/i18n.js:
    • Classe I18n singleton
    • Détection automatique de la langue (localStorage → browser → défaut)
    • Chargement asynchrone des traductions depuis /api/i18n/{lang}
    • Fonction t(key, args) pour traduire avec interpolation
    • Système de callbacks pour changement de langue
    • Fonction translatePage() pour éléments avec data-i18n
  • Création de frontend/src/language-manager.js:
    • Gestion du sélecteur de langue dans Settings
    • Rechargement automatique de l'interface après changement
    • Mise à jour de l'attribut lang du HTML
    • Rechargement HTMX du contenu (editor, file-tree, favorites)
  • Import des modules dans frontend/src/main.js

Phase 4 - Interface utilisateur:

  • Ajout d'un nouvel onglet "⚙️ Autre" dans la modal Settings (templates/index.html)
  • Création de la section "🌍 Langue / Language" avec:
    • Radio button 🇬🇧 English
    • Radio button 🇫🇷 Français
    • Description et conseils pour chaque option
  • Mise à jour de frontend/src/theme-manager.js pour gérer le nouvel onglet
  • Support du changement de langue en temps réel

Phase 5 - Documentation:

  • Création de I18N_IMPLEMENTATION.md:
    • Documentation complète de l'implémentation
    • Guide étape par étape pour finalisation
    • Exemples de code JavaScript et Go
    • Checklist de test et dépannage
  • Création de I18N_QUICKSTART.md:
    • Guide de démarrage rapide
    • Instructions de build et test
    • Exemples d'utilisation
    • Notes sur le statut et prochaines étapes

Résultats:

  • ✅ Infrastructure i18n complète et fonctionnelle
  • ✅ 200+ traductions EN/FR prêtes
  • ✅ Détection automatique de la langue
  • ✅ Sélecteur de langue dans Settings
  • ✅ API REST pour servir les traductions
  • ✅ Système extensible (ajout facile de nouvelles langues)
  • ✅ Zéro breaking change - code existant non affecté
  • ⏳ Templates HTML gardent leur texte français (migration optionnelle)
  • ⏳ Messages d'erreur backend restent en français (logs uniquement)

Fichiers créés/modifiés (17 fichiers):

  1. locales/en.json - Nouveau
  2. locales/fr.json - Nouveau
  3. locales/README.md - Nouveau
  4. internal/i18n/i18n.go - Nouveau
  5. internal/i18n/i18n_test.go - Nouveau
  6. frontend/src/i18n.js - Nouveau
  7. frontend/src/language-manager.js - Nouveau
  8. frontend/src/main.js - Modifié (imports)
  9. frontend/src/theme-manager.js - Modifié (onglet Autre)
  10. templates/index.html - Modifié (section langue)
  11. cmd/server/main.go - Modifié (translator)
  12. internal/api/handler.go - Modifié (i18n, endpoint, helpers)
  13. internal/api/handler_test.go - Modifié (translator)
  14. I18N_IMPLEMENTATION.md - Nouveau
  15. I18N_QUICKSTART.md - Nouveau
  16. COPILOT.md - Modifié (cette section)
  17. .gitignore - (si besoin pour node_modules)

Prochaines étapes recommandées:

  1. Build du frontend: cd frontend && npm run build
  2. Test du serveur: go run ./cmd/server
  3. Vérifier l'interface dans le navigateur
  4. Migration progressive des templates HTML (optionnel)
  5. Migration des alert() JavaScript (optionnel)
  6. Ajout d'autres langues: ES, DE, IT, etc. (optionnel)

Technologies utilisées:

  • Go 1.22+ (encoding/json, sync.RWMutex)
  • JavaScript ES6+ (async/await, classes, modules)
  • JSON pour les fichiers de traduction
  • localStorage pour la persistance côté client
  • HTMX pour le rechargement dynamique
  • Template Go pour le rendering HTML

Architecture technique

Backend (Go)

Trois packages principaux sous internal/:

indexer:

  • Indexation en mémoire des notes par tags
  • Parse le front matter YAML
  • Recherche riche avec scoring et ranking
  • Thread-safe avec sync.RWMutex

watcher:

  • Surveillance filesystem avec fsnotify
  • Déclenchement de la ré-indexation (debounce 200ms)
  • Surveillance récursive des sous-dossiers

api:

  • handler.go: Endpoints HTML principaux
  • rest_handler.go: API REST v1 (JSON)
  • daily_notes.go: Fonctionnalités notes quotidiennes
  • favorites.go: Gestion des favoris

Frontend (JavaScript)

Code source dans frontend/src/, build avec Vite:

Modules principaux:

  • main.js: Point d'entrée, importe tous les modules
  • editor.js: Éditeur CodeMirror 6, preview, commandes slash
  • vim-mode-manager.js: Intégration mode Vim
  • search.js: Modal de recherche Ctrl/Cmd+K
  • link-inserter.js: Modal de liens internes /ilink
  • file-tree.js: Arborescence drag-and-drop
  • favorites.js: Système de favoris
  • daily-notes.js: Création notes quotidiennes et calendrier
  • keyboard-shortcuts.js: Raccourcis clavier globaux
  • theme-manager.js: Gestion des thèmes
  • font-manager.js: Personnalisation des polices
  • ui.js: Toggle sidebar et utilitaires UI

Coordination HTMX + JavaScript

Principe clé: HTMX gère TOUTES les interactions serveur et mises à jour DOM. JavaScript gère les améliorations UI client.

Flow:

Interaction utilisateur → HTMX (AJAX) → Serveur Go (HTML) → HTMX (swap DOM) → Events JS (améliorations)

Best practices:

  • Utiliser htmx.ajax() pour les requêtes initiées par JS
  • Écouter les events HTMX (htmx:afterSwap, htmx:oobAfterSwap) au lieu de MutationObserver
  • Laisser HTMX traiter automatiquement les swaps out-of-band (OOB)
  • Éviter la manipulation DOM manuelle, laisser HTMX gérer

Développement

Build du frontend (OBLIGATOIRE)

cd frontend
npm install              # Première fois seulement
npm run build           # Build production
npm run build -- --watch # Mode watch pour développement

Fichiers générés:

  • static/dist/personotes-frontend.es.js (1.0 MB, ES module)
  • static/dist/personotes-frontend.umd.js (679 KB, UMD)

Lancement du serveur

go run ./cmd/server

Options:

  • -addr :PORT - Port du serveur (défaut: :8080)
  • -notes-dir PATH - Répertoire des notes (défaut: ./notes)

Tests

go test ./...              # Tous les tests
go test -v ./...          # Mode verbose
go test ./internal/indexer # Package spécifique

Dépendances

Backend Go

  • github.com/fsnotify/fsnotify - Surveillance filesystem
  • gopkg.in/yaml.v3 - Parsing YAML front matter

Frontend NPM

  • @codemirror/basic-setup (^0.20.0) - Fonctionnalités éditeur de base
  • @codemirror/lang-markdown (^6.5.0) - Support Markdown
  • @codemirror/state (^6.5.2) - Gestion état éditeur
  • @codemirror/view (^6.38.6) - Couche affichage éditeur
  • @codemirror/theme-one-dark (^6.1.3) - Thème sombre
  • @replit/codemirror-vim (^6.2.2) - Mode Vim
  • vite (^7.2.2) - Build tool

Frontend CDN

  • htmx (1.9.10) - Interactions AJAX dynamiques
  • marked.js - Conversion Markdown → HTML
  • DOMPurify - Sanitisation HTML (prévention XSS)
  • Highlight.js (11.9.0) - Coloration syntaxique code blocks

Sécurité

Validation des chemins

  • filepath.Clean() pour normaliser les chemins
  • Rejet des chemins commençant par .. ou absolus
  • Vérification extension .md obligatoire
  • filepath.Join() pour construire des chemins sécurisés

Protection XSS

  • DOMPurify sanitise tout HTML rendu depuis Markdown
  • Prévention des attaques Cross-Site Scripting

API REST

  • ⚠️ Pas d'authentification par défaut
  • Recommandation: Reverse proxy (nginx, Caddy) avec auth pour exposition publique
  • Pas de CORS configuré (same-origin uniquement)
  • Pas de rate limiting (à ajouter si besoin)

Format des notes

Les notes utilisent du front matter YAML:

---
title: "Titre de la note"
date: "12-11-2025"
last_modified: "12-11-2025:14:30"
tags: [tag1, tag2, tag3]
---

Contenu Markdown de la note...

Gestion automatique:

  • title: Généré depuis le nom de fichier si absent
  • date: Date de création (préservée)
  • last_modified: Toujours mis à jour à la sauvegarde (format: DD-MM-YYYY:HH:MM)
  • tags: Préservés depuis l'input utilisateur, défaut ["default"]

Commandes slash

Déclenchées par / en début de ligne:

Formatage:

  • h1, h2, h3 - Titres Markdown
  • bold, italic, code - Formatage texte
  • list - Liste à puces

Blocs:

  • codeblock - Bloc de code avec langage
  • quote - Citation
  • hr - Ligne horizontale
  • table - Tableau Markdown

Dynamique:

  • date - Insère date actuelle (format français DD/MM/YYYY)

Liens:

  • link - Lien Markdown standard [texte](url)
  • ilink - Modal de liens internes entre notes

Raccourcis clavier

Essentiels:

  • Ctrl/Cmd+D - Créer/ouvrir note du jour
  • Ctrl/Cmd+K - Ouvrir modal de recherche
  • Ctrl/Cmd+S - Sauvegarder note
  • Ctrl/Cmd+B - Toggle sidebar
  • Ctrl/Cmd+/ - Afficher aide raccourcis

Éditeur:

  • Tab - Indentation
  • Shift+Tab - Dés-indentation
  • Ctrl/Cmd+Enter - Sauvegarder (alternatif)

Navigation:

  • ↑/↓ - Naviguer résultats recherche/palette
  • Enter - Sélectionner/confirmer
  • Esc - Fermer modals/annuler

Voir docs/KEYBOARD_SHORTCUTS.md pour la documentation complète.

Structure du projet

personotes/
├── cmd/server/main.go                    # Point d'entrée serveur
├── internal/                             # Packages Go backend
│   ├── api/
│   │   ├── handler.go                    # Endpoints HTML principaux
│   │   ├── rest_handler.go               # API REST v1
│   │   ├── daily_notes.go                # Notes quotidiennes
│   │   ├── favorites.go                  # Gestion favoris
│   │   └── handler_test.go
│   ├── indexer/
│   │   ├── indexer.go                    # Indexation et recherche
│   │   └── indexer_test.go
│   └── watcher/
│       └── watcher.go                    # Surveillance filesystem
├── frontend/                             # Source et build frontend
│   ├── src/
│   │   ├── main.js                       # Point d'entrée JS
│   │   ├── editor.js                     # Éditeur CodeMirror 6
│   │   ├── vim-mode-manager.js           # Mode Vim
│   │   ├── search.js                     # Modal recherche
│   │   ├── link-inserter.js              # Modal liens internes
│   │   ├── file-tree.js                  # Arborescence drag-and-drop
│   │   ├── favorites.js                  # Système favoris
│   │   ├── daily-notes.js                # Notes quotidiennes
│   │   ├── keyboard-shortcuts.js         # Raccourcis clavier
│   │   ├── theme-manager.js              # Gestion thèmes
│   │   ├── font-manager.js               # Personnalisation polices
│   │   └── ui.js                         # Utilitaires UI
│   ├── package.json
│   ├── package-lock.json
│   └── vite.config.js
├── static/                               # Assets statiques servis
│   ├── dist/                             # JS compilé (généré par Vite)
│   │   ├── personotes-frontend.es.js
│   │   └── personotes-frontend.umd.js
│   ├── theme.css                         # Feuille de style principale
│   └── themes.css                        # 8 thèmes sombres
├── templates/                            # Templates HTML Go
│   ├── index.html                        # Page principale
│   ├── editor.html                       # Composant éditeur
│   ├── file-tree.html                    # Sidebar arborescence
│   ├── search-results.html               # Résultats recherche
│   ├── favorites.html                    # Liste favoris
│   ├── daily-calendar.html               # Calendrier notes quotidiennes
│   ├── daily-recent.html                 # Notes quotidiennes récentes
│   └── new-note-prompt.html              # Modal nouvelle note
├── notes/                                # Répertoire des notes utilisateur
│   ├── *.md                              # Fichiers Markdown
│   ├── daily/                            # Notes quotidiennes
│   ├── .favorites.json                   # Liste favoris (auto-généré)
│   └── daily-note-template.md            # Template optionnel notes quotidiennes
├── docs/                                 # Documentation
│   ├── KEYBOARD_SHORTCUTS.md             # Référence raccourcis
│   ├── DAILY_NOTES.md                    # Guide notes quotidiennes
│   ├── USAGE_GUIDE.md                    # Guide utilisation complet
│   ├── THEMES.md                         # Documentation thèmes
│   └── FREEBSD_BUILD.md                  # Guide build FreeBSD
├── go.mod                                # Dépendances Go
├── go.sum
├── API.md                                # Documentation API REST
├── ARCHITECTURE.md                       # Architecture détaillée
├── CHANGELOG.md                          # Historique des versions
├── README.md                             # README principal
├── CLAUDE.md                             # Guide pour Claude
├── GEMINI.md                             # Guide pour Gemini
└── COPILOT.md                            # Ce fichier

Fichiers clés à modifier

Développement Backend:

  • cmd/server/main.go - Initialisation serveur et routes
  • internal/api/handler.go - Endpoints HTML et gestion requêtes
  • internal/api/rest_handler.go - API REST v1
  • internal/api/daily_notes.go - Fonctionnalités notes quotidiennes
  • internal/api/favorites.go - Gestion favoris
  • internal/indexer/indexer.go - Logique recherche et indexation
  • internal/watcher/watcher.go - Surveillance filesystem

Développement Frontend:

  • frontend/src/editor.js - Éditeur, preview, commandes slash
  • frontend/src/vim-mode-manager.js - Intégration Vim
  • frontend/src/search.js - Modal recherche
  • frontend/src/link-inserter.js - Modal liens internes
  • frontend/src/file-tree.js - Interactions arborescence
  • frontend/src/favorites.js - Système favoris
  • frontend/src/daily-notes.js - Création notes quotidiennes
  • frontend/src/keyboard-shortcuts.js - Raccourcis clavier
  • frontend/src/theme-manager.js - Logique thèmes
  • frontend/src/font-manager.js - Personnalisation polices
  • static/theme.css - Styles et théming
  • templates/*.html - Templates HTML (syntaxe Go template)

Configuration:

  • frontend/vite.config.js - Configuration build frontend
  • frontend/package.json - Dépendances NPM et scripts
  • go.mod - Dépendances Go

Notes importantes

  1. Build frontend obligatoire: L'application ne fonctionne pas sans le JS compilé dans static/dist/
  2. Pas de hot reload frontend: Changements dans frontend/src/ nécessitent npm run build + refresh navigateur
  3. Changements backend: Nécessitent redémarrage serveur Go (go run ./cmd/server)
  4. Changements templates: Nécessitent redémarrage serveur (templates pré-parsés au démarrage)
  5. Changements CSS: Nécessitent seulement refresh navigateur (chargé via <link>)
  6. Changements notes: Détectés automatiquement par le watcher, déclenchent ré-indexation

Documentation complémentaire

  • API.md - Documentation complète API REST avec exemples
  • ARCHITECTURE.md - Architecture détaillée du projet
  • CHANGELOG.md - Historique des versions et changements
  • docs/KEYBOARD_SHORTCUTS.md - Référence complète raccourcis clavier
  • docs/DAILY_NOTES.md - Guide fonctionnalités notes quotidiennes
  • docs/USAGE_GUIDE.md - Guide utilisation complet application
  • docs/THEMES.md - Documentation système de thèmes
  • docs/FREEBSD_BUILD.md - Instructions build pour FreeBSD

Contributions futures

Les contributions futures avec GitHub Copilot seront documentées ci-dessous avec:

  • Date de la session
  • Contexte et objectifs
  • Actions effectuées
  • Résultats obtenus
  • Apprentissages et notes techniques

Dernière mise à jour: 12 novembre 2025