NimPulse/README.md

# NimPulse

Timer **Pomodoro nouvelle génération** pour Windows, écrit entièrement en
**Nim**. Il vit discrètement dans la zone de notification (system tray) et
prend soin de votre santé autant que de votre productivité, dans une interface
**simple et intuitive** pour tous : non-techniciens, étudiants, développeurs.

## Fonctionnalités

- **Icône tray** : démarre minimisé, menu contextuel complet, icône colorée
  dynamique selon l'état (travail / pause courte / pause longue / en pause),
  tooltip avec le temps restant.
- **Assistant de premier lancement** : en quelques étapes (langue, profil,
  rappels santé), l'application est prête sans toucher à un fichier.
- **Panneau de réglages graphique** : durées, objectif journalier, son, mode
  « Ne pas déranger », démarrage avec Windows, langue, rappels santé. Plus
  besoin d'éditer le JSON à la main.
- **Internationalisation** : français et anglais (détection automatique de la
  langue système ou choix manuel).
- **Timer personnalisable** : durées de travail / pause courte / pause longue,
  nombre de cycles avant pause longue, et **profils** (« Classique »,
  « Deep Work » 50/10, « Sprint » 15/3).
- **Contrôle des pauses** : sauter la pause, la prolonger de 5 minutes.
- **Objectif journalier** : définissez un nombre de pomodoros par jour et
  recevez une notification quand il est atteint.
- **Rappels santé intelligents** (le différenciateur) : notifications rotatives
  pendant les pauses (« Lève-toi et marche », « Bois un verre d'eau »,
  « Fais 10 push-ups », règle 20-20-20, étirements…), **entièrement modifiables**
  (ajouter / modifier / supprimer / activer-désactiver vos propres activités),
  sans répéter deux fois le même rappel.
- **Notifications Windows natives** (toast via `Shell_NotifyIcon` + `NIF_INFO`)
  et son optionnel en fin de période.
- **Statistiques enrichies** : pomodoros complétés (jour / semaine / total),
  streak de jours consécutifs, historique des 7 derniers jours, **export CSV**.
- **Raccourci global** `Ctrl+Alt+P` (configurable) pour démarrer/mettre en
  pause, sans toucher la souris.
