##############################################################################
####### SYNC BOOKMARKS #######################################################
##############################################################################

Outil Python autonome de synchronisation de favoris pour Google Chrome
et Mozilla Firefox, a partir d'une source JSON distante.

Le script est distribue sous la forme d'un fichier unique Python,
simple a telecharger, a executer et a utiliser.

##############################################################################
####### AUTEUR ###############################################################
##############################################################################

Auteur :
- Bastien Schneider @baschnei

##############################################################################
####### CONTENU DU PACK ######################################################
##############################################################################

Le pack de livraison contient les fichiers suivants :

- sync_bookmarks.py
  Script principal

- README.txt
  Documentation utilisateur

- requirements.txt
  Dependances Python

- run.bat
  Lanceur Windows

- run.command
  Lanceur macOS


##############################################################################
####### VUE D'ENSEMBLE #######################################################
##############################################################################

sync_bookmarks.py permet de :

- telecharger une liste de favoris depuis une API JSON
- creer ou recreer un dossier racine de favoris
- organiser les favoris par categories
- injecter ces favoris dans :
  - la barre de favoris Chrome
  - la barre personnelle Firefox

Le script propose :
- une CLI pilotable par arguments
- un mode interactif guide
- un mode de simulation sans ecriture
- une option de sauvegarde avant modification


##############################################################################
####### FONCTIONNALITES ######################################################
##############################################################################

- Synchronisation vers Chrome
- Synchronisation vers Firefox
- Detection automatique des navigateurs disponibles
- Mode interactif par defaut si aucun argument n'est fourni
- Sous-commandes disponibles :
  - sync
  - check
  - doctor
- Mode dry-run
- Sauvegarde avant modification avec --backup
- Sortie texte ou JSON
- Fichier unique Python
- Compatible macOS et Windows


##############################################################################
####### PREREQUIS ############################################################
##############################################################################

- Python 3.10 ou superieur recommande
- Module Python requis :
  - requests

Installation :

    pip install requests

ou via le fichier requirements.txt :

    pip install -r requirements.txt


##############################################################################
####### INSTALLATION #########################################################
##############################################################################

1. Telechargez ou copiez tous les fichiers du pack dans un meme dossier

2. Installez la dependance Python :

    pip install -r requirements.txt

3. Lancez le script :
   - directement avec Python
   - ou via le lanceur adapte a votre systeme


##############################################################################
####### LANCEMENT RAPIDE #####################################################
##############################################################################

----- Windows ---------------------------------------------------------------

Lancement direct :

    python sync_bookmarks.py

ou :

    run.bat


----- macOS -----------------------------------------------------------------

Lancement direct :

    python3 sync_bookmarks.py

ou :

    ./run.command

Si necessaire, rendez le fichier executable une premiere fois :

    chmod +x run.command


##############################################################################
####### UTILISATION ##########################################################
##############################################################################

Si le script est lance sans argument, il demarre automatiquement
en mode interactif :

    python sync_bookmarks.py

Le mode guide permet de choisir :
- Chrome
- Firefox
- les deux
- automatique


##############################################################################
####### COMMANDES ############################################################
##############################################################################

----- sync -------------------------------------------------------------------

Synchronise les favoris vers un ou plusieurs navigateurs.

----- check ------------------------------------------------------------------

Verifie quels navigateurs sont detectes et disponibles.

----- doctor -----------------------------------------------------------------

Affiche un diagnostic detaille de l'environnement.


##############################################################################
####### OPTIONS PRINCIPALES ##################################################
##############################################################################

----- --browser --------------------------------------------------------------

Definit le navigateur cible.

Valeurs possibles :
- auto
- chrome
- firefox
- all

Exemple :

    python sync_bookmarks.py sync --browser auto


----- --interactive ----------------------------------------------------------

Force l'utilisation du mode guide.

Exemple :

    python sync_bookmarks.py sync --interactive


----- --dry-run --------------------------------------------------------------

Simule la synchronisation sans ecrire de modifications.

Exemple :

    python sync_bookmarks.py sync --browser all --dry-run


----- --backup ---------------------------------------------------------------

Cree une sauvegarde avant modification.

Exemple :

    python sync_bookmarks.py sync --browser all --backup


----- --backup-dir -----------------------------------------------------------

Specifie un repertoire personnalise pour les sauvegardes.

Exemple :

    python sync_bookmarks.py sync --browser chrome --backup --backup-dir "./backups"


----- --prefix ---------------------------------------------------------------

Definit le nom du dossier racine de favoris a creer.

Exemple :

    python sync_bookmarks.py sync --browser chrome --prefix "[SET]"


----- --source-url -----------------------------------------------------------

