clip-sync/README.md

# clip-sync

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go)](https://go.dev)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-100%25-brightgreen)](.)

**Daemon de synchronisation bidirectionnelle du presse-papiers sur réseau local.**

Copier sur une machine → coller sur une autre, automatiquement et instantanément.

```
┌──────────────┐         POST /clip          ┌──────────────┐
│  Machine A   │◄──────────────────────────►│  Machine B   │
│  (bureau)    │    {text, ts, origin}       │  (portable)  │
│  :9137       │                             │  :9137       │
└──────────────┘                             └──────────────┘
```

## Fonctionnalités

- **Bidirectionnel** — copie A → B et B → A, chaque nœud est client et serveur
- **Anti-boucle** — double filtre (hash SHA-256 + timestamp/origine) empêche le ping-pong
- **Sécurité** — clé partagée (Bearer token), validation d'origine, TLS optionnel
- **Découverte mDNS** — détection automatique des pairs (optionnelle)
- **Historique** — derniers clips conservés (`clip-sync history`)
- **Transfert de fichiers** — `clip-sync send-file` (réception optionnelle)
- **Interface web** — monitoring local sur `http://localhost:9137/`
- **Multi-plateforme** — Linux (X11/Wayland), Windows, macOS
- **Binaire unique** — zéro runtime externe, compilation Go native
- **Configuration simple** — fichier TOML + variables d'environnement
- **LAN uniquement** — aucune donnée ne quitte votre réseau local

## Installation

### Méthode 1 : Script automatique (tous OS)

```bash
curl -sSL https://git.dracodev.net/Projets/clip-sync/raw/branch/main/install.sh | bash
```

Le script détecte OS + architecture, télécharge le binaire, l'installe dans `~/.local/bin/` et crée une config par défaut.

---

### Méthode 2 : Instructions détaillées par OS

#### 🐧 Linux (X11 ou Wayland)

**1. Installer les dépendances**

| Distribution | X11 | Wayland |
|---|---|---|
| **Debian / Ubuntu** | `sudo apt install xclip` | `sudo apt install wl-clipboard` |
| **Arch / Manjaro** | `sudo pacman -S xclip` | `sudo pacman -S wl-clipboard` |
| **Fedora / RHEL** | `sudo dnf install xclip` | `sudo dnf install wl-clipboard` |
| **Alpine** | `sudo apk add xclip` | `sudo apk add wl-clipboard` |

clip-sync détecte automatiquement X11 vs Wayland via `$XDG_SESSION_TYPE`.

**2. Télécharger le binaire**

```bash
# amd64
curl -sSL -o ~/.local/bin/clip-sync \
  https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-linux-amd64
chmod +x ~/.local/bin/clip-sync

# arm64 (Raspberry Pi, etc.)
curl -sSL -o ~/.local/bin/clip-sync \
  https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-linux-arm64
chmod +x ~/.local/bin/clip-sync
```

**3. Vérifier le PATH**

```bash
# Ajouter ~/.local/bin au PATH si ce n'est pas déjà fait
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**4. Vérifier l'installation**

```bash
clip-sync --version
# → clip-sync v0.2.0
```

**5. Installer comme service (systemd --user)**

```bash
mkdir -p ~/.config/systemd/user/
curl -sSL -o ~/.config/systemd/user/clip-sync.service \
  https://git.dracodev.net/Projets/clip-sync/raw/branch/main/clip-sync.service
systemctl --user daemon-reload
systemctl --user enable --now clip-sync
systemctl --user status clip-sync
```

---

#### 🍎 macOS

**1. Aucune dépendance externe** — `pbpaste`/`pbcopy` sont intégrés à macOS.

**2. Télécharger le binaire**

```bash
# Apple Silicon (M1/M2/M3)
curl -sSL -o ~/.local/bin/clip-sync \
  https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-darwin-arm64
chmod +x ~/.local/bin/clip-sync

# Intel Mac
curl -sSL -o ~/.local/bin/clip-sync \
  https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-darwin-amd64
chmod +x ~/.local/bin/clip-sync
```

**3. Vérifier le PATH**

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**4. Vérifier l'installation**

```bash
clip-sync --version
# → clip-sync v0.2.0
```

**5. Installer comme service (launchd)**

```bash
cat > ~/Library/LaunchAgents/com.clip-sync.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.clip-sync</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/$(whoami)/.local/bin/clip-sync</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/$(whoami)/Library/Logs/clip-sync.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/$(whoami)/Library/Logs/clip-sync.err</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.clip-sync.plist
launchctl list | grep clip-sync
```

---

#### 🪟 Windows

**1. Aucune dépendance externe** — clip-sync utilise l'API Win32 native (user32.dll, kernel32.dll) sans CGo ni runtime externe.

**2. Télécharger le binaire**

```powershell
# amd64 (standard)
Invoke-WebRequest -Uri `
  "https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-windows-amd64.exe" `
  -OutFile "$env:USERPROFILE\bin\clip-sync.exe"

# arm64 (Surface Pro X, etc.)
Invoke-WebRequest -Uri `
  "https://git.dracodev.net/Projets/clip-sync/releases/download/v0.2.0/clip-sync-windows-arm64.exe" `
  -OutFile "$env:USERPROFILE\bin\clip-sync.exe"
```

**3. Ajouter au PATH**

```powershell
# PowerShell (admin) — permanent
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\bin",
  "User"
)
```

**4. Vérifier l'installation** (redémarrer le terminal après l'étape 3)

```powershell
clip-sync --version
# → clip-sync v0.2.0
```

**5. Installer comme service Windows (NSSM)**

Télécharger [NSSM](https://nssm.cc/download) et l'extraire, puis :

```powershell
nssm install clip-sync %USERPROFILE%\bin\clip-sync.exe
nssm set clip-sync AppStdout %USERPROFILE%\AppData\Local\clip-sync\stdout.log
nssm set clip-sync AppStderr %USERPROFILE%\AppData\Local\clip-sync\stderr.log
nssm set clip-sync AppStdoutCreationDisposition 4
nssm set clip-sync AppStderrCreationDisposition 4
nssm start clip-sync
```

**6. Pare-feu Windows** — la première exécution peut déclencher une alerte. Autoriser l'accès réseau privé.

---

### Compilation depuis les sources

Prérequis : [Go 1.21+](https://go.dev/dl/)

```bash
git clone https://git.dracodev.net/Projets/clip-sync.git
cd clip-sync
make build        # binaire dans ./bin/
make install      # copie vers ~/.local/bin/
```

## Démarrage rapide

### 1. Créer la configuration

```bash
mkdir -p ~/.config/clip-sync
```

**Machine A** (bureau, 192.168.1.10) :

```toml
# ~/.config/clip-sync/peers.toml
[daemon]
port = 9137
poll_interval_ms = 500