- **Fenêtre flottante** : un petit panneau toujours au-dessus, draggable, qui
  affiche la phase et le temps restant en grand (pratique et lisible d'un coup
  d'œil).
- **Mono-instance** : lancer le programme une seconde fois ne crée pas de
  doublon.
- **Mode portable** : placez un fichier vide `portable` à côté de l'exécutable
  et la configuration est stockée au même endroit (pratique sur clé USB).
- **Mise à jour automatique** (optionnelle) : vérification en arrière-plan,
  notification si une version plus récente est disponible.
- **Pages web locales** : aide, statistiques et réglages présentés sous forme de
  pages HTML servies localement par l'application (127.0.0.1) et ouvertes dans
  le navigateur par défaut — aucune donnée ne quitte l'ordinateur.

## Prérequis

- [Nim](https://nim-lang.org) ≥ 2.0 (testé avec 2.2.10)
- La bibliothèque [winim](https://github.com/khchen/winim) :

  ```bash
  nimble install winim
  ```

- Le framework GUI [wNim](https://github.com/khchen/wNim) :

  ```bash
  nimble install wnim
  ```

  > **Important (Nim 2.2.x)** : wNim 1.0.0 contient deux bugs de compilation
  > avec Nim 2.2.x. Appliquez ces deux correctifs dans
  > `~/.nimble/pkgs2/wnim-*/wnim/` :
  > 1. `private/kiwi/strength.nim` : remplacer les 4 `const X = createStrength(...)`
  >    par des littéraux (`REQUIRED = 1000.0`, `STRONG = 1000000.0`,
  >    `MEDIUM = 1000.0`, `WEAK = 1.0`).
  > 2. `private/wResizer.nim` : remplacer `initHashSet[wResizable]()` par
  >    `HashSet[wTypes.wResizable]()`.
  > Voir les issues wNim [#125](https://github.com/khchen/wNim/issues/125) et
  > [#133](https://github.com/khchen/wNim/issues/133).

## Compilation

```bash
nim c -d:release --app:gui src/nimpulse.nim
```

Le binaire résultant `src/nimpulse.exe` est autonome (aucune dépendance
externe à installer) et pèse environ 1,4 Mo.

> **Note** : à l'édition de liens, `winim` injecte son propre fichier de
> ressources (styles visuels / manifeste), ce qui peut produire l'avertissement
> bénin `ld.exe: .rsrc merge failure: multiple non-default manifests`. Il est
> sans effet sur le fonctionnement. Pour le supprimer, compilez avec
> `-d:noRes` (vous perdrez alors les styles visuels des boîtes de dialogue).

## Distribution

- **Binaire autonome** : `src\nimpulse.exe` (ou `build\nimpulse.exe`).
- **Installeur une-ligne (Windows)** :

  ```powershell
  irm https://git.dracodev.net/Projets/NimPulse/-/raw/main/install.ps1 | iex
  ```

  Le script [`install.ps1`](install.ps1) télécharge le binaire et crée un
  raccourci sur le bureau.
- **Archive portable** : lancez [`release.cmd`](release.cmd) pour compiler et
  créer `build\NimPulse-portable.zip` (version prête à copier sur une clé USB).
- **Installeur classique** : un script [Inno Setup](installer/nimpulse.iss) est
  fourni. Compilez-le avec [Inno Setup 6](https://jrsoftware.org/isinfo.php).

## Configuration

Au premier lancement (et à la sortie), l'application crée :

```
%APPDATA%\NimPulse\
├── config.json   # réglages, profils, rappels santé
└── stats.json    # statistiques
```

En **mode portable**, ces fichiers sont créés à côté de l'exécutable.

Un exemple de configuration est fourni dans
[`config.example.json`](config.example.json).

### Structure de `config.json`

| Clé                     | Type    | Description                                      |
|-------------------------|---------|--------------------------------------------------|
| `workMin`               | int     | Durée de travail (défaut 25)                     |
| `shortBreakMin`         | int     | Pause courte (défaut 5)                          |
| `longBreakMin`          | int     | Pause longue (défaut 15)                         |
| `cyclesBeforeLongBreak` | int     | Cycles avant pause longue (défaut 4)             |
| `soundEnabled`          | bool    | Son en fin de période                            |
| `doNotDisturb`          | bool    | Mode « Ne pas déranger »                         |
| `autoStart`             | bool    | Démarrage avec Windows                           |
| `activeProfile`         | string  | Nom du profil actif                              |
| `lang`                  | string  | `"auto"`, `"fr"` ou `"en"`                       |
| `dailyGoal`             | int     | Objectif de pomodoros par jour (0 = aucun)       |
| `hotkeyModifiers`       | int     | Modificateurs du raccourci global (Ctrl+Alt = 3) |
| `hotkeyVk`              | int     | Code de touche virtuelle du raccourci (`P` = 80) |
| `soundName`             | string  | Alias sonore système (fin de période)            |
| `floatingWindow`        | bool    | Affiche la fenêtre flottante                     |
| `profiles`              | array   | Liste des profils (`name`, durées, `cycles`)     |
| `healthReminders`       | array   | Rappels santé (`text`, `enabled`)                |

## Architecture du code

```
src/
├── nimpulse.nim      # point d'entrée : fenêtre cachée, boucle de messages,
│                      #   WM_TIMER, raccourci global, mono-instance, câblage
├── config.nim         # Config/Profile/HealthReminder/Lang, JSON, registre (Run)
├── timer.nim          # machine à états Pomodoro (aucune dépendance Win32)
├── tray.nim           # Shell_NotifyIcon, icône dynamique (GDI), menu contextuel
├── notifications.nim  # toast (NIF_INFO), son, rotation des rappels santé
├── stats.nim          # compteurs jour/semaine/total, streak, CSV, JSON
├── i18n.nim           # chaînes localisées (français / anglais), détection langue
├── dialogs.nim        # réglages, rappels santé, assistant, stats (wNim)
├── floating.nim       # fenêtre flottante compacte (toujours au-dessus)
├── updater.nim        # comparaison de versions + récupération distante
└── webserver.nim      # serveur HTTP local (127.0.0.1) : pages aide / stats /
                       #   réglages, routage, rendu HTML, formulaire de sauvegarde
```

Séparation des responsabilités : `timer`, `stats` et `updater` sont purs
(aucune dépendance à l'API Win32), ce qui les rend testables ; `config`,
`tray`, `notifications`, `dialogs` et `nimpulse` gèrent l'interaction avec
Windows.

## Raccourcis

| Action                        | Raccourci      |
|-------------------------------|----------------|
| Démarrer / mettre en pause    | `Ctrl+Alt+P`   |
| Menu contextuel               | Clic droit     |
| Démarrer / mettre en pause    | Double-clic    |

## Pages web locales (aide, statistiques, réglages)

Depuis le menu de l'icône, « Aide », « Statistiques » et « Réglages » ouvrent
des pages HTML **servies localement** par l'application elle-même :

- Le menu **Aide** explique le fonctionnement de l'application (périodes,
  pauses, rappels santé, raccourcis, astuces).
- **Statistiques** affiche les pomodoros du jour / semaine, la série de jours
  consécutifs, le total et l'historique des 7 derniers jours.
- **Réglages** présente un formulaire complet (durées, objectif, son, langue,
  rappels santé) avec un **éditeur de périodes** : créez, modifiez ou supprimez
  vos propres profils (nom, travail, pauses, cycles) et choisissez la période
  active. L'enregistrement est appliqué immédiatement par l'application.

L'application lance un petit serveur sur `127.0.0.1` (premier port libre à
partir de `38943`), uniquement accessible en local. Aucune donnée ne quitte
l'ordinateur. Si le serveur est indisponible, les menus retombent sur les
dialogues natifs.

## Tests

Les modules purs (`timer`, `stats`, `config`, `notifications`, `updater`,
`webserver`) sont testés unitairement, ainsi que l'intégration Win32
(`tray`). Un exécutable unique les lance toutes et affiche un résumé :

```bash
run_tests.cmd
```

Ou individuellement :

```bash
nim c -r tests/test_timer.nim
nim c -r tests/test_stats.nim
nim c -r tests/test_config.nim
nim c -r tests/test_notifications.nim
nim c -r tests/test_tray_integration.nim
nim c -r tests/test_updater.nim
nim c -r tests/test_floating.nim
nim c -r tests/test_webserver.nim
```

La correspondance exigence → contrôle → résultat est détaillée dans
[`VERIFICATION.md`](VERIFICATION.md).

## Licence

MIT