lcsc2kicad 0.1.0__tar.gz

lcsc2kicad-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/

lcsc2kicad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Votre nom]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lcsc2kicad-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: lcsc2kicad
+Version: 0.1.0
+Summary: Importe des composants LCSC/EasyEDA dans la librairie KiCad du projet courant (surcouche d'easyeda2kicad).
+License: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Requires-Python: >=3.10
+Requires-Dist: easyeda2kicad>=0.8
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lcsc2kicad
+
+Surcouche de [`easyeda2kicad`](https://github.com/uPesy/easyeda2kicad.py) : importe des
+composants LCSC/EasyEDA (symbole + empreinte + modèle 3D) dans la **librairie KiCad du projet**,
+avec le numéro LCSC conservé dans un champ du symbole.
+
+## Installation
+
+```bash
+pipx install lcsc2kicad        # ou : pip install lcsc2kicad
+```
+
+## Utilisation
+
+```bash
+lcsc2kicad C12345                      # import complet dans le projet courant
+lcsc2kicad C12345 --no-3d              # sans modèle 3D
+lcsc2kicad C123 C456 --project ~/kicad/DesktopHub
+lcsc2kicad --from-file refs.txt -y     # sans confirmation
+lcsc2kicad list                        # composants de la librairie
+lcsc2kicad remove C12345               # supprime symbole (+ empreinte/3D devenus inutiles)
+lcsc2kicad init                        # facultatif : crée dossiers + .lcsc2kicad.toml
+
+lcsc2kicad config list                 # réglages effectifs et leur origine (défaut/global/projet)
+lcsc2kicad config set no_3d true       # modifie .lcsc2kicad.toml du projet
+lcsc2kicad config set --global projects_root ~/kicad   # config globale (-g)
+lcsc2kicad config get lcsc_field | unset no_3d | path
+```
+
+Choix du projet (ordre) : `--project` → sélecteur (si activé) → remontée depuis le dossier courant.
+Le projet retenu est affiché et confirmé avant toute écriture (`-y` pour désactiver ;
+un choix fait dans le sélecteur vaut confirmation).
+
+Chaque import affiche le **nom du composant** (nom du symbole) à côté de la référence LCSC.
+La référence est aussi ajoutée aux **mots-clés** du symbole (`ki_keywords`) : taper `C25804`
+dans le sélecteur de symboles de KiCad retrouve le composant (désactivable : `lcsc_keyword = false`).
+
+Librairie créée dans `libs/<projet>.kicad_sym`, `libs/<projet>.pretty/`, `libs/3dmodels/`.
+**À faire une seule fois dans KiCad** : Préférences > Gérer les librairies (onglet du projet),
+avec le même nom pour les symboles et les empreintes.
+
+## Configuration (TOML)
+
+Projet : `<projet>/.lcsc2kicad.toml` — global : `~/.config/lcsc2kicad/config.toml`
+(`%APPDATA%\lcsc2kicad\config.toml` sous Windows). Priorité : flags > projet > global > défauts.
+
+```toml
+# global uniquement
+projects_root = "~/kicad"
+use_selector  = true
+
+# global ou projet
+lib_dir = "libs"
+lib_name = "MaLib"         # défaut : nom du projet
+model_dir = "3dmodels"     # relatif à lib_dir
+lcsc_field = "LCSC"
+lcsc_keyword = true       # réf LCSC dans les mots-clés de recherche
+no_3d = false
+```
+
+## Développement
+
+```bash
+pip install -e ".[dev]" && pytest
+```

lcsc2kicad-0.1.0/README.md

@@ -0,0 +1,65 @@
+# lcsc2kicad
+
+Surcouche de [`easyeda2kicad`](https://github.com/uPesy/easyeda2kicad.py) : importe des
+composants LCSC/EasyEDA (symbole + empreinte + modèle 3D) dans la **librairie KiCad du projet**,
+avec le numéro LCSC conservé dans un champ du symbole.
+
+## Installation
+
+```bash
+pipx install lcsc2kicad        # ou : pip install lcsc2kicad
+```
+
+## Utilisation
+
+```bash
+lcsc2kicad C12345                      # import complet dans le projet courant
+lcsc2kicad C12345 --no-3d              # sans modèle 3D
+lcsc2kicad C123 C456 --project ~/kicad/DesktopHub
+lcsc2kicad --from-file refs.txt -y     # sans confirmation
+lcsc2kicad list                        # composants de la librairie
+lcsc2kicad remove C12345               # supprime symbole (+ empreinte/3D devenus inutiles)
+lcsc2kicad init                        # facultatif : crée dossiers + .lcsc2kicad.toml
+
+lcsc2kicad config list                 # réglages effectifs et leur origine (défaut/global/projet)
+lcsc2kicad config set no_3d true       # modifie .lcsc2kicad.toml du projet
+lcsc2kicad config set --global projects_root ~/kicad   # config globale (-g)
+lcsc2kicad config get lcsc_field | unset no_3d | path
+```
+
+Choix du projet (ordre) : `--project` → sélecteur (si activé) → remontée depuis le dossier courant.
+Le projet retenu est affiché et confirmé avant toute écriture (`-y` pour désactiver ;
+un choix fait dans le sélecteur vaut confirmation).
+
+Chaque import affiche le **nom du composant** (nom du symbole) à côté de la référence LCSC.
+La référence est aussi ajoutée aux **mots-clés** du symbole (`ki_keywords`) : taper `C25804`
+dans le sélecteur de symboles de KiCad retrouve le composant (désactivable : `lcsc_keyword = false`).
+
+Librairie créée dans `libs/<projet>.kicad_sym`, `libs/<projet>.pretty/`, `libs/3dmodels/`.
+**À faire une seule fois dans KiCad** : Préférences > Gérer les librairies (onglet du projet),
+avec le même nom pour les symboles et les empreintes.
+
+## Configuration (TOML)
+
+Projet : `<projet>/.lcsc2kicad.toml` — global : `~/.config/lcsc2kicad/config.toml`
+(`%APPDATA%\lcsc2kicad\config.toml` sous Windows). Priorité : flags > projet > global > défauts.
+
+```toml
+# global uniquement
+projects_root = "~/kicad"
+use_selector  = true
+
+# global ou projet
+lib_dir = "libs"
+lib_name = "MaLib"         # défaut : nom du projet
+model_dir = "3dmodels"     # relatif à lib_dir
+lcsc_field = "LCSC"
+lcsc_keyword = true       # réf LCSC dans les mots-clés de recherche
+no_3d = false
+```
+
+## Développement
+
+```bash
+pip install -e ".[dev]" && pytest
+```

lcsc2kicad-0.1.0/TESTING.md

@@ -0,0 +1,134 @@
+# Procédure de test manuel — lcsc2kicad
+
+Prérequis : Python ≥ 3.10, accès Internet (API EasyEDA), KiCad ≥ 6 installé.
+Composants de test (courants, avec empreinte et normalement un modèle 3D) :
+`C25804` (10 kΩ 0603), `C14663` (100 nF 0603), `C2040` (RP2040).
+Si une référence est introuvable, prenez-en une autre sur lcsc.com.
+
+## 0. Préparation
+
+```bash
+python -m venv /tmp/venv && source /tmp/venv/bin/activate      # Windows : .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest                                    # tests unitaires hors-ligne : tous verts
+lcsc2kicad --version
+mkdir -p ~/tmp-kicad/TestA ~/tmp-kicad/TestB
+touch ~/tmp-kicad/TestA/TestA.kicad_pro ~/tmp-kicad/TestB/TestB.kicad_pro
+```
+
+(Mieux : créez de vrais projets vides depuis KiCad pour les étapes 9 et 10.)
+
+## 1. Détection du projet (méthode A)
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 1.1 | `cd ~/tmp-kicad/TestA && lcsc2kicad C25804` | Affiche projet `TestA`, demande « Écrire dans ce projet ? » ; `n` → « annulé », rien créé |
+| 1.2 | Même commande, répondre Entrée | `C25804  ajouté (symbole, empreinte, 3D)` ; création de `libs/TestA.kicad_sym`, `libs/TestA.pretty/`, `libs/3dmodels/` ; rappel KiCad affiché |
+| 1.3 | `mkdir sub && cd sub && lcsc2kicad list` | Remonte jusqu'à `TestA` ; liste `C25804` avec empreinte `TestA:<nom>` (pas de confirmation pour `list`) |
+| 1.4 | `cd /tmp && lcsc2kicad list` | Erreur claire listant les 3 moyens de préciser le projet, code retour ≠ 0 |
+
+## 2. Import et options
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 2.1 | `lcsc2kicad C25804 -y` | `sauté (déjà présent : symbole)`, aucun appel réseau, rien modifié |
+| 2.2 | `lcsc2kicad C14663 --no-3d -y` | `ajouté (symbole, empreinte)` ; pas de `.wrl`/`.step` pour ce composant ; ligne `(model` absente de son `.kicad_mod` |
+| 2.3 | `lcsc2kicad C2040 --no-symbol --no-footprint -y` | Seul le 3D est ajouté ; `list` ne montre pas C2040 |
+| 2.4 | `lcsc2kicad C2040 --no-3d -y` | Ajoute symbole + empreinte (le 3D de 2.3 reste en place) |
+| 2.5 | `lcsc2kicad C25804 --force -y` | `ajouté` ; un seul symbole C25804 dans le `.kicad_sym` (pas de doublon) |
+| 2.6 | Fichier `refs.txt` : `C25804`, `C14663 # commentaire`, ligne vide, `C2040` puis `lcsc2kicad --from-file refs.txt -y` | 3 lignes de résultat, tout « sauté » |
+| 2.7 | `lcsc2kicad C99999999 C25804x -y` | Deux lignes `erreur` explicites ; code retour 1 ; les autres références du même appel sont quand même traitées |
+| 2.8 | `lcsc2kicad C25804 --force -v -y` | Sortie détaillée d'`easyeda2kicad` affichée |
+
+- 2.9 Vérifier que chaque ligne de résultat affiche le **nom du composant** après la référence (ex. `C25804  0603WAF1002T5E5  ajouté (…)`), y compris pour `sauté` et `remove`.
+
+## 3. Contenu des fichiers
+
+- 3.1 Ouvrir `libs/TestA.kicad_sym` dans un éditeur : chaque symbole contient `(property "LCSC" "C…" …)` ; la propriété `Footprint` vaut `TestA:<empreinte>`.
+- 3.2 Ouvrir un `.kicad_mod` : le chemin du modèle est `${KIPRJMOD}/libs/3dmodels/<nom>.wrl` (aucun chemin absolu ni temporaire).
+- 3.2 bis Chaque symbole contient aussi `(property "ki_keywords" "C…" …)`. Si le symbole avait déjà des mots-clés, la réf LCSC y est ajoutée une seule fois (relancer avec `--force` ne la duplique pas).
+- 3.3 Aucun fichier `.tmp` résiduel dans `libs/`. Les fichiers `sym-lib-table` / `fp-lib-table` du projet n'ont **pas** été modifiés.
+
+## 4. Intégration KiCad (point critique)
+
+1. Ouvrir `TestA` dans KiCad. Préférences > Gérer les librairies de symboles > onglet *Projet* : ajouter `TestA` avec `${KIPRJMOD}/libs/TestA.kicad_sym`. Idem pour les empreintes avec `${KIPRJMOD}/libs/TestA.pretty` (même nom `TestA`).
+2. Éditeur de schéma > placer un symbole : `TestA` apparaît avec ses composants ; champ `LCSC` visible dans les propriétés (masqué par défaut).
+3. Assigner l'empreinte (elle est déjà liée) et ouvrir l'éditeur PCB : empreinte et modèle 3D (visionneuse 3D) s'affichent.
+4. **Sans fermer KiCad**, lancer `lcsc2kicad C14663 -y` hors-KiCad, puis rouvrir le sélecteur de symboles : le nouveau symbole apparaît sans redémarrage.
+5. Dans le sélecteur de symboles, taper la référence (`C25804`) dans la barre de recherche : le composant ressort. Refaire avec `lcsc_keyword = false` sur un nouveau composant : il ne ressort plus par sa réf (le nom reste cherchable).
+6. Vérifier que KiCad n'affiche aucune erreur de format `.kicad_sym` (note le numéro de version de KiCad testé : points 10 de la spec).
+7. Exporter une BOM contenant le champ `LCSC` (ou tester avec JLCPCB Tools) : la colonne est bien reconnue.
+
+## 5. `list` et `remove`
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 5.1 | `lcsc2kicad list` | Tableau LCSC / Symbole / Empreinte, compteur correct |
+| 5.2 | `lcsc2kicad remove C14663 -y` | `supprimé (symbole, empreinte, 3D)` ; `list` ne le montre plus ; fichiers `.kicad_mod`, `.wrl`, `.step` supprimés |
+| 5.3 | Deux composants partageant la même empreinte (ex. deux résistances 0603) : supprimer l'un | L'empreinte et le 3D sont **conservés** ; supprimés au retrait du second |
+| 5.4 | `lcsc2kicad remove C00000 -y` | `erreur : composant introuvable`, code 1 |
+| 5.5 | `lcsc2kicad remove <nom du symbole> -y` | Fonctionne aussi par nom de symbole |
+
+## 6. `init` et configuration
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 6.1 | Dans `TestB` : `lcsc2kicad init` | Crée `libs/…`, `.lcsc2kicad.toml` (commenté), affiche les chemins à déclarer ; un `add` suivant n'affiche **pas** le rappel |
+| 6.2 | Dans `TestB/.lcsc2kicad.toml` : `lib_dir = "lib"`, `lib_name = "Perso"`, `lcsc_field = "LCSC Part"`, `no_3d = true` ; `lcsc2kicad C25804 -y` | Fichiers dans `lib/Perso.*` ; champ `LCSC Part` ; pas de 3D |
+| 6.3 | Même config, ajouter `--full` | Le 3D est importé malgré `no_3d = true` |
+| 6.4 | Config globale (`~/.config/lcsc2kicad/config.toml`, ou `%APPDATA%\lcsc2kicad\`) avec `lcsc_field = "MPN_LCSC"` et config projet avec `lcsc_field = "LCSC"` | Le projet l'emporte |
+| 6.5 | Clé inconnue ou mauvais type dans un TOML | Avertissement (clé inconnue) ou erreur claire (mauvais type) |
+
+### Commande `config`
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 6.6 | `lcsc2kicad config list` (dans un projet) | Tableau clé = valeur `[défaut/global/projet]` ; chemin du fichier affiché |
+| 6.7 | `lcsc2kicad config set no_3d true` (confirmation) | Écrit `no_3d = true` dans `<projet>/.lcsc2kicad.toml` ; `list` → origine `[projet]` ; commentaires du fichier conservés |
+| 6.8 | `lcsc2kicad config get no_3d` / `config path` | Affichent uniquement la valeur / le chemin (utilisable dans un script) |
+| 6.9 | `lcsc2kicad config unset no_3d -y` | Clé retirée ; second `unset` : « n'était pas défini » |
+| 6.10 | `lcsc2kicad config set --global projects_root ~/tmp-kicad` puis `config set -g use_selector true` | Crée/modifie le fichier global (`config path -g` donne son emplacement) ; pas de projet requis, depuis n'importe quel dossier |
+| 6.11 | `config set no_3d peut-être` / `config set projects_root x` (sans `-g`) / `config set foo 1` | Erreurs claires (valeur booléenne invalide, clé globale uniquement, clé inconnue + liste des clés valides) |
+| 6.12 | `config set lib_dir lib` puis `lcsc2kicad C25804 -y` | La librairie est créée dans `lib/` |
+
+## 7. Sélecteur (méthode C)
+
+Config globale :
+```toml
+projects_root = "~/tmp-kicad"
+use_selector = true
+```
+
+| # | Action | Résultat attendu |
+|---|---|---|
+| 7.1 | `cd /tmp && lcsc2kicad C25804` | Liste numérotée `TestA`, `TestB` ; choisir `2` → écrit dans `TestB` (sans seconde confirmation) |
+| 7.2 | Saisir `testa` (nom) | Sélectionne `TestA` |
+| 7.3 | `cd ~/tmp-kicad/TestA && lcsc2kicad C25804` puis Entrée | `TestA` présélectionné (`*`), Entrée valide |
+| 7.4 | `lcsc2kicad C25804 --project ~/tmp-kicad/TestB` | Pas de sélecteur : `--project` gagne ; confirmation demandée |
+| 7.5 | `projects_root` inexistant | Avertissement puis repli sur le dossier courant |
+| 7.6 | `cd ~/tmp-kicad/TestA && lcsc2kicad C25804 -y` | Pas de sélecteur (pas d'interaction avec `-y`) : utilise le projet courant |
+
+## 8. Terminal non interactif
+
+- 8.1 `lcsc2kicad C25804 < /dev/null` (Windows : `< NUL`) → erreur « terminal non interactif », code 2, rien écrit.
+- 8.2 `lcsc2kicad C25804 -y < /dev/null` → fonctionne.
+
+## 9. Cas limites
+
+- 9.1 Coupez le réseau : `lcsc2kicad C25804 --force -y` → `erreur` explicite, la librairie existante n'est pas corrompue.
+- 9.2 Projet dont le nom contient espaces/points (`Mon Projet v1.2`) : la librairie s'appelle `Mon_Projet_v1_2` ; import OK.
+- 9.3 Plusieurs `.kicad_pro` dans le même dossier : le premier par ordre alphabétique est utilisé.
+- 9.4 `lcsc2kicad` sans argument : affiche l'aide. `lcsc2kicad --project X` sans référence : erreur « aucune référence ».
+- 9.5 Ctrl+C pendant une confirmation : sortie propre (code 130), aucun fichier modifié.
+
+## 10. Windows (PowerShell et cmd)
+
+Reprendre 1.1–1.3, 2.2, 4 (KiCad Windows), 7.1 et 8 (`< NUL`). Vérifier : accents lisibles dans la console, chemins `${KIPRJMOD}/…` en `/`, `%APPDATA%\lcsc2kicad\config.toml` bien lu, `pipx install` fonctionnel.
+
+## 11. Installation depuis PyPI (après publication)
+
+```bash
+pipx install lcsc2kicad && lcsc2kicad --version
+pipx upgrade lcsc2kicad
+```
+Vérifier qu'`easyeda2kicad` est installé comme dépendance (`pipx runpip lcsc2kicad list`).

lcsc2kicad-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lcsc2kicad"
+version = "0.1.0"
+description = "Importe des composants LCSC/EasyEDA dans la librairie KiCad du projet courant (surcouche d'easyeda2kicad)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "easyeda2kicad>=0.8",
+    "tomli>=2.0; python_version < '3.11'",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+lcsc2kicad = "lcsc2kicad.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lcsc2kicad"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

lcsc2kicad-0.1.0/src/lcsc2kicad/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lcsc2kicad-0.1.0/src/lcsc2kicad/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

lcsc2kicad-0.1.0/src/lcsc2kicad/cli.py

@@ -0,0 +1,297 @@
+"""Interface en ligne de commande de lcsc2kicad."""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__, config, importer
+from . import library as lib
+from . import project as proj
+from .errors import CliError, ImportFailure, Lcsc2KicadError
+
+COMMANDS = {"add", "list", "remove", "init", "config"}
+LCSC_RE = re.compile(r"^C\d+$")
+
+
+@dataclass
+class Context:
+    project: proj.Project
+    settings: dict
+    paths: lib.LibPaths
+
+
+# ------------------------------------------------------------------ utilitaires
+def _confirm(question: str) -> bool:
+    try:
+        answer = input(f"{question} [O/n] ").strip().lower()
+    except EOFError:
+        return False
+    return answer in ("", "o", "oui", "y", "yes")
+
+
+def _prepare(args, write: bool, quiet: bool = False) -> Context:
+    interactive = sys.stdin.isatty()
+    if write and not args.yes and not interactive:
+        raise CliError("terminal non interactif : confirmation impossible, relancez avec -y")
+
+    gconf = config.load_global()
+    can_prompt = interactive and not (write and args.yes)
+    project, via_selector = proj.resolve(args.project, gconf, can_prompt)
+
+    overrides = {k: getattr(args, k, False) for k in ("no_symbol", "no_footprint", "no_3d", "full")}
+    settings = config.load_settings(project.dir, gconf, overrides)
+    paths = lib.LibPaths.build(project.dir, project.name, settings)
+
+    if not quiet:
+        print(f"Projet     : {project.name}")
+        print(f"Dossier    : {project.dir}")
+        print(f"Librairie  : {paths.sym}")
+    # Un choix explicite dans le sélecteur vaut confirmation.
+    if write and not args.yes and not via_selector:
+        if not _confirm("Écrire dans ce projet ?"):
+            raise CliError("annulé")
+    if not quiet:
+        print()
+    return Context(project, settings, paths)
+
+
+def _kicad_reminder(paths: lib.LibPaths) -> None:
+    print("\nRappel : déclarez la librairie dans KiCad (une seule fois par projet) :")
+    print("  Préférences > Gérer les librairies de symboles / d'empreintes > onglet « Projet »")
+    print(f"  Symboles   : nom « {paths.name} »  chemin {paths.sym_ref}")
+    print(f"  Empreintes : nom « {paths.name} »  chemin {paths.pretty_ref}")
+    print("  Le nom (nickname) doit être identique pour les deux : le symbole le référence.")
+
+
+def _collect_refs(args) -> list[str]:
+    refs = list(args.refs)
+    if args.from_file:
+        try:
+            lines = Path(args.from_file).expanduser().read_text(encoding="utf-8-sig").splitlines()
+        except OSError as exc:
+            raise CliError(f"lecture de {args.from_file} impossible : {exc}") from exc
+        for line in lines:
+            line = line.split("#", 1)[0].strip()
+            if line:
+                refs.append(line)
+    seen, out = set(), []
+    for r in refs:
+        r = r.strip().upper()
+        if r and r not in seen:
+            seen.add(r)
+            out.append(r)
+    if not out:
+        raise CliError("aucune référence LCSC fournie (ex. : lcsc2kicad C12345)")
+    return out
+
+
+# --------------------------------------------------------------------- commandes
+def cmd_add(args) -> int:
+    refs = _collect_refs(args)
+    ctx = _prepare(args, write=True)
+    created = lib.ensure_library(ctx.paths)
+
+    added = skipped = errors = 0
+    for ref in refs:
+        if not LCSC_RE.match(ref):
+            print(f"{ref:<11} erreur : référence LCSC invalide (attendu : C + chiffres)")
+            errors += 1
+            continue
+        try:
+            res = importer.import_one(ref, ctx.paths, ctx.settings, args.force, args.verbose)
+        except (ImportFailure, Lcsc2KicadError, OSError, ValueError) as exc:
+            print(f"{ref:<11} erreur : {exc}")
+            errors += 1
+            continue
+        if res.status == "added":
+            extra = f" ; conservé : {', '.join(res.kept)}" if res.kept else ""
+            print(f"{ref:<11} {res.name}  ajouté ({', '.join(res.wrote)}){extra}")
+            added += 1
+        else:
+            print(f"{ref:<11} {res.name}  sauté (déjà présent : {', '.join(res.kept)}) — --force pour écraser")
+            skipped += 1
+
+    print(f"\n{added} ajouté(s), {skipped} sauté(s), {errors} erreur(s)")
+    if created and added:
+        _kicad_reminder(ctx.paths)
+    return 1 if errors else 0
+
+
+def cmd_list(args) -> int:
+    ctx = _prepare(args, write=False)
+    if not ctx.paths.sym.exists():
+        print("Aucune librairie pour ce projet pour l'instant (lcsc2kicad add C…).")
+        return 0
+    field = ctx.settings["lcsc_field"]
+    syms = lib.parse_symbols(lib.read(ctx.paths.sym))
+    rows = sorted(((s.props.get(field, "-"), s.name, s.props.get("Footprint", "-")) for s in syms),
+                  key=lambda r: r[1].lower())
+    if not rows:
+        print("La librairie est vide.")
+        return 0
+    w0 = max(len(field), *(len(r[0]) for r in rows))
+    w1 = max(len("Symbole"), *(len(r[1]) for r in rows))
+    print(f"{field:<{w0}}  {'Symbole':<{w1}}  Empreinte")
+    for lcsc, name, fp in rows:
+        print(f"{lcsc:<{w0}}  {name:<{w1}}  {fp}")
+    print(f"\n{len(rows)} composant(s)")
+    return 0
+
+
+def cmd_remove(args) -> int:
+    refs = [r.strip() for r in args.refs if r.strip()]
+    if not refs:
+        raise CliError("indiquez au moins une référence LCSC ou un nom de symbole")
+    ctx = _prepare(args, write=True)
+    errors = 0
+    for ref in refs:
+        try:
+            name, removed = lib.remove_component(ctx.paths, ctx.settings["lcsc_field"], ref)
+            print(f"{ref:<11} {name}  supprimé ({', '.join(removed)})")
+        except (Lcsc2KicadError, OSError, ValueError) as exc:
+            print(f"{ref:<11} erreur : {exc}")
+            errors += 1
+    return 1 if errors else 0
+
+
+def cmd_init(args) -> int:
+    ctx = _prepare(args, write=True)
+    created = lib.ensure_library(ctx.paths)
+    cfg = ctx.project.dir / config.PROJECT_CONFIG_NAME
+    if not cfg.exists():
+        cfg.write_text(config.PROJECT_CONFIG_TEMPLATE, encoding="utf-8")
+        print(f"Créé : {cfg}")
+    print(f"{'Créé' if created else 'Déjà présent'} : {ctx.paths.root}")
+    _kicad_reminder(ctx.paths)
+    return 0
+
+
+def cmd_config(args) -> int:
+    action, use_global = args.action, args.use_global
+    if action in ("get", "set", "unset") and not args.key:
+        raise CliError(f"'config {action}' demande un nom de clé")
+    if action == "set" and args.value is None:
+        raise CliError("'config set' demande une valeur : lcsc2kicad config set <clé> <valeur>")
+
+    gconf = config.load_global()
+    if use_global:
+        path, project_dir = config.global_config_path(), None
+    else:
+        ctx = _prepare(args, write=action in ("set", "unset"), quiet=action in ("get", "path"))
+        path, project_dir = ctx.project.dir / config.PROJECT_CONFIG_NAME, ctx.project.dir
+
+    if action == "path":
+        print(path)
+    elif action == "list":
+        rows = config.describe(project_dir, gconf)
+        w = max(len(r[0]) for r in rows)
+        for key, value, origin in rows:
+            shown = config.fmt_value(value) or "(non défini)"
+            print(f"{key:<{w}} = {shown:<14} [{origin}]")
+        print(f"\nFichier : {path}{'' if path.exists() else ' (inexistant)'}")
+    elif action == "get":
+        config.key_type(args.key, use_global)
+        value = next((v for k, v, _ in config.describe(project_dir, gconf) if k == args.key), None)
+        if value is None and use_global:
+            value = gconf.get(args.key)
+        print("" if value is None else config.fmt_value(value).strip('"') if isinstance(value, str)
+              else config.fmt_value(value))
+    elif action == "set":
+        value = config.parse_value(args.key, args.value, use_global)
+        config.edit_file(path, args.key, value)
+        print(f"{args.key} = {config.fmt_value(value)}   ({path})")
+    elif action == "unset":
+        config.key_type(args.key, use_global)
+        if config.edit_file(path, args.key, None):
+            print(f"{args.key} supprimé de {path}")
+        else:
+            print(f"{args.key} n'était pas défini dans {path}")
+    return 0
+
+
+# ------------------------------------------------------------------------ parser
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--project", metavar="CHEMIN",
+                        help="dossier du projet ou fichier .kicad_pro")
+    common.add_argument("-y", "--yes", action="store_true",
+                        help="ne pas demander de confirmation")
+    common.add_argument("-v", "--verbose", action="store_true",
+                        help="afficher la sortie d'easyeda2kicad")
+
+    parser = argparse.ArgumentParser(
+        prog="lcsc2kicad",
+        description="Importe des composants LCSC/EasyEDA dans la librairie KiCad du projet.",
+        epilog="Sans sous-commande, « add » est utilisé : lcsc2kicad C12345",
+    )
+    parser.add_argument("--version", action="version", version=f"lcsc2kicad {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="{add,list,remove,init,config}")
+
+    p = sub.add_parser("add", parents=[common], help="importer un ou plusieurs composants")
+    p.add_argument("refs", nargs="*", metavar="LCSC", help="références LCSC (C12345 …)")
+    p.add_argument("--from-file", metavar="FICHIER", help="fichier : une référence par ligne")
+    p.add_argument("--no-symbol", action="store_true", help="ne pas importer le symbole")
+    p.add_argument("--no-footprint", action="store_true", help="ne pas importer l'empreinte")
+    p.add_argument("--no-3d", action="store_true", help="ne pas importer le modèle 3D")
+    p.add_argument("--full", action="store_true",
+                   help="tout importer, en ignorant les no_* de la config")
+    p.add_argument("--force", action="store_true", help="écraser les éléments déjà présents")
+    p.set_defaults(func=cmd_add)
+
+    p = sub.add_parser("list", parents=[common], help="lister les composants de la librairie")
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("remove", parents=[common], help="supprimer un composant")
+    p.add_argument("refs", nargs="*", metavar="LCSC_OU_NOM")
+    p.set_defaults(func=cmd_remove)
+
+    p = sub.add_parser("init", parents=[common], help="préparer le projet (facultatif)")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("config", parents=[common],
+                       help="afficher / modifier la configuration (list, get, set, unset, path)")
+    p.add_argument("action", choices=["list", "get", "set", "unset", "path"])
+    p.add_argument("key", nargs="?", help="nom du réglage")
+    p.add_argument("value", nargs="?", help="nouvelle valeur (pour set)")
+    p.add_argument("-g", "--global", dest="use_global", action="store_true",
+                   help="agir sur la config globale plutôt que sur celle du projet")
+    p.set_defaults(func=cmd_config)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    if not argv:
+        parser.print_help()
+        return 0
+    if argv[0] not in COMMANDS and argv[0] not in ("-h", "--help", "--version"):
+        argv.insert(0, "add")
+    # argparse gère mal une option placée entre deux positionnels facultatifs
+    # (config set --global clé valeur) : on extrait -g/--global nous-mêmes.
+    global_flag = argv[0] == "config" and any(a in ("-g", "--global") for a in argv)
+    if global_flag:
+        argv = [a for a in argv if a not in ("-g", "--global")]
+    args = parser.parse_args(argv)
+    if global_flag:
+        args.use_global = True
+    try:
+        return args.func(args)
+    except Lcsc2KicadError as exc:
+        print(f"Erreur : {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("\nInterrompu.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())