[[peers]]
name = "portable"
addr = "192.168.1.20:9137"
```

**Machine B** (portable, 192.168.1.20) :

```toml
# ~/.config/clip-sync/peers.toml
[daemon]
port = 9137
poll_interval_ms = 500

[[peers]]
name = "bureau"
addr = "192.168.1.10:9137"
```

### 2. Lancer le daemon

```bash
clip-sync
```

### 3. Tester

Copiez du texte sur la machine A (Ctrl+C), collez sur la machine B (Ctrl+V).
Ça marche !

## Configuration

### Fichier TOML

| Clé | Défaut | Description |
|-----|--------|-------------|
| `daemon.port` | `9137` | Port d'écoute HTTP(S) |
| `daemon.poll_interval_ms` | `500` | Intervalle de scrutation du presse-papiers (ms) |
| `daemon.max_body_bytes` | `10485760` | Taille max d'une requête (10 MiB) |
| `daemon.history_size` | `50` | Nombre d'entrées conservées dans l'historique |
| `daemon.discovery` | `false` | Découverte automatique des pairs via mDNS |
| `daemon.notify` | `false` | Notifications desktop à chaque clip reçu |
| `daemon.sync_images` | `false` | Sync d'images (PNG) entre pairs |
| `daemon.receive_files` | `false` | Accepter les transferts de fichiers |
| `daemon.receive_dir` | `~/Downloads/clip-sync` | Dossier de réception des fichiers |
| `security.shared_key` | — | Clé partagée (`clip-sync --generate-key`) |
| `security.allowed_origins` | — | Liste des hôtes autorisés |
| `security.tls` | `false` | Chiffrement TLS entre pairs |
| `security.cert_file` / `key_file` | `~/.config/clip-sync/{cert,key}.pem` | Certificat auto-signé |
| `peers[].name` | — | Nom descriptif du pair |
| `peers[].addr` | — | Adresse `host:port` du pair |
| `peers[].tls` | `false` | TLS pour ce pair (override global) |

### Variables d'environnement (override)

| Variable | Équivalent TOML |
|----------|-----------------|
| `CLIP_SYNC_PORT` | `daemon.port` |
| `CLIP_SYNC_POLL_MS` | `daemon.poll_interval_ms` |
| `CLIP_SYNC_KEY` | `security.shared_key` |
| `CLIP_SYNC_MAX_BODY_BYTES` | `daemon.max_body_bytes` |

## Commandes

```bash
clip-sync                          # lancer le daemon
clip-sync --config <path>          # config personnalisée
clip-sync --version                # afficher la version
clip-sync history                  # afficher l'historique local
clip-sync --one-shot [text]        # envoyer le presse-papiers (ou text) une fois
clip-sync send-file <path>         # envoyer un fichier aux pairs
clip-sync --generate-key           # générer une clé partagée
clip-sync --generate-cert          # générer un certificat TLS auto-signé
```

## Sécurité

Sur un réseau partagé, activez au minimum une clé partagée :

```bash
clip-sync --generate-key   # → copier la clé sur toutes les machines
```

```toml
[security]
shared_key = "LA_CLÉ_GÉNÉRÉE"
```

Pour chiffrer le trafic, générez un certificat sur une machine, copiez les
fichiers `cert.pem`/`key.pem` vers toutes les autres, puis :

```toml
[security]
tls = true
insecure_skip_verify = true   # confiance au certificat auto-signé partagé
```

## Déboguer

```bash
# Tester la connectivité entre pairs
curl -X POST http://192.168.1.20:9137/clip \
  -H 'Content-Type: application/json' \
  -d '{"text":"test","ts":0,"origin":"debug"}'
```

L'interface de monitoring est disponible sur `http://localhost:9137/` après le démarrage du daemon.

## Licence

MIT © 2026