Permet de surcharger l'URL source du JSON.

Exemple :

    python sync_bookmarks.py sync --browser all --source-url "https://example.com/bookmarks"


----- --output ---------------------------------------------------------------

Format de sortie :
- text
- json

Exemple :

    python sync_bookmarks.py doctor --output json


----- --log-level ------------------------------------------------------------

Niveau de logs :
- DEBUG
- INFO
- WARNING
- ERROR
- CRITICAL

Exemple :

    python sync_bookmarks.py sync --browser firefox --log-level DEBUG


##############################################################################
####### EXEMPLES #############################################################
##############################################################################

Verifier les navigateurs disponibles :

    python sync_bookmarks.py check

Afficher un diagnostic detaille :

    python sync_bookmarks.py doctor

Synchroniser automatiquement les navigateurs detectes :

    python sync_bookmarks.py sync --browser auto

Synchroniser Chrome uniquement :

    python sync_bookmarks.py sync --browser chrome

Synchroniser Firefox uniquement :

    python sync_bookmarks.py sync --browser firefox

Synchroniser les deux avec sauvegarde :

    python sync_bookmarks.py sync --browser all --backup

Simuler sans ecriture :

    python sync_bookmarks.py sync --browser all --dry-run

Obtenir une sortie JSON :

    python sync_bookmarks.py doctor --output json


##############################################################################
####### COMPORTEMENT PAR NAVIGATEUR ##########################################
##############################################################################

----- GOOGLE CHROME ----------------------------------------------------------

Le script modifie le fichier "Bookmarks" du profil principal Chrome.

Fonctionnement :
- suppression du dossier cible s'il existe deja
- recreation du dossier dans la barre de favoris
- ajout des sous-dossiers par categories
- ajout des favoris
- ecriture atomique du fichier JSON


----- MOZILLA FIREFOX --------------------------------------------------------

Le script modifie directement la base SQLite "places.sqlite".

Fonctionnement :
- detection du profil Firefox
- verification du verrouillage de la base
- suppression du dossier cible s'il existe deja
- recreation dans la barre personnelle
- ajout des categories et favoris

IMPORTANT :
Firefox doit etre ferme pendant l'execution.


##############################################################################
####### SAUVEGARDES ##########################################################
##############################################################################

Lorsque l'option --backup est utilisee, une copie du fichier source
est creee avant modification :

- Chrome : sauvegarde du fichier Bookmarks
- Firefox : sauvegarde du fichier places.sqlite

Par defaut, les sauvegardes sont stockees dans un dossier :

    bookmark_backups

cree a cote du fichier source.

Un repertoire personnalise peut etre defini avec --backup-dir.


##############################################################################
####### CODES DE RETOUR ######################################################
##############################################################################

Le script retourne les codes suivants :

- 0 : execution reussie
- 2 : erreur metier ou echec fonctionnel
- 3 : erreur inattendue


##############################################################################
####### COMPATIBILITE ########################################################
##############################################################################

Systemes supportes :
- macOS
- Windows

Navigateurs supportes :
- Google Chrome
- Mozilla Firefox


##############################################################################
####### LIMITATIONS CONNUES ##################################################
##############################################################################

- Le script cible le profil principal de Chrome (Default)
- Pour Firefox, le profil Profile0 est prioritaire s'il existe,
  sinon le profil marque Default=1
- Firefox doit etre ferme pour permettre la modification de places.sqlite
- Le module requests doit etre disponible


##############################################################################
####### DEPANNAGE ############################################################
##############################################################################

----- No module named 'requests' ---------------------------------------------

Installez la dependance :

    pip install requests

ou :

    pip install -r requirements.txt


----- Chrome non detecte -----------------------------------------------------

Verifier :
- que Chrome est installe
- qu'un profil utilisateur Default existe


----- Firefox non detecte ----------------------------------------------------

Verifier :
- que Firefox est installe
- qu'un profil utilisateur existe
- que profiles.ini est present


----- Firefox verrouille -----------------------------------------------------

Fermez completement Firefox puis relancez la commande.


----- Erreur reseau ----------------------------------------------------------

Verifier :
- la connectivite reseau
- l'accessibilite de l'URL
- le format JSON renvoye


##############################################################################
####### BONNES PRATIQUES #####################################################
##############################################################################

Pour une premiere execution, il est recommande de suivre l'ordre suivant :

1. Verifier l'environnement :

    python sync_bookmarks.py check

2. Lancer un diagnostic :

    python sync_bookmarks.py doctor

3. Simuler la synchronisation :

    python sync_bookmarks.py sync --browser auto --dry-run

4. Executer la synchronisation avec sauvegarde :

    python sync_bookmarks.py sync --browser auto --backup