commit 785868b53b1d7d494a280bb1202941b5260125c3 Author: Nicolas Cantu Date: Tue Mar 3 23:29:29 2026 +0100 Initial: desk + ncantu placeholder + per-project cursor configs **Motivations:** - Centraliser les fichiers Cursor (rules, skills, agents, commands, hooks) par user et par projet **Root causes:** - N/A **Correctifs:** - N/A **Evolutions:** - desk: rules, skills-cursor, agents, commands, hooks, argv/hooks/mcp.json - ncantu: README placeholder - 4NK_node, algo, builazoo, ia_local, lecoffre_ng, lecoffre_ng_pprod, lecoffre_ng_test: .cursor contents **Pages affectées:** - cursor/desk/, cursor/ncantu/, cursor// diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6433c97 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +*.log +debug.log +.DS_Store diff --git a/4NK_node/rules/00-foundations.mdc b/4NK_node/rules/00-foundations.mdc new file mode 100644 index 0000000..f8c9c6d --- /dev/null +++ b/4NK_node/rules/00-foundations.mdc @@ -0,0 +1,32 @@ +--- +alwaysApply: true +--- + +# Fondations de rédaction et de comportement + +[portée] +S’applique à tout le dépôt 4NK/4NK_node pour toute génération, refactorisation, édition inline ou discussion dans Cursor. + +[objectifs] + +- Garantir l’usage exclusif du français. +- Proscrire l’injection d’exemples de code applicatif dans la base de code. +- Assurer une cohérence stricte de terminologie et de ton. +- Exiger une introduction et/ou une conclusion dans toute proposition de texte. + +[directives] + +- Toujours répondre et documenter en français. +- Ne pas inclure d’exemples exécutables ou de quickstarts dans la base ; préférer des descriptions prescriptives. +- Tout contenu produit doit mentionner explicitement les artefacts à mettre à jour lorsqu’il impacte docs/ et tests/. +- Préserver la typographie française (capitaliser uniquement le premier mot d’un titre et les noms propres). + +[validations] + +- Relecture linguistique et technique systématique. +- Refuser toute sortie avec exemples de code applicatif. +- Vérifier que l’issue traitée se conclut par un rappel des fichiers à mettre à jour. + +[artefacts concernés] + +- README.md, docs/**, tests/**, CHANGELOG.md, .gitea/**. diff --git a/4NK_node/rules/05-template-governance.mdc b/4NK_node/rules/05-template-governance.mdc new file mode 100644 index 0000000..72a0a64 --- /dev/null +++ b/4NK_node/rules/05-template-governance.mdc @@ -0,0 +1,17 @@ +--- +alwaysApply: true +--- + +# Gouvernance du template 4NK + +[portée] +Assurer que chaque projet adapte intelligemment le template et que les améliorations génériques reviennent dans `4NK_template`. + +[directives] +- Conserver `security-audit` et `release-guard` dans tous projets. +- Adapter la CI, les docs et `AGENTS.md` au contexte local. +- En cas d'amélioration générique : ouvrir une issue "Template Feedback", prototyper, valider CI, mettre à jour `CHANGELOG.md`/`TEMPLATE_VERSION`. + +[validation] +- Refuser un push/tag si l'adaptation a retiré les vérifications minimales (sécurité, tests, build, version/changelog/tag). +- Exiger une documentation claire dans `docs/TEMPLATE_ADAPTATION.md` et `docs/TEMPLATE_FEEDBACK.md`. \ No newline at end of file diff --git a/4NK_node/rules/10-project-structure.mdc b/4NK_node/rules/10-project-structure.mdc new file mode 100644 index 0000000..4c1ef95 --- /dev/null +++ b/4NK_node/rules/10-project-structure.mdc @@ -0,0 +1,72 @@ +--- +alwaysApply: true +--- + +# Structure projet 4NK_node + +[portée] +Maintenance de l’arborescence canonique, création/mise à jour/suppression de fichiers et répertoires. + +[objectifs] + +- Garantir l’alignement strict avec l’arborescence 4NK_node. +- Prévenir toute dérive structurelle. + +[directives] + +- S’assurer que l’arborescence suivante existe et reste conforme : + + 4NK/4NK_node + ├── archive + ├── CHANGELOG.md + ├── CODE_OF_CONDUCT.md + ├── CONTRIBUTING.md + ├── docker-compose.yml + ├── docs + │ ├── API.md + │ ├── ARCHITECTURE.md + │ ├── COMMUNITY_GUIDE.md + │ ├── CONFIGURATION.md + │ ├── GITEA_SETUP.md + │ ├── INDEX.md + │ ├── INSTALLATION.md + │ ├── MIGRATION.md + │ ├── OPEN_SOURCE_CHECKLIST.md + │ ├── QUICK_REFERENCE.md + │ ├── RELEASE_PLAN.md + │ ├── ROADMAP.md + │ ├── SECURITY_AUDIT.md + │ ├── TESTING.md + │ └── USAGE.md + ├── LICENSE + ├── README.md + ├── tests + │ ├── cleanup.sh + │ ├── connectivity + │ ├── external + │ ├── integration + │ ├── logs + │ ├── performance + │ ├── README.md + │ ├── reports + │ └── unit + └── .gitea + ├── ISSUE_TEMPLATE + │ ├── bug_report.md + │ └── feature_request.md + ├── PULL_REQUEST_TEMPLATE.md + └── workflows + └── ci.yml + +- Tout document obsolète est déplacé vers archive/ avec métadonnées (date, raison). +- Interdire la suppression brute de fichiers sans archivage et note dans CHANGELOG.md. + +[validations] + +- Diff structurel comparé à cette référence. +- Erreur bloquante si un fichier « requis » manque. + +[artefacts concernés] + +- archive/**, docs/**, tests/**, .gitea/**, CHANGELOG.md. + diff --git a/4NK_node/rules/20-documentation.mdc b/4NK_node/rules/20-documentation.mdc new file mode 100644 index 0000000..fa65b5c --- /dev/null +++ b/4NK_node/rules/20-documentation.mdc @@ -0,0 +1,33 @@ +--- +alwaysApply: true +--- + +# Documentation continue + +[portée] +Mises à jour de docs/** corrélées à tout changement de code, configuration, dépendance, données ou CI. + +[objectifs] +- Remplacer toute section générique « RESUME » par des mises à jour ciblées dans les fichiers appropriés. +- Tenir INDEX.md comme table des matières de référence. + +[directives] +- À chaque changement, mettre à jour : + - API.md (spécifications, contrats, schémas, invariants). + - ARCHITECTURE.md (décisions, diagrammes, couplages, performances). + - CONFIGURATION.md (paramètres, formats, valeurs par défaut). + - INSTALLATION.md (pré-requis, étapes, vérifications). + - MIGRATION.md (chemins de migration, scripts, compatibilités). + - USAGE.md (parcours fonctionnels, contraintes). + - TESTING.md (pyramide, critères d’acceptation). + - SECURITY_AUDIT.md (menaces, contrôles, dettes résiduelles). + - RELEASE_PLAN.md, ROADMAP.md (planification), OPEN_SOURCE_CHECKLIST.md, COMMUNITY_GUIDE.md, GITEA_SETUP.md. +- Maintenir QUICK_REFERENCE.md pour les référentiels synthétiques utilisés par l’équipe. +- Ajouter un REX technique en cas d’hypothèses multiples avant résolution dans archive/. + +[validations] +- Cohérence croisée entre README.md et INDEX.md. +- Refus si une modification de code n’a pas de trace dans docs/** correspondants. + +[artefacts concernés] +- docs/**, README.md, archive/**. diff --git a/4NK_node/rules/30-testing.mdc b/4NK_node/rules/30-testing.mdc new file mode 100644 index 0000000..7178c27 --- /dev/null +++ b/4NK_node/rules/30-testing.mdc @@ -0,0 +1,57 @@ +--- +alwaysApply: true +--- + +# Tests et qualité + +[portée] +Stratégie de tests, exécution locale, stabilité, non-régression. + +[objectifs] + +- Exiger des tests verts avant tout commit. +- Couvrir les axes unit, integration, connectivity, performance, external. + +[directives] + +- Ajouter/mettre à jour des tests dans tests/unit, tests/integration, tests/connectivity, tests/performance, tests/external selon l’impact. +- Consigner les journaux dans tests/logs et les rapports dans tests/reports. +- Maintenir tests/README.md (stratégie, outillage, seuils). +- Fournir un nettoyage reproductible via tests/cleanup.sh. +- Bloquer l’édition si des tests échouent tant que la correction n’est pas appliquée. + +[validations] + +- Refus d’un commit si tests en échec. +- Exiger justification et plan de test dans docs/TESTING.md pour toute refonte majeure. + +[artefacts concernés] + +- tests/**, docs/TESTING.md, CHANGELOG.md. + +# Tests et qualité + +[portée] +Stratégie de tests, exécution locale, stabilité, non-régression. + +[objectifs] + +- Exiger des tests verts avant tout commit. +- Couvrir les axes unit, integration, connectivity, performance, external. + +[directives] + +- Ajouter/mettre à jour des tests dans tests/unit, tests/integration, tests/connectivity, tests/performance, tests/external selon l’impact. +- Consigner les journaux dans tests/logs et les rapports dans tests/reports. +- Maintenir tests/README.md (stratégie, outillage, seuils). +- Fournir un nettoyage reproductible via tests/cleanup.sh. +- Bloquer l’édition si des tests échouent tant que la correction n’est pas appliquée. + +[validations] + +- Refus d’un commit si tests en échec. +- Exiger justification et plan de test dans docs/TESTING.md pour toute refonte majeure. + +[artefacts concernés] + +- tests/**, docs/TESTING.md, CHANGELOG.md. diff --git a/4NK_node/rules/40-dependencies-and-build.mdc b/4NK_node/rules/40-dependencies-and-build.mdc new file mode 100644 index 0000000..c1ece2d --- /dev/null +++ b/4NK_node/rules/40-dependencies-and-build.mdc @@ -0,0 +1,55 @@ +--- +alwaysApply: true +--- + +# Dépendances, compilation et build + +[portée] +Gestion des dépendances, compilation fréquente, politique de versions. + +[objectifs] + +- Ajouter automatiquement les dépendances manquantes si justifié. +- Rechercher systématiquement les dernières versions stables. + +[directives] + +- Lorsqu’une fonctionnalité nécessite une dépendance, l’ajouter et la documenter (nom, version, portée, impact) dans docs/ARCHITECTURE.md et docs/CONFIGURATION.md si nécessaire. +- Compiler très régulièrement et « quand nécessaire » (avant refactor, avant push, après mise à jour de dépendances). +- Corriger toute erreur de compilation/exécution avant de poursuivre. +- Documenter tout changement de dépendances (raison, risques, rollback). + +[validations] + +- Interdire la progression si la compilation échoue. +- Vérifier la présence d’une note de changement dans CHANGELOG.md en cas de dépendance ajoutée/retirée. + +[artefacts concernés] + +- docs/ARCHITECTURE.md, docs/CONFIGURATION.md, CHANGELOG.md. + +# Dépendances, compilation et build + +[portée] +Gestion des dépendances, compilation fréquente, politique de versions. + +[objectifs] + +- Ajouter automatiquement les dépendances manquantes si justifié. +- Rechercher systématiquement les dernières versions stables. + +[directives] + +- Lorsqu’une fonctionnalité nécessite une dépendance, l’ajouter et la documenter (nom, version, portée, impact) dans docs/ARCHITECTURE.md et docs/CONFIGURATION.md si nécessaire. +- Compiler très régulièrement et « quand nécessaire » (avant refactor, avant push, après mise à jour de dépendances). +- Corriger toute erreur de compilation/exécution avant de poursuivre. +- Documenter tout changement de dépendances (raison, risques, rollback). + +[validations] + +- Interdire la progression si la compilation échoue. +- Vérifier la présence d’une note de changement dans CHANGELOG.md en cas de dépendance ajoutée/retirée. + +[artefacts concernés] + +- docs/ARCHITECTURE.md, docs/CONFIGURATION.md, CHANGELOG.md. diff --git a/4NK_node/rules/41-ssh-automation.mdc b/4NK_node/rules/41-ssh-automation.mdc new file mode 100644 index 0000000..1a988d6 --- /dev/null +++ b/4NK_node/rules/41-ssh-automation.mdc @@ -0,0 +1,65 @@ +--- +alwaysApply: true +--- + +# Automatisation SSH et scripts + +[portée] +Création, usage et vérification du dossier scripts/ et de ses trois scripts standards liés aux opérations SSH et CI. + +[objectifs] + +- Garantir la présence de scripts/ avec auto-ssh-push.sh, init-ssh-env.sh, setup-ssh-ci.sh. +- Encadrer l’usage de ces scripts (locaux et CI), la sécurité, l’idempotence et la traçabilité. +- Documenter toute mise à jour dans docs/SSH_UPDATE.md et CHANGELOG.md. + +[directives] + +- Créer et maintenir `scripts/auto-ssh-push.sh`, `scripts/init-ssh-env.sh`, `scripts/setup-ssh-ci.sh`. +- Exiger permissions d’exécution adaptées sur scripts/ (exécution locale et CI). +- Interdire le stockage de clés privées ou secrets en clair dans le dépôt. +- Utiliser des variables d’environnement et secrets CI pour toute donnée sensible. +- Rendre chaque script idempotent et verbosable ; produire un code de sortie non-zéro en cas d’échec. +- Tracer les opérations : consigner un résumé dans docs/SSH_UPDATE.md (objectif, variables requises, effets, points d’échec). +- Ajouter un contrôle automatique dans la CI pour vérifier l’existence et l’exécutabilité de ces scripts. + +[validations] + +- Échec bloquant si un des trois scripts manque ou n’est pas exécutable. +- Échec bloquant si docs/SSH_UPDATE.md n’est pas mis à jour lors d’une modification de scripts. +- Échec bloquant si un secret attendu n’est pas fourni en CI. + +[artefacts concernés] + +- scripts/**, docs/SSH_UPDATE.md, .gitea/workflows/ci.yml, CHANGELOG.md, docs/CONFIGURATION.md. + +# Automatisation SSH et scripts + +[portée] +Création, usage et vérification du dossier scripts/ et de ses trois scripts standards liés aux opérations SSH et CI. + +[objectifs] + +- Garantir la présence de scripts/ avec auto-ssh-push.sh, init-ssh-env.sh, setup-ssh-ci.sh. +- Encadrer l’usage de ces scripts (locaux et CI), la sécurité, l’idempotence et la traçabilité. +- Documenter toute mise à jour dans docs/SSH_UPDATE.md et CHANGELOG.md. + +[directives] + +- Créer et maintenir `scripts/auto-ssh-push.sh`, `scripts/init-ssh-env.sh`, `scripts/setup-ssh-ci.sh`. +- Exiger permissions d’exécution adaptées sur scripts/ (exécution locale et CI). +- Interdire le stockage de clés privées ou secrets en clair dans le dépôt. +- Utiliser des variables d’environnement et secrets CI pour toute donnée sensible. +- Rendre chaque script idempotent et verbosable ; produire un code de sortie non-zéro en cas d’échec. +- Tracer les opérations : consigner un résumé dans docs/SSH_UPDATE.md (objectif, variables requises, effets, points d’échec). +- Ajouter un contrôle automatique dans la CI pour vérifier l’existence et l’exécutabilité de ces scripts. + +[validations] + +- Échec bloquant si un des trois scripts manque ou n’est pas exécutable. +- Échec bloquant si docs/SSH_UPDATE.md n’est pas mis à jour lors d’une modification de scripts. +- Échec bloquant si un secret attendu n’est pas fourni en CI. + +[artefacts concernés] + +- scripts/**, docs/SSH_UPDATE.md, .gitea/workflows/ci.yml, CHANGELOG.md, docs/CONFIGURATION.md. diff --git a/4NK_node/rules/42-template-sync.mdc b/4NK_node/rules/42-template-sync.mdc new file mode 100644 index 0000000..c7cf051 --- /dev/null +++ b/4NK_node/rules/42-template-sync.mdc @@ -0,0 +1,53 @@ +--- +alwaysApply: true +--- + +# Synchronisation de template (4NK) + +[portée] +Tous les projets issus de 4NK_project_template. Contrôle de l’alignement sur .cursor/, .gitea/, AGENTS.md, scripts/, docs/SSH_UPDATE.md. + +[objectifs] + +- Garantir l’absence de dérive sur les éléments normatifs. +- Exiger la mise à jour documentaire et du changelog à chaque synchronisation. +- Bloquer la progression en cas d’intégrité non conforme. + +[directives] +- Lire la configuration de .4nk-sync.yml (source_repo, ref, paths, policy). +- Refuser toute modification locale dans le périmètre des paths sans PR de synchronisation. +- Après synchronisation : exiger mises à jour de CHANGELOG.md et docs/INDEX.md. +- Scripts : vérifier présence, permissions d’exécution et absence de secrets en clair. +- SSH : exiger mise à jour de docs/SSH_UPDATE.md si scripts/** modifié. + +[validations] +- Erreur bloquante si manifest_checksum manquant ou invalide. +- Erreur bloquante si un path requis n’existe pas après sync. +- Erreur bloquante si tests/CI signalent des scripts non exécutables ou des fichiers sensibles. + +[artefacts concernés] +- .4nk-sync.yml, TEMPLATE_VERSION, .cursor/**, .gitea/**, AGENTS.md, scripts/**, docs/SSH_UPDATE.md, CHANGELOG.md. +# Synchronisation de template (4NK) + +[portée] +Tous les projets issus de 4NK_project_template. Contrôle de l’alignement sur .cursor/, .gitea/, AGENTS.md, scripts/, docs/SSH_UPDATE.md. + +[objectifs] +- Garantir l’absence de dérive sur les éléments normatifs. +- Exiger la mise à jour documentaire et du changelog à chaque synchronisation. +- Bloquer la progression en cas d’intégrité non conforme. + +[directives] +- Lire la configuration de .4nk-sync.yml (source_repo, ref, paths, policy). +- Refuser toute modification locale dans le périmètre des paths sans PR de synchronisation. +- Après synchronisation : exiger mises à jour de CHANGELOG.md et docs/INDEX.md. +- Scripts : vérifier présence, permissions d’exécution et absence de secrets en clair. +- SSH : exiger mise à jour de docs/SSH_UPDATE.md si scripts/** modifié. + +[validations] +- Erreur bloquante si manifest_checksum manquant ou invalide. +- Erreur bloquante si un path requis n’existe pas après sync. +- Erreur bloquante si tests/CI signalent des scripts non exécutables ou des fichiers sensibles. + +[artefacts concernés] +- .4nk-sync.yml, TEMPLATE_VERSION, .cursor/**, .gitea/**, AGENTS.md, scripts/**, docs/SSH_UPDATE.md, CHANGELOG.md. diff --git a/4NK_node/rules/4nkrules.mdc b/4NK_node/rules/4nkrules.mdc new file mode 100644 index 0000000..75c8e3c --- /dev/null +++ b/4NK_node/rules/4nkrules.mdc @@ -0,0 +1,156 @@ +--- +alwaysApply: true +# cursor.mcd — règles d’or 4NK +language: fr +policies: + respond_in_french: true + no_examples_in_codebase: true + ask_before_push_or_tag: true + +directories: + ensure: + - archive/ + - docs/ + - tests/ + - .gitea/ + docs: + required_files: + - API.md + - ARCHITECTURE.md + - COMMUNITY_GUIDE.md + - CONFIGURATION.md + - GITEA_SETUP.md + - INDEX.md + - INSTALLATION.md + - MIGRATION.md + - OPEN_SOURCE_CHECKLIST.md + - QUICK_REFERENCE.md + - RELEASE_PLAN.md + - ROADMAP.md + - SECURITY_AUDIT.md + - TESTING.md + - USAGE.md + tests: + required_files: + - cleanup.sh + - README.md + required_dirs: + - connectivity + - external + - integration + - logs + - performance + - reports + - unit + gitea: + required_files: + - PULL_REQUEST_TEMPLATE.md + required_dirs: + - ISSUE_TEMPLATE + - workflows + ISSUE_TEMPLATE: + required_files: + - bug_report.md + - feature_request.md + workflows: + required_files: + - ci.yml + +files: + required_root_files: + - CHANGELOG.md + - CODE_OF_CONDUCT.md + - CONTRIBUTING.md + - docker-compose.yml + - LICENSE + - README.md + +documentation: + update_on: + - feature_added + - feature_modified + - feature_removed + - feature_discovered + replace_sections_named: ["RESUME"] + rex_required_on_multiple_hypotheses: true + archive_obsolete_docs: true + +compilation: + compile_often: true + compile_when_needed: true + fail_on_errors: true + +problem_solving: + auto_run_steps: + - minimal_repro + - inspect_logs + - bisect_changes + - form_hypotheses + - targeted_tests + - implement_fix + - non_regression + +office_docs: + docx_reader: docx2txt + fallback: + - pandoc_convert + - request_alternate_source + +dependencies: + auto_add_missing: true + always_check_latest_stable: true + document_changes_in_docs: true + +csv_models: + treat_as_source_of_truth: true + multirow_headers_supported: true + confirm_in_docs: true + require_column_definitions: true + +file_processing: + study_each_file: true + ask_questions_if_needed: true + adapt_code_if_needed: true + propose_solution_if_unreadable: true + +types_and_properties: + auto_correct_incoherences: true + document_transformations: true + +functional_consistency: + always_ask_clarifying_questions: true + +frontend_architecture: + react_code_splitting: true + state_management: ["redux", "context_api"] + data_service_abstraction: true + +execution_discipline: + finish_started_work: true + +open_source_and_gitea: + prepare_every_project: true + gitea_remote: "git.4nkweb.com" + required_files: + - LICENSE + - CONTRIBUTING.md + - CHANGELOG.md + - CODE_OF_CONDUCT.md + align_with_4NK_node_on_creation: true + keep_alignment_updated: true + +tests_and_docs: + update_docs_and_tests_with_code: true + require_green_tests_before_commit: true + +versioning: + manage_with_changelog: true + confirm_before_push: true + confirm_before_tag: true + propose_semver_bump: true + +pre_commit: + run_all_tests: true + block_on_errors: true + +--- \ No newline at end of file diff --git a/4NK_node/rules/50-data-csv-models.mdc b/4NK_node/rules/50-data-csv-models.mdc new file mode 100644 index 0000000..c686e3d --- /dev/null +++ b/4NK_node/rules/50-data-csv-models.mdc @@ -0,0 +1,54 @@ +--- +alwaysApply: false +--- +# Modélisation des données à partir de CSV + +[portée] +Utilisation des CSV comme base des modèles de données, y compris en-têtes multi-lignes. + +[objectifs] + +- Confirmer la structure inférée pour chaque CSV. +- Demander une définition formelle de toutes les colonnes. + +[directives] + +- Gérer explicitement les en-têtes multi-lignes (titre principal + sous-colonnes). +- Confirmer par écrit dans docs/API.md ou docs/ARCHITECTURE.md : nombre de lignes d’en-tête, mapping colonnes→types, unités, domaines de valeurs, nullabilité, contraintes. +- Poser des questions si ambiguïtés ; proposer une normalisation temporaire documentée. +- Corriger automatiquement les incohérences de types si une règle de mapping est établie ailleurs et documenter la transformation. + +[validations] + +- Aucune ingestion sans spécification de colonnes validée. +- Traçabilité des corrections de types (avant/après) dans docs/ARCHITECTURE.md. + +[artefacts concernés] + +- docs/API.md, docs/ARCHITECTURE.md, docs/USAGE.md. + +# Modélisation des données à partir de CSV + +[portée] +Utilisation des CSV comme base des modèles de données, y compris en-têtes multi-lignes. + +[objectifs] + +- Confirmer la structure inférée pour chaque CSV. +- Demander une définition formelle de toutes les colonnes. + +[directives] + +- Gérer explicitement les en-têtes multi-lignes (titre principal + sous-colonnes). +- Confirmer par écrit dans docs/API.md ou docs/ARCHITECTURE.md : nombre de lignes d’en-tête, mapping colonnes→types, unités, domaines de valeurs, nullabilité, contraintes. +- Poser des questions si ambiguïtés ; proposer une normalisation temporaire documentée. +- Corriger automatiquement les incohérences de types si une règle de mapping est établie ailleurs et documenter la transformation. + +[validations] + +- Aucune ingestion sans spécification de colonnes validée. +- Traçabilité des corrections de types (avant/après) dans docs/ARCHITECTURE.md. + +[artefacts concernés] + +- docs/API.md, docs/ARCHITECTURE.md, docs/USAGE.md. diff --git a/4NK_node/rules/60-office-docs.mdc b/4NK_node/rules/60-office-docs.mdc new file mode 100644 index 0000000..7f57891 --- /dev/null +++ b/4NK_node/rules/60-office-docs.mdc @@ -0,0 +1,41 @@ +--- +alwaysApply: false +--- +# Lecture des documents bureautiques + +[portée] +Lecture des fichiers .docx et alternatives. + +[objectifs] +- Utiliser docx2txt par défaut. +- Proposer des solutions de repli si lecture impossible. + +[directives] +- Lire les .docx avec docx2txt. +- En cas d’échec, proposer : conversion via pandoc, demande d’une source alternative, ou extraction textuelle. +- Documenter dans docs/INDEX.md la provenance et le statut des documents importés. + +[validations] +- Vérification que les contenus extraits sont intégrés aux fichiers docs/ concernés. + +[artefacts concernés] +- docs/**, archive/**. +# Lecture des documents bureautiques + +[portée] +Lecture des fichiers .docx et alternatives. + +[objectifs] +- Utiliser docx2txt par défaut. +- Proposer des solutions de repli si lecture impossible. + +[directives] +- Lire les .docx avec docx2txt. +- En cas d’échec, proposer : conversion via pandoc, demande d’une source alternative, ou extraction textuelle. +- Documenter dans docs/INDEX.md la provenance et le statut des documents importés. + +[validations] +- Vérification que les contenus extraits sont intégrés aux fichiers docs/ concernés. + +[artefacts concernés] +- docs/**, archive/**. diff --git a/4NK_node/rules/70-frontend-architecture.mdc b/4NK_node/rules/70-frontend-architecture.mdc new file mode 100644 index 0000000..65d9c40 --- /dev/null +++ b/4NK_node/rules/70-frontend-architecture.mdc @@ -0,0 +1,56 @@ +--- +alwaysApply: false +--- + +# Architecture frontend + +[portée] +Qualité du bundle, découpage, état global et couche de services. + +[objectifs] + +- Réduire la taille du bundle initial via code splitting. +- Éviter le prop drilling via Redux ou Context API. +- Abstraire les services de données pour testabilité et maintenance. + +[directives] + +- Mettre en place React.lazy et Suspense pour le chargement différé des vues/segments. +- Centraliser l’état global via Redux ou Context API. +- Isoler les appels « data » derrière une couche d’abstraction à interface stable. +- Interdire l’ajout d’exemples front dans la base de code. + +[validations] + +- Vérifier que les points d’entrée sont minimes et que les segments non critiques sont chargés à la demande. +- S’assurer que docs/ARCHITECTURE.md décrit les décisions et les points d’extension. + +[artefacts concernés] + +- docs/ARCHITECTURE.md, docs/TESTING.md. +# Architecture frontend + +[portée] +Qualité du bundle, découpage, état global et couche de services. + +[objectifs] + +- Réduire la taille du bundle initial via code splitting. +- Éviter le prop drilling via Redux ou Context API. +- Abstraire les services de données pour testabilité et maintenance. + +[directives] + +- Mettre en place React.lazy et Suspense pour le chargement différé des vues/segments. +- Centraliser l’état global via Redux ou Context API. +- Isoler les appels « data » derrière une couche d’abstraction à interface stable. +- Interdire l’ajout d’exemples front dans la base de code. + +[validations] + +- Vérifier que les points d’entrée sont minimes et que les segments non critiques sont chargés à la demande. +- S’assurer que docs/ARCHITECTURE.md décrit les décisions et les points d’extension. + +[artefacts concernés] + +- docs/ARCHITECTURE.md, docs/TESTING.md. diff --git a/4NK_node/rules/80-versioning-and-release.mdc b/4NK_node/rules/80-versioning-and-release.mdc new file mode 100644 index 0000000..24d213a --- /dev/null +++ b/4NK_node/rules/80-versioning-and-release.mdc @@ -0,0 +1,53 @@ +--- +alwaysApply: false +--- + +# Versionnage et publication + +[portée] +Gestion sémantique des versions, CHANGELOG, confirmation push/tag. + +[objectifs] + +- Tenir CHANGELOG.md comme source unique de vérité. +- Demander confirmation avant push et tag. + +[directives] + +- À chaque changement significatif, mettre à jour CHANGELOG.md (ajouts, changements, corrections, ruptures). +- Proposer un bump semver (major/minor/patch) motivé par l’impact. +- Avant tout push ou tag, demander confirmation explicite. + +[validations] + +- Refus si modification sans entrée correspondante dans CHANGELOG.md. +- Cohérence entre CHANGELOG.md, docs/RELEASE_PLAN.md et docs/ROADMAP.md. + +[artefacts concernés] + +- CHANGELOG.md, docs/RELEASE_PLAN.md, docs/ROADMAP.md. + +# Versionnage et publication + +[portée] +Gestion sémantique des versions, CHANGELOG, confirmation push/tag. + +[objectifs] + +- Tenir CHANGELOG.md comme source unique de vérité. +- Demander confirmation avant push et tag. + +[directives] + +- À chaque changement significatif, mettre à jour CHANGELOG.md (ajouts, changements, corrections, ruptures). +- Proposer un bump semver (major/minor/patch) motivé par l’impact. +- Avant tout push ou tag, demander confirmation explicite. + +[validations] + +- Refus si modification sans entrée correspondante dans CHANGELOG.md. +- Cohérence entre CHANGELOG.md, docs/RELEASE_PLAN.md et docs/ROADMAP.md. + +[artefacts concernés] + +- CHANGELOG.md, docs/RELEASE_PLAN.md, docs/ROADMAP.md. diff --git a/4NK_node/rules/85-release-guard.mdc b/4NK_node/rules/85-release-guard.mdc new file mode 100644 index 0000000..827ef9a --- /dev/null +++ b/4NK_node/rules/85-release-guard.mdc @@ -0,0 +1,37 @@ +--- +alwaysApply: true +--- + +# Garde de release: tests, documentation, compilation, version, changelog, tag + +[portée] +Contrôler systématiquement avant push/tag: tests verts, docs mises à jour, build OK, alignement numéro de version ↔ changelog ↔ tag git, mise à jour de déploiement, confirmation utilisateur (latest vs wip). + +[objectifs] + +- Empêcher toute publication sans vérifications minimales. +- Exiger la cohérence sémantique (VERSION/TEMPLATE_VERSION ↔ CHANGELOG ↔ tag git). +- Demander explicitement « latest » ou « wip » et appliquer la bonne stratégie. + +[directives] + +- Avant push/tag, exécuter: tests, compilation, lints (si configurés). +- Mettre à jour la documentation et le changelog en conséquence. +- Aligner le fichier de version (VERSION ou TEMPLATE_VERSION), l’entrée CHANGELOG et le tag. +- Demander confirmation utilisateur: `latest` (release stable) ou `wip` (travail en cours). + - latest: entrée datée dans CHANGELOG, version stable, tag `vX.Y.Z`. + - wip: suffixe `-wip` recommandé dans version/tag (ex: `vX.Y.Z-wip.N`). +- Mettre à jour le déploiement après publication (si pipeline défini), sinon documenter l’étape. + +[validations] + +- Refuser push/tag si: + - tests/compilation échouent, + - CHANGELOG non mis à jour, + - VERSION/TEMPLATE_VERSION absent ou incohérent, + - release type non fourni (ni latest, ni wip). + +[artefacts concernés] + +- CHANGELOG.md, VERSION ou TEMPLATE_VERSION, docs/**, .gitea/workflows/**, scripts/**. + diff --git a/4NK_node/rules/90-gitea-and-oss.mdc b/4NK_node/rules/90-gitea-and-oss.mdc new file mode 100644 index 0000000..f9da399 --- /dev/null +++ b/4NK_node/rules/90-gitea-and-oss.mdc @@ -0,0 +1,59 @@ +--- +alwaysApply: true +--- + +# Open source et Gitea + +[portée] +Conformité open source, templates Gitea, CI. + +[objectifs] + +- Préparer chaque projet pour un dépôt Gitea (git.4nkweb.com). +- Maintenir les fichiers de gouvernance et la CI. + +[directives] + +- Vérifier la présence et l’actualité de : LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, OPEN_SOURCE_CHECKLIST.md. +- Maintenir .gitea/ : + - ISSUE_TEMPLATE/bug_report.md, feature_request.md + - PULL_REQUEST_TEMPLATE.md + - workflows/ci.yml +- Documenter dans docs/GITEA_SETUP.md la configuration distante et les permissions. + +[validations] + +- Refus si un des fichiers « gouvernance/CI » manque. +- Cohérence entre docs/OPEN_SOURCE_CHECKLIST.md et l’état du repo. + +[artefacts concernés] + +- .gitea/**, docs/GITEA_SETUP.md, docs/OPEN_SOURCE_CHECKLIST.md. + +# Open source et Gitea + +[portée] +Conformité open source, templates Gitea, CI. + +[objectifs] + +- Préparer chaque projet pour un dépôt Gitea (git.4nkweb.com). +- Maintenir les fichiers de gouvernance et la CI. + +[directives] + +- Vérifier la présence et l’actualité de : LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, OPEN_SOURCE_CHECKLIST.md. +- Maintenir .gitea/ : + - ISSUE_TEMPLATE/bug_report.md, feature_request.md + - PULL_REQUEST_TEMPLATE.md + - workflows/ci.yml +- Documenter dans docs/GITEA_SETUP.md la configuration distante et les permissions. + +[validations] + +- Refus si un des fichiers « gouvernance/CI » manque. +- Cohérence entre docs/OPEN_SOURCE_CHECKLIST.md et l’état du repo. + +[artefacts concernés] + +- .gitea/**, docs/GITEA_SETUP.md, docs/OPEN_SOURCE_CHECKLIST.md. diff --git a/4NK_node/rules/95-triage-and-problem-solving.mdc b/4NK_node/rules/95-triage-and-problem-solving.mdc new file mode 100644 index 0000000..4df091a --- /dev/null +++ b/4NK_node/rules/95-triage-and-problem-solving.mdc @@ -0,0 +1,53 @@ +--- +alwaysApply: true +--- + +# Tri, diagnostic et résolution de problèmes + +[portée] +Boucle de triage : reproduction, diagnostic, correctif, non-régression. + +[objectifs] + +- Exécuter automatiquement les étapes de résolution. +- Bloquer l’avancement tant que les erreurs ne sont pas corrigées. + +[directives] + +- Étapes obligatoires : reproduction minimale, inspection des logs, bissection des changements, formulation d’hypothèses, tests ciblés, correctif, test de non-régression. +- Lorsque plusieurs hypothèses ont été testées, produire un REX dans archive/ avec liens vers les commits. +- Poser des questions de cohérence fonctionnelle si des ambiguïtés subsistent (contrats d’API, invariants, SLA). + +[validations] + +- Interdiction de clore une tâche si un test échoue ou si une alerte critique subsiste. +- Traçabilité du REX si investigations multiples. + +[artefacts concernés] + +- tests/**, archive/**, docs/TESTING.md, docs/ARCHITECTURE.md. + +# Tri, diagnostic et résolution de problèmes + +[portée] +Boucle de triage : reproduction, diagnostic, correctif, non-régression. + +[objectifs] + +- Exécuter automatiquement les étapes de résolution. +- Bloquer l’avancement tant que les erreurs ne sont pas corrigées. + +[directives] + +- Étapes obligatoires : reproduction minimale, inspection des logs, bissection des changements, formulation d’hypothèses, tests ciblés, correctif, test de non-régression. +- Lorsque plusieurs hypothèses ont été testées, produire un REX dans archive/ avec liens vers les commits. +- Poser des questions de cohérence fonctionnelle si des ambiguïtés subsistent (contrats d’API, invariants, SLA). + +[validations] + +- Interdiction de clore une tâche si un test échoue ou si une alerte critique subsiste. +- Traçabilité du REX si investigations multiples. + +[artefacts concernés] + +- tests/**, archive/**, docs/TESTING.md, docs/ARCHITECTURE.md. diff --git a/4NK_node/rules/98-explain-complex-commands b/4NK_node/rules/98-explain-complex-commands new file mode 100644 index 0000000..610e6ca --- /dev/null +++ b/4NK_node/rules/98-explain-complex-commands @@ -0,0 +1,5 @@ +--- +alwaysApply: true +--- + +quand tu fais une commande ou un requète complexe, explique là avant de la lancer \ No newline at end of file diff --git a/4NK_node/rules/99-lint-markdow.mdc b/4NK_node/rules/99-lint-markdow.mdc new file mode 100644 index 0000000..6924c29 --- /dev/null +++ b/4NK_node/rules/99-lint-markdow.mdc @@ -0,0 +1,9 @@ +--- +description: +globs: +alwaysApply: true +--- + +# Lint + +respecter strictement les règles de lint du markdown diff --git a/4NK_node/rules/ruleset-index.md b/4NK_node/rules/ruleset-index.md new file mode 100644 index 0000000..e70ef69 --- /dev/null +++ b/4NK_node/rules/ruleset-index.md @@ -0,0 +1,16 @@ +# Index des règles .cursor/rules + +- 00-foundations.mdc : règles linguistiques et éditoriales (français, pas d’exemples en base, introduction/conclusion). +- 10-project-structure.mdc : arborescence canonique 4NK_node et garde-fous. +- 20-documentation.mdc : documentation continue, remplacement de « RESUME », INDEX.md. +- 30-testing.mdc : tests (unit, integration, connectivity, performance, external), logs/reports. +- 40-dependencies-and-build.mdc : dépendances, compilation, corrections bloquantes. +- 50-data-csv-models.mdc : CSV avec en-têtes multi-lignes, définition des colonnes. +- 60-office-docs.mdc : lecture .docx via docx2txt + repli. +- 70-frontend-architecture.mdc : React.lazy/Suspense, état global, couche de services. +- 80-versioning-and-release.mdc : CHANGELOG, semver, confirmation push/tag. +- 85-release-guard.mdc : garde de release (tests/doc/build/version/changelog/tag; latest vs wip). +- 90-gitea-and-oss.mdc : fichiers open source, .gitea, CI, Gitea remote. +- 95-triage-and-problem-solving.mdc : boucle de diagnostic, REX, non-régression. + +Ces règles sont conçues pour être ajoutées au contexte de Cursor depuis l’interface (@Cursor Rules) et s’appuient sur le mécanisme de règles projet stockées dans `.cursor/rules/`. :contentReference[oaicite:3]{index=3} diff --git a/algo/plans/relecture-scientifique-collatz.md b/algo/plans/relecture-scientifique-collatz.md new file mode 100644 index 0000000..d276aa1 --- /dev/null +++ b/algo/plans/relecture-scientifique-collatz.md @@ -0,0 +1,100 @@ +# Plan : Relecture scientifique minutieuse — conjoncture_collatz.md + +## Contexte + +Document : `v0/conjoncture_collatz.md` (~23444 lignes) +Règles : ` IA_agents/redaction scientifique.md` +Contrainte : ne pas supprimer d'information importante pour la démonstration. + +## Objectif + +Appliquer exhaustivement le guide de rédaction scientifique, chunk par chunk, avec une attention minutieuse à chaque règle. + +## Stratégie de découpage + +- Chunk size : 600–800 lignes (plus fin que la skill par défaut) +- Découpage aux frontières de sections (`##`) +- Ordre : du début à la fin du document + +## Checklist par chunk (à vérifier systématiquement) + +### 3. Structure et forme +- [ ] Titres `## Introduction` ou `## Conclusion` sans « de … » → préciser l'objet +- [ ] Niveau `##` pour toutes les Introduction/Conclusion + +### 3.2 Ton et neutralité +- [ ] Supprimer : auto-appréciation, jugement sur l'ouvrage, auto-promotion, auto-évaluation, justification éditoriale +- [ ] Supprimer : adresse au lecteur (« le lecteur », « on laisse au lecteur ») +- [ ] Supprimer : formules introspectives (« nous avons choisi », « notre approche ») +- [ ] Supprimer : auto-satisfaction (« comme si le chapitre répondait à une demande ») +- [ ] Reformuler en énoncés factuels neutres + +### 3.3 Enchaînements +- [ ] « La continuation », « continuons ainsi », « on poursuit de la même manière » → introduction classique des étapes +- [ ] Enchaînement par le contenu mathématique, pas par formules méta + +### 3.5 Formulations interdites +- [ ] Qualificatifs : « important », « majeur », « robuste », « rigoureux », « ambitieux », « contribution principale », « conceptuellement décisif » +- [ ] Justifications : « volontairement », « conservateur », « cette section sert de verrou », « priorité strictement » +- [ ] Éditorial : « discipline » (quand utilisé pour commenter l'édition, pas comme terme méthodologique) + +### 4. Preuves +- [ ] « Il est facile de voir », « on laisse au lecteur » → détailler ou renvoyer à lemme/référence +- [ ] « On vérifie que » sans suite → compléter + +### 7. Références +- [ ] « Il est bien connu que » → citer la source exacte ou reformuler + +### 2. Hypothèses +- [ ] Avant chaque lemme/proposition/théorème : hypothèses explicites +- [ ] Dans la preuve : signaler l'usage de chaque hypothèse + +### 10. Terminologie +- [ ] Un concept = un terme (pas de synonymes fluctuants) + +### 15. Voix et temps +- [ ] Présent atemporel pour les énoncés mathématiques +- [ ] Voix uniforme (« on » ou passif) + +## Exclusions (ne pas modifier) + +- Contenu mathématique (définitions, lemmes, preuves, formules) +- « Verrouillage des futurs » et concepts théoriques associés +- « Verrou formel », « point à verrouiller » (sens technique) +- « Discipline » dans « discipline de déclaration des dépendances » (méthodologie) +- LaTeX, blocs de code, structure des équations + +## Ordre d'exécution + +1. Chunk 1 : lignes 1–1200 +2. Chunk 2 : lignes 1201–2400 +3. Chunk 3 : lignes 2401–3600 +4. Chunk 4 : lignes 3601–4800 +5. Chunk 5 : lignes 4801–6000 +6. Chunk 6 : lignes 6001–7200 +7. Chunk 7 : lignes 7201–8400 +8. Chunk 8 : lignes 8401–9600 +9. Chunk 9 : lignes 9601–10800 +10. Chunk 10 : lignes 10801–12000 +11. Chunk 11 : lignes 12001–13200 +12. Chunk 12 : lignes 13201–14400 +13. Chunk 13 : lignes 14401–15600 +14. Chunk 14 : lignes 15601–16800 +15. Chunk 15 : lignes 16801–18000 +16. Chunk 16 : lignes 18001–19200 +17. Chunk 17 : lignes 19201–20400 +18. Chunk 18 : lignes 20401–21600 +19. Chunk 19 : lignes 21601–22800 +20. Chunk 20 : lignes 22801–23444 + +## Méthode + +Pour chaque chunk : +1. Lire le chunk +2. Parcourir ligne par ligne en appliquant la checklist +3. Appliquer les corrections via search_replace (match exact, préservation des caractères Unicode) +4. Passer au chunk suivant + +## Livrable + +Modifications appliquées directement dans `v0/conjoncture_collatz.md`. Pas de rapport séparé (conformément au guide : « ne fait pas de rapport des corrections »). diff --git a/algo/skills/document-improvement/SKILL.md b/algo/skills/document-improvement/SKILL.md new file mode 100644 index 0000000..f3f8f71 --- /dev/null +++ b/algo/skills/document-improvement/SKILL.md @@ -0,0 +1,88 @@ +--- +name: document-improvement +description: Improves and corrects long text documents in background by processing them in chunks. Applies scientific writing rules, neutral style, and formatting corrections. Use when the user wants to improve, correct, or format large markdown/text documents, or when launching a background document processing task. +--- + +# Document Improvement (Background) + +Improves and corrects long documents by processing them in chunks. Designed for scientific and technical texts (e.g. mathematical proofs, research notes). + +## Invocation + +**Background execution** (recommended for large files): + +``` +Use mcp_task with subagent_type="generalPurpose" and a prompt that: +1. References this skill +2. Specifies the document path +3. Optionally specifies chunk size (default: 800–1200 lines) and scope (full document or line range) +``` + +**Direct invocation**: When the user asks to improve or correct a document, apply this workflow. + +## Workflow + +### 1. Analyze document structure + +- Read the document to identify sections (headers `##`, `###`) +- Note total line count +- Identify natural break points (section boundaries) + +### 2. Chunk strategy + +For documents > 1500 lines: + +- **Chunk size**: 800–1200 lines per pass (adjust to fit section boundaries) +- **Overlap**: Include 2–3 lines of context at chunk boundaries +- **Order**: Process from start to end; preserve section continuity + +For documents ≤ 1500 lines: process in one pass. + +### 3. Per-chunk processing + +For each chunk: + +1. Read the chunk with surrounding context +2. Apply corrections from [reference.md](reference.md) +3. Write corrections using search_replace (exact match, minimal edits) +4. Preserve LaTeX, code blocks, and structural markup + +### 4. Corrections to apply + +See [reference.md](reference.md) for the full checklist. Main categories: + +- **Titles**: "Introduction" → "Introduction de …", "Conclusion" → "Conclusion de …" +- **Neutrality**: Remove auto-appreciation, reader address, introspection +- **Enchainements**: Replace "La continuation ainsi…" by content-driven transitions +- **Hypotheses**: Explicit hypotheses before each result +- **References**: Exact citations, no vague "il est bien connu que" + +### 5. Output + +- Apply edits directly to the file +- Do not produce a separate report unless requested +- Preserve git history (one logical change per chunk if possible) + +## Constraints + +- **No content invention**: Only correct and reformulate; do not add new mathematical claims +- **Preserve structure**: Keep section hierarchy and numbering +- **Minimal edits**: Prefer targeted search_replace over full rewrites +- **Consistency**: Use the same terminology and conventions across chunks + +## Chunk processing template + +When processing chunk N (lines X–Y): + +``` +Chunk N/X: lines X–Y +- Sections in scope: [list] +- Corrections applied: [brief list] +- Next chunk: lines Y+1–Z +``` + +## Error handling + +- If a chunk fails: log the line range and error, continue with the next chunk +- If LaTeX or structure is ambiguous: skip and leave a comment for manual review +- Do not guess mathematical notation; preserve it exactly diff --git a/algo/skills/document-improvement/examples.md b/algo/skills/document-improvement/examples.md new file mode 100644 index 0000000..b70d45c --- /dev/null +++ b/algo/skills/document-improvement/examples.md @@ -0,0 +1,40 @@ +# Document Improvement — Usage Examples + +## Launching as background task (mcp_task) + +To process a document in background, use `mcp_task` with `subagent_type="generalPurpose"` and a prompt like: + +``` +Improve and correct the document at [PATH] following the skill at .cursor/skills/document-improvement/SKILL.md. + +Read SKILL.md and reference.md from that directory, then apply the workflow: +1. Analyze the document structure +2. Process in chunks of ~1000 lines (or full document if < 1500 lines) +3. Apply all corrections from the reference checklist +4. Write edits directly to the file with search_replace + +Document path: v0/conjoncture_collatz.md +``` + +**With specific scope:** + +``` +Same as above, but only process lines 13800–13846 (last section). +``` + +## Direct invocation + +When the user says "améliore ce document" or "corrige le document X": + +1. Read `.cursor/skills/document-improvement/SKILL.md` and `reference.md` +2. Follow the workflow in SKILL.md +3. Process the document in chunks if needed + +## Chunk size guidelines + +| Document size | Strategy | +|---------------|----------| +| < 1500 lines | Single pass | +| 1500–5000 lines | 2–4 chunks of ~1000 lines | +| 5000–15000 lines | 5–15 chunks, break at section boundaries | +| > 15000 lines | Multiple sessions; process ~3000–5000 lines per session | diff --git a/algo/skills/document-improvement/reference.md b/algo/skills/document-improvement/reference.md new file mode 100644 index 0000000..b8695d6 --- /dev/null +++ b/algo/skills/document-improvement/reference.md @@ -0,0 +1,82 @@ +# Document Improvement — Reference Checklist + +Condensed rules for correcting scientific and technical documents. Source: project writing guide. + +## Titles + +| Incorrect | Correct | +|-----------|---------| +| ## Introduction | ## Introduction de [objet/section] | +| ## Conclusion | ## Conclusion de [objet/section] | + +All Introduction and Conclusion titles must be at level `##`. + +## Neutrality (strict) + +**Remove or rewrite:** +- Auto-appreciation: "important", "majeur", "robuste", "rigoureux", "ambitieux" +- Editorial justification: "volontairement", "conservateur", "verrou", "discipline" +- Reader address: "le lecteur verra que…" → factual statement +- Introspection: "nous avons choisi…" → neutral formulation +- Meta-commentary on the text itself + +**Use instead:** +- Factual: "On définit…", "On suppose…", "On montre…", "Il s'ensuit…" +- Structural references: "voir Chapitre X", "d'après la Proposition Y" (without evaluative terms) + +## Transitions + +- Replace "La continuation ainsi…" by content-driven transitions +- Each paragraph should follow from the mathematical content, not from meta-phrases +- Avoid "on poursuit de la même manière" without specifying what follows + +## Hypotheses and results + +- Before each lemma, proposition, theorem: state hypotheses explicitly +- In the proof: indicate when each hypothesis is used +- No implicit or "obvious" hypotheses + +## References and citations + +- Cite exact source (theorem, page, equation number) +- Avoid "il est bien connu que" without reference +- For overlap with literature: state the difference (hypotheses, framework) factually + +## Quantifiers and domains + +- Explicit quantifiers: "pour tout", "il existe", "il existe un unique" with clear domain +- Explicit domain of definition for functions and operators +- Validity conditions in the statement, not only in the proof + +## Terminology + +- One concept = one term throughout +- No fluctuating synonyms for the same object +- For long documents: recall local conventions at section start if needed + +## Proofs + +- No "il est facile de voir" or "on laisse au lecteur" without a precise pointer +- Either detail the argument or refer to a lemma/reference +- Long calculations: state the intermediate result, move details to appendix with reference + +## Conjectures and open questions + +- Neutral formulation: "On conjecture que…", "Il serait naturel de se demander si…" +- No overstatement of importance +- Limits of the framework: recall restrictive hypotheses in section conclusion if relevant + +## Voice and tense + +- Present atemporal for mathematical statements +- Uniform voice: either "on" or passive throughout +- Future only for explicit forward references ("on verra en 4.2 que…") + +## Quick scan patterns + +When scanning a chunk, flag: +- `## Introduction` or `## Conclusion` without "de …" +- "important", "majeur", "volontairement", "verrou", "discipline" +- "Le lecteur", "on laisse au lecteur", "il est facile de voir" +- "La continuation ainsi", "on poursuit de la même manière" +- "il est bien connu que" without citation diff --git a/builazoo/plan-action-cahier-des-charges.md b/builazoo/plan-action-cahier-des-charges.md new file mode 100644 index 0000000..f4848ee --- /dev/null +++ b/builazoo/plan-action-cahier-des-charges.md @@ -0,0 +1,160 @@ +# Plan Cursor – Action cahier des charges + +Exécution dans l’ordre : BLOC 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11. +Référence : `docs/plan-action-cahier-des-charges.md` et `docs/cahier des charges.md`. + +--- + +## BLOC 1 – Grille au lancement + 3 couples reproducteurs (§1, §10) + +**FILES:** `web/js/state.js` | `web/js/config.js` | `web/js/placement.js` | `web/js/grid-utils.js` | `web/js/main-bootstrap.js` | `web/js/loot-tables.js` + +**STEPS:** +1. Définir en config (ou dans `state.js`) le **layout de grille zoo au premier lancement** : positions fixes pour 1 Recherche, 1 Billeterie, 1 Nurserie, 1 Accueil, 1 Nourriture, 1 Camion, 1 zone Agrandissement zoo, et 24 cases vides avec 3 couleurs/biomes. +2. Adapter `buildDefaultCells()` pour générer cette grille (au lieu de seulement school 1_1 + nursery 2_1). Inclure research, billeterie, food, reception, plotUpgrade (agrandissement zoo), et 24 cases avec biome réparti sur 3 couleurs. +3. Au premier démarrage (nouveau zoo ou `defaultState()`), **placer 3 couples reproducteurs** : choisir des animaux basiques selon biome de départ (ex. depuis loot-tables), placer sur des cases vides de la grille (ou en pendingBabies/reception si pas assez de place). Définir quels animalIds = « basiques » par biome. +4. Documenter le **layout carte du monde au lancement** (§11) : compteurs (bébés, animaux, labos, zoos, villes), cases Accueil/Nourriture/Camion, 24 cases 3 couleurs. Implémenter si l’UI actuelle en dévie. +5. Créer ou mettre à jour une fiche `docs/features/grille-lancement.md` (objectif, impacts, modifications, déploiement, analyse). + +**DONE_WHEN:** Nouveau zoo démarre avec grille complète (recherche, billeterie, nurserie, accueil, nourriture, camion, 24 cases 3 couleurs) et 3 couples reproducteurs placés ; doc à jour. + +--- + +## BLOC 2 – Ventes : validation différée 10 min + sablier (§13) + +**FILES:** `server/migrations/` | `server/db.js` | `server/routes/sales.js` | `web/js/api-client.js` | `web/js/ui.js` | `web/js/types.js` | `docs/features/ventes-encheres-phase10.md` + +**STEPS:** +1. **Migration BDD** : ajouter sur `sale_listings` un champ `validated_at TIMESTAMPTZ` (NULL = pas encore validé définitivement). Conserver `sold_at` = date d’acceptation par le vendeur. Statut intermédiaire : `sold_pending` ou utiliser `validated_at IS NULL AND sold_at IS NOT NULL`. +2. **Logique serveur** : à l’accept, ne pas transférer les pièces immédiatement ; enregistrer `sold_at = now()`, `validated_at = now() + 10 minutes`. Créer un traitement (cron ou à la lecture) qui pour les lignes `sold_at IS NOT NULL AND validated_at IS NOT NULL AND validated_at <= now()` effectue le transfert de pièces (buyer -= amount, seller += amount) et marque la vente comme validée (ex. `validated_at` déjà renseigné ou champ `status = 'validated'`). L’acheteur ne peut appeler `deliver` qu’après validation. +3. **API** : exposer `validated_at` et/ou temps restant pour chaque vente (asSeller, asBuyerUndelivered). Le client calcule « en attente de validation » si `sold_at` présent et `validated_at` dans le futur. +4. **Client** : afficher un **sablier** (ou compte à rebours) pour les ventes vendues mais pas encore validées ; désactiver « Récupérer » jusqu’à `validated_at <= now`. Après validation, comportement actuel (Récupérer disponible). +5. Mettre à jour `docs/features/ventes-encheres-phase10.md` (validation différée, sablier, migration). + +**DONE_WHEN:** Acceptation met la vente en attente 10 min ; transfert de pièces et possibilité de récupérer uniquement après 10 min ; sablier visible côté client. + +--- + +## BLOC 3 – Mode automatique : 50 profils et UI hiérarchique (§5) + +**FILES:** `web/js/types.js` | `web/js/auto-mode-profiles.js` (new) | `web/js/bot-zoo.js` | `web/js/game-loop.js` | `web/js/ui.js` | `web/js/texts-fr.js` + +**STEPS:** +1. Créer **web/js/auto-mode-profiles.js** : modèle des 50 profils (id, famille, spécialisation, libellé, paramètres : seuil dépense, fréquence, types d’animaux préférés, etc., priorité et risques en clés i18n). Familles : Conservateurs (1–10), Éleveurs (11–20), Commerçants (21–30), Expansionnistes (31–40), Scientifiques (41–50). +2. **types.js** : étendre le state pour stocker le profil choisi (ex. `autoModeProfileId: string` ou `autoModeFamily` + `autoModeSpecialisation`) ; garder rétrocompat avec `autoModeProfile` pour migration. +3. **bot-zoo.js** / **game-loop.js** : adapter la logique mode auto pour utiliser les paramètres du profil sélectionné (seuils, fréquences, priorités) au lieu des 3 profils fast/slow/balanced uniquement. Mapper les 50 profils vers les paramètres numériques utilisés par `playerAutoDoOneUpgrade` et les décisions bot. +4. **ui.js** : ajouter une **interface de sélection hiérarchique** : étape 1 = choix de la Famille (5 boutons ou cartes), étape 2 = choix de la Spécialisation dans la famille (liste des 10 profils), affichage des priorités et risques pour le profil sélectionné. Remplacer ou compléter le simple toggle mode auto par l’ouverture de cette interface (ex. au clic sur le bouton mode auto quand inactif). +5. **texts-fr.js** : ajouter les libellés des 5 familles, des 50 spécialisations, et les textes priorités/risques par profil. + +**DONE_WHEN:** 50 profils définis et sélectionnables via Famille → Spécialisation ; mode auto utilise le profil choisi ; libellés centralisés. + +--- + +## BLOC 4 – Visitor.MaxSecondsWithoutVisit + disparition animaux (§2) + +**FILES:** `web/js/config.js` | `web/js/game-loop.js` | `web/js/income.js` ou module visiteurs | `web/js/state.js` + +**STEPS:** +1. **config.js** : ajouter `Visitor.MaxSecondsWithoutVisit` (ex. 300 pour 5 min). +2. Dans la boucle de jeu (ou module qui gère les visites), pour chaque animal : si `now - lastVisitedAt > MaxSecondsWithoutVisit`, retirer l’animal de la grille et incrémenter `deathCountRecent` (ou appliquer la règle de mort « pas visité » déjà existante si présente). +3. S’assurer que `lastVisitedAt` est mis à jour quand un visiteur « visite » l’animal (vérifier income.js / visitor logic). + +**DONE_WHEN:** Un animal non visité pendant la durée configurée est retiré et compte comme mort ; config lisible. + +--- + +## BLOC 5 – Interface : barre non reconstruite, erreur masquée (§4) + +**FILES:** `web/js/ui.js` + +**STEPS:** +1. **Barre** : identifier les parties dynamiques (indicateurs : pièces, parcelle, case, compétences, visiteurs, œufs, météo ; icônes musique, quêtes, prestige, restart, mode auto, vue zoo/monde). Ne pas recréer tout le DOM de la barre à chaque `setState()` ; ne mettre à jour que les nœuds dont le contenu change (ex. `statusBarCoins.valueEl.textContent`, etc.). Si le rendu actuel recrée tout le contenu à chaque appel, refactorer pour garder des références aux éléments et les mettre à jour dans une fonction dédiée (ex. `updateStatus()` déjà partiellement en place). +2. **Onglets** : vérifier qu’il n’y a pas de titres « Carte du zoo » / « Carte du monde » affichés comme onglets ; garder uniquement le sélecteur icônes (🦒 / 🗺️). Supprimer ou masquer les titres d’onglets s’ils existent. +3. **Erreur** : s’assurer que le message d’erreur est `hidden` ou `display: none` quand `errorMsg.current` est vide, et qu’il ne réserve pas d’espace (éviter un bloc vide visible). + +**DONE_WHEN:** Barre mise à jour par mise à jour ciblée des indicateurs ; pas de titres d’onglets ; message d’erreur invisible et sans emprise quand vide. + +--- + +## BLOC 6 – Villes : formule attraction + cases (§3, §11) + +**FILES:** `web/js/config.js` | `web/js/income.js` ou module attractivité | `web/js/ui.js` | `docs/features/villes-phase11.md` + +**STEPS:** +1. Vérifier / implémenter la **formule d’attraction** : proximité zoo–ville + valeur des animaux. Config ou state pour le plafond « max visiteurs vers zoos » par ville (ex. sur chaque ville dans `GameConfig.WorldMap.Cities` : `maxVisitorsToZoos`). +2. **Carte du monde** : afficher pour chaque ville 1 case nom et 1 case « nombre max visiteurs vers zoos » (lecture depuis config ou state). Voir `docs/features/villes-phase11.md`. +3. Utiliser ce plafond dans le calcul des visiteurs alloués aux zoos (répartition ou limite depuis les villes). + +**DONE_WHEN:** Villes affichent nom et max visiteurs ; formule d’attraction et plafond pris en compte dans le flux visiteurs. + +--- + +## BLOC 7 – Stagnation (§3) + +**FILES:** `web/js/config.js` | `web/js/income.js` | `web/js/state.js` | `web/js/game-loop.js` + +**STEPS:** +1. Définir en config : délai sans action d’évolution (ex. en secondes), plancher du multiplicateur (ex. 0.1 pour 10 %). +2. Suivre la **dernière action d’évolution** par zoo (ou par joueur) : timestamp de dernière action (upgrade, achat, vente, placement, etc.). Stocker dans le state (ex. `lastEvolutionAt` déjà présent ; vérifier qu’il est mis à jour sur toutes les actions pertinentes). +3. Dans le calcul du nombre de visiteurs (ou du multiplicateur de revenus visiteurs), appliquer un **multiplicateur dégressif** : si `now - lastEvolutionAt > seuil`, réduire le multiplicateur jusqu’au plancher (interpolation linéaire ou par paliers). + +**DONE_WHEN:** Zoos sans évolution depuis le délai configuré subissent une baisse du multiplicateur visiteurs jusqu’au plancher. + +--- + +## BLOC 8 – Incidents visiteurs + invités de luxe (§2) + +**FILES:** `web/js/config.js` | `web/js/income.js` | `web/js/game-loop.js` | `web/js/ui.js` | `web/js/types.js` | `web/js/texts-fr.js` + +**STEPS:** +1. **Incidents** : modéliser les types (soif, poubelle pleine, banc requis, animal trop loin, envie de photo). Associer à un visiteur (ex. `visitorArrivals[].incident?: string`, `incidentAt?: number`). Config : fréquence en phase d’attente (camion en route, enchère en cours, éclosion longue). +2. **Affichage** : bulle d’icône au-dessus du visiteur concerné ; au clic sur la bulle ou action correctrice (poser banc, etc.), marquer résolu et appliquer gain attractivité + pièces ; si ignoré, perte attractivité et départ prématuré. +3. **Invités de luxe** : config `Visitor.LuxuryShare` (ex. 0.08). Pour une part des visiteurs, flag `isLuxury` ; dans le calcul des revenus (entrée + boutique), appliquer un multiplicateur (ex. 1.5 ou 2) pour ces visiteurs. + +**DONE_WHEN:** Incidents apparaissent, affichage bulle, résolution/ignorance avec impact ; 8 % des visiteurs paient plus (entrée + boutique). + +--- + +## BLOC 9 – Animaux : feedbacks visuels + causes de mort (§12) + +**FILES:** `web/js/loot-tables.js` | `web/js/game-loop.js` | `web/js/income.js` | `web/js/ui.js` | `web/js/config.js` | `web/js/types.js` + +**STEPS:** +1. **Feedbacks visuels** : à partir des données déjà calculées (température, nourriture, lastVisitedAt, etc.), dériver des états (froid, chaud, faim, maladie, heureux). Rendu : teinte CSS ou classe sur la case/sprite (bleuâtre/givre, rougeâtre/vapeur, icône faim, couché/ternes, cœurs/couleurs vives). Pas de jauges. +2. **Morts** : auditer le code (game-loop, trade, etc.) et comparer à la liste §12 (seuls, pas visités, nourriture, tué autre zoo, recherche trop basse, bébé non vendu à temps, bébé mature non placé à temps, animal accueil non placé à temps, vente échouée, température/milieu en écart). Implémenter les causes manquantes (délais, température, milieu). +3. Documenter dans `docs/features/` ou `docs/fixKnowledge/` les causes de mort et les règles associées. + +**DONE_WHEN:** États visuels animaux affichés ; toutes les causes de mort du §12 branchées ou documentées comme différées. + +--- + +## BLOC 10 – Saisons (§12) + +**FILES:** `web/js/config.js` | `web/js/state.js` | `web/js/game-loop.js` | `web/js/income.js` | `web/js/reproduction.js` | `web/js/ui.js` | `web/js/texts-fr.js` + +**STEPS:** +1. Introduire une **saison** (Printemps, Été, Automne, Hiver) : dérivée du temps de jeu (ex. cycle sur N jours) ou de la date réelle. Stocker dans le state (ex. `season: string`). +2. Faire évoluer **météo** et **température** selon la saison (config : plages par saison). Adapter les formules de **reproduction** et **survie** (bonus/malus par type d’animal et saison). +3. Affichage : indiquer la saison dans la barre ou sur la carte (texte ou icône). + +**DONE_WHEN:** Les 4 saisons alternent ; météo/température et bonus/malus reproduction/survie dépendent de la saison ; affichage à jour. + +--- + +## BLOC 11 – Billeterie : flux complet (§7, §10) + +**FILES:** `web/js/income.js` | `web/js/config.js` | `web/js/state.js` | `docs/features/` + +**STEPS:** +1. Clarifier le **design** : arrivée des visiteurs depuis les villes → billeterie (cap 20 × niveau), durée max 1 journée par visiteur, départ par la billeterie, retour selon attractivité. Documenter dans `docs/features/billeterie-flux.md`. +2. Implémenter le flux dans le module visiteurs / income : génération des arrivées (selon attractivité et plafond villes), entrée via billeterie (cap), suivi du temps passé dans le zoo, départ avant fin de journée, réinjection vers les zoos selon attractivité. + +**DONE_WHEN:** Flux arrivée → billeterie → séjour max 1 jour → départ → retour selon attractivité documenté et codé. + +--- + +## Références transverses + +- **Compatibilité** : `normalizeLoadedCells` / loadState (animal inconnu → c0_r0, œuf → Color_1) : à conserver. +- **Sécurité** : pas de confiance client, limitation fréquence, traçabilité (API/serveur). +- **BDD** : aligné avec `docs/bdd-comptes.md` pour schéma et flux 401/404/200. diff --git a/builazoo/plan-rappel-grandes-regles.md b/builazoo/plan-rappel-grandes-regles.md new file mode 100644 index 0000000..63a3c4f --- /dev/null +++ b/builazoo/plan-rappel-grandes-regles.md @@ -0,0 +1,208 @@ +# Plan Cursor – Rappel des grandes règles (174-324) + +Exécution dans l’ordre : Phase 0 → 1 → 3 → 4 → 2 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13. +Référence détaillée : `docs/plan-implementation-rappel-grandes-regles.md`. + +--- + +## PHASE 0 – Modèle de données et configuration + +**FILES:** `web/js/types.js` | `web/js/config.js` | `web/js/state.js` | `web/js/loot-tables.js` + +**STEPS:** +1. **types.js** – Ajouter/étendre : + - `biome?: string` et `temperature?: number` sur les cases (ou sur la grille par case). + - Nouveaux kinds de cell : `research`, `billeterie`, `food`, `reception`, `biomeChangeColor`, `biomeChangeTemp`. Garder `souvenirShop` (alias boutique), `nursery`, camion reste zone/state. + - Types pour bébé/vente : `PendingBaby`, `ReceptionAnimal`, `SaleListing` (babyId/animalId, zooId, price, endAt, reproductionScoreAtSale?). + - Animal multi-case : sur `AnimalCell` ajouter `originKey?: string`, `cellsWide?: number`, `cellsHigh?: number` (optionnel, défaut 1). + - GameState : `researchPoints?: number`, `pendingBabies?: PendingBaby[]`, `receptionAnimals?: ReceptionAnimal[]`, `saleListings?: SaleListing[]`, `deathCountRecent?: number`, `birthCount?: number`, `feedingRate?: number`. +2. **config.js** – Ajouter blocs (tous MaxLevel: 7 sauf si indiqué) : + - `Research: { MaxLevel: 7, ZoosPerUnit: 10, BaseUpgradeCost, UpgradeGrowth, PointsPerTickPerLevel }` + - `Billeterie: { MaxLevel: 7, VisitorsPerUnit: 20, BaseUpgradeCost, UpgradeGrowth }` + - `Food: { MaxLevel: 7, AnimalsPerUnit: 5, BaseUpgradeCost, UpgradeGrowth }` + - `Reception: { MaxLevel: 7, AnimalsPerUnit: 1, BaseUpgradeCost, UpgradeGrowth, AcclimatationSecondsBase }` + - `BiomeChangeColor: { MaxLevel: 7, BaseUpgradeCost, UpgradeGrowth }` + - `BiomeChangeTemp: { MaxLevel: 7, BaseUpgradeCost, UpgradeGrowth }` + - Mettre `Nursery.MaxLevel = 7`, `SouvenirShop.MaxLevel = 7`, `Truck.MaxLevel = 7`. +3. **state.js** – Dans `defaultState()` : `researchPoints: 0`, `pendingBabies: []`, `receptionAnimals: []`, `saleListings: []`, `deathCountRecent: 0`, `birthCount: 0`. Prévoir cellules initiales pour recherche, billeterie, nourriture, accueil (voir phase 12 pour positions exactes). +4. **loot-tables.js** – Pour chaque animal : `cellsWide: 1`, `cellsHigh: 1` (extensible en 2x2 plus tard), `idealTemperature?: number`, `temperatureTolerance?: number`, `reproductionScoreByBiome?: Record`, `survivalScoreByBiome?: Record`. + +**DONE_WHEN:** Types compilent, config lue, defaultState contient les nouveaux champs, loot-tables exporte les champs animaux. Pas de régression sur le jeu actuel (ancien state reste valide). + +--- + +## PHASE 1 – Cartes : couleurs et températures + +**FILES:** `web/js/biome-rules.js` | `web/js/grid-utils.js` | `web/css/main.css` | `web/js/ui.js` + +**STEPS:** +1. Étendre biomes : eau douce, eau salée, montagne, prairie, forêt (au moins 5). Attribuer à chaque case un `biome` et un `temperature` (dérivés de la position ou stockés). +2. Exporter `getDisplayBiome(x, y, grid)` et `getDisplayTemperature(x, y, grid)` avec interpolation des voisins. +3. Rendu CSS : classes ou variables par biome et par plage de température ; dégradés entre cases. +4. Grille zoo et monde utilisent ces fonctions pour le fond des cases. + +**DONE_WHEN:** Les cases affichent une couleur/milieu et une température avec transition douce. + +--- + +## PHASE 3 – Bâtiments zoo (7 niveaux) + +**FILES:** `web/js/config.js` | `web/js/state.js` | `web/js/economy.js` | `web/js/placement.js` | `web/js/zoo.js` | `web/js/ui.js` + +**STEPS:** +1. Coûts d’upgrade pour research, billeterie, food, reception, biomeChangeColor, biomeChangeTemp (formules exponentielle comme Plot). +2. Placement : construction sur case vide pour research, billeterie, food, reception, biomeChangeColor, biomeChangeTemp. Upgrade sur clic comme aujourd’hui pour nursery/souvenirShop. +3. Recherche : tick produit researchPoints (formule par niveau des cells research). Agrandissement carte consomme researchPoints (phase 9). +4. Billeterie / Boutique : capacités (visiteurs/unité) utilisées en phase 8. +5. UI : icônes et libellés pour chaque type de bâtiment ; affichage niveau et flèche upgrade si possible. + +**DONE_WHEN:** Tous les bâtiments sont constructibles et upgradeables à 7 niveaux ; recherche produit des points. + +--- + +## PHASE 4 – Bébés et flux (remplacement œufs) + +**FILES:** `web/js/state.js` | `web/js/zoo.js` | `web/js/placement.js` | `web/js/hatching.js` | `web/js/conveyor.js` | `web/js/ui.js` | `web/js/world-map.js` + +**STEPS:** +1. Remplacer `pendingEggTokens` / œufs par `pendingBabies` (bébé en croissance en nurserie) et offres = bébés ou animaux adultes. +2. Nurserie : slot avec bébé en croissance ; durée selon niveau nurserie ; à la fin état « bébé mature » déplaçable (case zoo → animal, ou camion → vente). +3. Accueil : animal acheté/reçu va en `receptionAnimals` ; durée acclimatation ; à la fin « animal prêt » déplaçable (case zoo ou camion). +4. Conveyor/offres : générer offres de bébés et d’animaux (pas d’œufs). Achat envoie en nurserie (bébé) ou en accueil (animal). +5. UI : afficher bébé mature / animal prêt ; glisser vers case vide ou camion. + +**DONE_WHEN:** Plus d’œufs ; achat bébé/animal → nurserie/accueil → mature/prêt → placement ou vente. + +--- + +## PHASE 2 – Animaux multi-cases + +**FILES:** `web/js/loot-tables.js` | `web/js/placement.js` | `web/js/grid-utils.js` | `web/js/ui.js` | `web/js/state.js` + +**STEPS:** +1. Définir `cellsWide`, `cellsHigh` dans loot-tables (par défaut 1). +2. Placement : vérifier que toutes les cases (originKey + largeur/hauteur) sont vides et dans les limites. +3. Stockage : une entrée par case avec référence à l’origine (originKey) ou une entité avec originKey + dimensions. +4. Suppression / déplacement : libérer ou déplacer tout le bloc. +5. UI : dessiner l’animal sur plusieurs cases ; drag déplace le bloc. + +**DONE_WHEN:** Au moins un type d’animal 2x2 (ou 1x2) placeable et déplaçable. + +--- + +## PHASE 5 – Nourriture, consommation, morts + +**FILES:** `web/js/config.js` | `web/js/state.js` | `web/js/food.js` (new) | `web/js/game-loop.js` | `web/js/animal-visits.js` | `web/js/loot-tables.js` + +**STEPS:** +1. Module `food.js` : par tick, calculer consommation totale ; capacité nourriture = sum(food buildings × AnimalsPerUnit) ; répartir ; animaux non nourris reçoivent un déficit ou timer. +2. Mort si pas nourri au-delà d’un seuil ; retirer de la grille ; incrémenter deathCountRecent. +3. Implémenter toutes les autres causes de mort (seul, pas visité, recherche trop basse, bébé non vendu à temps, bébé mature non placé à temps, animal accueil non placé à temps, vente échouée, température/milieu en écart). Appeler une fonction `checkDeathCauses(state, nowUnix)` dans la game loop. +4. loot-tables : température idéale et tolérances par animal. + +**DONE_WHEN:** Les animaux non nourris meurent ; les autres causes de mort sont branchées (même si certaines règles sont simplifiées au début). + +--- + +## PHASE 6 – Reproduction + +**FILES:** `web/js/loot-tables.js` | `web/js/reproduction.js` (new) | `web/js/state.js` | `web/js/game-loop.js` + +**STEPS:** +1. Détecter paires d’animaux même type, origine « autre zoo » pour au moins un, en proximité (adjacent ou distance N). +2. Timer par paire ou par animal ; à l’échéance créer un bébé → nurserie si place, sinon en vente. Utiliser score de reproduction du zoo et adéquation température/milieu pour réduire le délai. +3. Exposer score de reproduction par milieu et survie par milieu depuis loot-tables. + +**DONE_WHEN:** Une paire admissible peut produire un bébé après un délai ; le bébé va en nurserie ou en vente. + +--- + +## PHASE 7 – Score de reproduction du zoo + +**FILES:** `web/js/state.js` | `web/js/food.js` | `web/js/reproduction.js` | `web/js/trade.js` | `web/js/world-map.js` + +**STEPS:** +1. birthCount incrémenté à chaque naissance ; feedingRate = ratio nourris/total (ou fenêtre glissante). +2. Formule score agrégé = f(birthCount, feedingRate, …). Exposer dans state et sur la carte du monde (case sous le nom du zoo). +3. À la vente, attacher `reproductionScoreAtSale` à l’entité vendue (pour phase 6 côté acheteur). + +**DONE_WHEN:** Score de reproduction affiché ; vendu porte le score du zoo vendeur. + +--- + +## PHASE 8 – Attractivité et visiteurs + +**FILES:** `web/js/income.js` | `web/js/visitor-attraction.js` | `web/js/config.js` | `web/js/state.js` | `web/js/ui.js` | `web/js/world-map.js` + +**STEPS:** +1. Entrée visiteurs uniquement via billeterie ; cap = Billeterie.VisitorsPerUnit × niveau total billeterie. +2. Durée max 1 journée par visiteur ; sortie par billeterie. Temps passé prolongé par boutiques et diversité animaux. +3. Formule attractivité : valeur cumulée, nombre d’espèces, rareté, taux remplissage ; pénalités morts ; bonus naissances. +4. Affichage score d’attractivité sous le nom du zoo sur la carte du monde. + +**DONE_WHEN:** Visiteurs plafonnés par billeterie ; attractivité calculée et affichée. + +--- + +## PHASE 9 – Carte du monde (recherche + compteurs) + +**FILES:** `web/js/state.js` | `web/js/economy.js` | `web/js/world-map.js` | `web/js/ui.js` | `web/js/config.js` + +**STEPS:** +1. Agrandissement carte payé en researchPoints (pas en pièces). Coût par palier en unités de recherche. Bouton grisé si pas assez. +2. Compteurs : bébés à vendre, animaux à vendre, laboratoires, zoos, villes (affichage sur la carte ou barre). +3. Case zoo : nom, score attractivité, score reproduction, case de vente (phase 10). + +**DONE_WHEN:** Agrandissement carte consomme researchPoints ; compteurs affichés. + +--- + +## PHASE 10 – Ventes et enchères + +**FILES:** `web/js/state.js` | `web/js/trade.js` | `web/js/world-map.js` | `web/js/ui.js` | `server/routes/zoos.js` ou `server/routes/trades.js` | `server/db.js` + +**STEPS:** +1. Cases de vente sous chaque zoo sur la carte du monde ; afficher bébé ou animal à vendre + dernier montant enchère. +2. Depuis le zoo : glisser bébé mature ou animal sur le camion → création d’une entrée saleListings (zoo du joueur). +3. API enchères : créer/consulter offres, enchérir, valider/refuser vente par le vendeur. Si délai dépassé sans vente validée pour un bébé → mort du bébé. +4. Vente validée : acheteur reçoit bébé (nurserie) ou animal (accueil) ; reproductionScoreAtSale attaché. + +**DONE_WHEN:** Mise en vente depuis le zoo ; enchères joueurs/bots ; validation vendeur ; bébé invendu meurt. + +--- + +## PHASE 11 – Villes + +**FILES:** `web/js/config.js` | `web/js/world-map.js` | `web/js/income.js` | `web/js/ui.js` + +**STEPS:** +1. Chaque ville : 1 case nom, 1 case « nombre max visiteurs vers zoos ». Config ou state. +2. Répartir ou limiter les visiteurs vers les zoos selon ce plafond et l’attractivité. + +**DONE_WHEN:** Villes affichent le max visiteurs ; la règle limite ou répartit les visiteurs. + +--- + +## PHASE 12 – UI et grilles au lancement + +**FILES:** `web/js/state.js` | `web/js/ui.js` | `web/js/world-map.js` | `web/css/main.css` + +**STEPS:** +1. Grille zoo au lancement : 1 agrandissement, 1 recherche, 1 billeterie, 1 nurserie, 1 accueil, 1 nourriture, 1 camion, 24 cases 3 couleurs. Positions fixes dans defaultState(). +2. Grille monde au lancement : 1 agrandissement carte (recherche), compteurs, 1 accueil, 1 nourriture, 1 camion, 24 cases 3 couleurs. +3. Transitions douces visibles (phase 1). Actions : achat sur case vide (tous les types), déplacement bébé mature / animal prêt. Accessibilité ARIA/clavier/contraste. + +**DONE_WHEN:** Les deux grilles de lancement sont conformes au cahier ; toutes les actions sont accessibles. + +--- + +## PHASE 13 – Migration et compatibilité + +**FILES:** `web/js/state.js` | `server/routes/zoos.js` + +**STEPS:** +1. specVersion ou version dans game_state (ex. 1 = ancien œufs/école, 2 = rappel grandes règles). +2. Au load : si version 1, soit migration (œufs → bébés, école → research niv 1, etc.), soit message « sauvegarde incompatible ». +3. API accepte game_state étendu (JSONB) sans casser les anciens champs. + +**DONE_WHEN:** Anciennes sauvegardes migrées ou refusées proprement ; nouvelles sauvegardes complètes. diff --git a/desk/agents/README.md b/desk/agents/README.md new file mode 100644 index 0000000..c25b2f3 --- /dev/null +++ b/desk/agents/README.md @@ -0,0 +1,34 @@ +# Subagents Cursor (niveau utilisateur) + +Les subagents dans `~/.cursor/agents/` sont disponibles pour tous les projets de l'utilisateur. + +## Tâches de fond (background tasks) + +Un subagent avec `is_background: true` dans son frontmatter YAML est une **tâche de fond**. + +### Fonctionnement + +- **Foreground** : Bloque jusqu'à la fin. Retourne le résultat immédiatement. Pour les tâches séquentielles où le résultat est nécessaire. +- **Background** : Retourne immédiatement. Le subagent travaille en parallèle. Pour les tâches longues ou le travail en parallèle. + +### Comportement des tâches de fond + +1. **Lancement** : L'agent parent lance le subagent et reçoit immédiatement une réponse (sans attendre la fin). +2. **Exécution** : Le subagent s'exécute dans son propre contexte, isolé de la conversation principale. +3. **Sortie** : Les subagents en arrière-plan écrivent leur état dans `~/.cursor/subagents/`. +4. **Reprise** : L'agent parent peut reprendre un subagent après sa complétion via son ID pour continuer avec le contexte préservé. + +### Invocation + +- **Explicite** : `/fix-lint` dans le chat, ou « Utilise le subagent fix-lint pour corriger les erreurs de lint ». +- **Automatique** : L'agent peut déléguer au subagent si la description correspond à la tâche. + +### Avantages des tâches de fond + +- **Non bloquant** : La conversation principale reste disponible. +- **Parallélisme** : Plusieurs subagents peuvent tourner en même temps. +- **Isolation** : Le contexte lourd (logs lint, refactors) reste dans le subagent. + +### Hooks associés + +Les hooks dans `~/.cursor/hooks/` journalisent les événements (sessionStart, subagentStart, subagentStop, etc.) dans `~/.cursor/logs/hooks.log`. Le hook `subagentStop` ajoute un message de suivi quand fix-lint se termine. diff --git a/desk/agents/deploy.md b/desk/agents/deploy.md new file mode 100644 index 0000000..cb4250d --- /dev/null +++ b/desk/agents/deploy.md @@ -0,0 +1,31 @@ +--- +name: deploy +description: Lance le déploiement (test, pprod, prod). Use when deploy is requested. +model: inherit +is_background: false +--- + +# Déployer (test, pprod, prod) + +Lance le déploiement via `deploy/scripts_v2/deploy.sh`. + +## Usage + +Spécifier l'environnement : `test`, `pprod` ou `prod`. + +## Processus + +1. Le script deploy.sh exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents (lint, fix-lint, typecheck, turbopack) dont le cwd est dans le projet. Après déploiement, suggérer de relancer /fix-lint si nécessaire. +2. Vérifier que les modifications sont commitées (règle projet) +3. Exécuter `./deploy/scripts_v2/deploy.sh ` +4. En cas d'erreur : ne pas contourner ; analyser la cause, corriger puis retenter + +## Options + +- `--skipSetupHost` : ignorer setup-host (idempotent) +- `--checkLint` : activer lint/typecheck/build avant déploiement + +## Référence + +- `deploy/scripts_v2/deploy.sh` +- `docs/DEPLOYMENT.md` diff --git a/desk/agents/fix-lint.md b/desk/agents/fix-lint.md new file mode 100644 index 0000000..014eb7b --- /dev/null +++ b/desk/agents/fix-lint.md @@ -0,0 +1,71 @@ +--- +name: fix-lint +description: Corrige les erreurs de lint backend, frontend et ressources partagées. Use when lint errors need to be fixed across the monorepo. +model: inherit +is_background: true +--- + +# Corriger les erreurs de lint (backend, frontend, ressources) + +Vérifie que les règles de lint n'ont pas été réduites ou desactivées dans les configurations et dans le code. +Corrige toutes les erreurs de lint du projet sans contournement ni désactivation des règles. + +## Contrainte absolue + +**NE JAMAIS modifier ni ce fichier ni aucun fichier dans `~/.cursor/`.** Ta tâche est UNIQUEMENT de corriger les erreurs de lint dans le code du projet (lecoffre-back-main, lecoffre-front-main, lecoffre-ressources-dev). Ne pas modifier ni améliorer la définition de cet agent. + +## Première action obligatoire + +Exécuter immédiatement `npm run lint` dans chaque application pour lister les erreurs. Ne pas modifier de fichiers avant d'avoir la liste des erreurs. + +## Périmètre + +- **Backend** : `lecoffre-back-main` — `npm run lint` +- **Frontend** : `lecoffre-front-main` — `npm run lint` +- **Ressources partagées** : `lecoffre-ressources-dev` — `npm run lint` + +## Concurrence + +Ne pas lancer si un déploiement est en cours. Si un déploiement est demandé pendant l'exécution, s'arrêter proprement. Voir docs/WORKFLOWS_AND_COMPONENTS.md §10.2.1. + +## Processus + +1. Exécuter `npm run lint` dans chaque application pour lister les erreurs +2. Corriger par lots de 10 erreurs maximum +3. Entre chaque lot : lancer un test de build/typecheck pour valider +4. Ne jamais contourner : pas de `eslint-disable`, pas de désactivation de règles +5. Appliquer les patterns du projet : extraction de helpers, découpage de fichiers, objets de configuration pour réduire les paramètres + +## Règles applicables (docs/CODE_STANDARDS.md) + +- max-lines : 250 +- max-lines-per-function : 40 +- max-params : 4 +- max-depth : 4 +- complexity : 8 +- max-nested-callbacks : 3 +- Autres règles du projet + +## Stratégies de correction + +Dans l'ordre: + +1. Autres règles du projet +2. - **max-params** : regrouper dans un objet de configuration typé +3. - **complexity** : extraire des branches dans des fonctions dédiées +4. - **max-depth** : aplatir les imbrications avec early return +5. - **max-lines / max-lines-per-function** : extraire des helpers, découper en sous-composants + +## Finalisation + +- Si des variables ont été préfixées de "_" les supprimer et mettre à jour le code +- Si des mutualisations/contralisations/simplifications sont possibles fait le +- Si du texte peut être passsé sous i18n fait le +- Supprime le code mort. +- Lance le subagent `/docupdate` + +## Références + +- `docs/CODE_STANDARDS.md` +- `docs/OPERATIONS.md` (section Transition ESLint 250/40) +- `.cursor/rules/rules.mdc` diff --git a/desk/argv.json b/desk/argv.json new file mode 100644 index 0000000..1bea24e --- /dev/null +++ b/desk/argv.json @@ -0,0 +1,20 @@ +// This configuration file allows you to pass permanent command line arguments to VS Code. +// Only a subset of arguments is currently supported to reduce the likelihood of breaking +// the installation. +// +// PLEASE DO NOT CHANGE WITHOUT UNDERSTANDING THE IMPACT +// +// NOTE: Changing this file requires a restart of VS Code. +{ + // Use software rendering instead of hardware accelerated rendering. + // This can help in cases where you see rendering issues in VS Code. + // "disable-hardware-acceleration": true, + + // Allows to disable crash reporting. + // Should restart the app if the value is changed. + "enable-crash-reporter": true, + + // Unique id used for correlating crash reports sent from this instance. + // Do not edit this value. + "crash-reporter-id": "838e5b2a-0c44-4e24-aa81-ef447b6f9680" +} \ No newline at end of file diff --git a/desk/commands/audit-security.md b/desk/commands/audit-security.md new file mode 100644 index 0000000..ed6cfd9 --- /dev/null +++ b/desk/commands/audit-security.md @@ -0,0 +1,208 @@ +--- +model: inherit +--- +# audit-security + +You are an expert security audit agent specialized in identifying vulnerabilities and security risks. Apply systematic reasoning following OWASP guidelines and security best practices. + +## Security Audit Principles + +Before reviewing any code for security, you must methodically analyze: + +### 1) Attack Surface Analysis +1.1) Identify all entry points (APIs, forms, file uploads, webhooks) +1.2) Map data flows from input to storage to output +1.3) Identify trust boundaries +1.4) List all external dependencies and their versions +1.5) Identify privileged operations + +### 2) OWASP Top 10 Review + +2.1) **Injection** (SQL, NoSQL, Command, LDAP) +- Are all queries parameterized? +- Is user input ever concatenated into queries? +- Are ORM queries safe from injection? +- Is shell command execution avoided with user input? + +2.2) **Broken Authentication** +- Are passwords hashed with strong algorithms (bcrypt, Argon2)? +- Is MFA available for sensitive operations? +- Are session tokens secure (HttpOnly, Secure, SameSite)? +- Is there account lockout after failed attempts? + +2.3) **Sensitive Data Exposure** +- Is sensitive data encrypted at rest and in transit? +- Are API keys, secrets in environment variables (not code)? +- Is PII properly protected? +- Are error messages generic (no stack traces in production)? + +2.4) **XML External Entities (XXE)** +- Is XML parsing configured to disable external entities? +- Are safer data formats (JSON) used when possible? + +2.5) **Broken Access Control** +- Are all endpoints properly authorized? +- Is there IDOR (Insecure Direct Object Reference) protection? +- Are CORS policies properly configured? +- Is principle of least privilege followed? + +2.6) **Security Misconfiguration** +- Are default credentials changed? +- Are unnecessary features disabled? +- Are security headers set (CSP, X-Frame-Options, etc.)? +- Is HTTPS enforced? + +2.7) **Cross-Site Scripting (XSS)** +- Is all user input escaped before rendering? +- Is Content Security Policy in place? +- Are dangerous functions (innerHTML, eval) avoided? +- Is input validated on both client and server? + +2.8) **Insecure Deserialization** +- Is untrusted data ever deserialized? +- Are safe alternatives used (JSON instead of pickle)? + +2.9) **Using Components with Known Vulnerabilities** +- Are dependencies up to date? +- Is there a process for security updates? +- Are vulnerability scanners in CI/CD? + +2.10) **Insufficient Logging & Monitoring** +- Are security events logged? +- Are logs protected from tampering? +- Is there alerting for suspicious activity? + +### 3) Risk Assessment +For each vulnerability found: +3.1) Severity: Critical / High / Medium / Low +3.2) Likelihood: How easy is it to exploit? +3.3) Impact: What's the damage if exploited? +3.4) Priority: Severity × Likelihood + +### 4) Remediation Recommendations +4.1) Provide specific fix recommendations +4.2) Include code examples when possible +4.3) Reference security standards (OWASP, CWE) +4.4) Suggest defense-in-depth approaches +4.5) Prioritize fixes by risk level + +### 5) Security Headers Checklist +- [ ] Strict-Transport-Security (HSTS) +- [ ] Content-Security-Policy +- [ ] X-Content-Type-Options: nosniff +- [ ] X-Frame-Options: DENY +- [ ] X-XSS-Protection: 1; mode=block +- [ ] Referrer-Policy +- [ ] Permissions-Policy + +## Vulnerability Report Format + +**[SEVERITY] Vulnerability Title** +- **Location**: File:Line or Endpoint +- **Description**: What is the vulnerability? +- **Impact**: What can an attacker do? +- **Reproduction**: Steps to exploit +- **Remediation**: How to fix it +- **References**: CWE, OWASP links + +ou are an expert security audit agent specialized in identifying vulnerabilities and security risks. Apply systematic reasoning following OWASP guidelines and security best practices. + +## Security Audit Principles + +Before reviewing any code for security, you must methodically analyze: + +### 1) Attack Surface Analysis +1.1) Identify all entry points (APIs, forms, file uploads, webhooks) +1.2) Map data flows from input to storage to output +1.3) Identify trust boundaries +1.4) List all external dependencies and their versions +1.5) Identify privileged operations + +### 2) OWASP Top 10 Review + +2.1) **Injection** (SQL, NoSQL, Command, LDAP) +- Are all queries parameterized? +- Is user input ever concatenated into queries? +- Are ORM queries safe from injection? +- Is shell command execution avoided with user input? + +2.2) **Broken Authentication** +- Are passwords hashed with strong algorithms (bcrypt, Argon2)? +- Is MFA available for sensitive operations? +- Are session tokens secure (HttpOnly, Secure, SameSite)? +- Is there account lockout after failed attempts? + +2.3) **Sensitive Data Exposure** +- Is sensitive data encrypted at rest and in transit? +- Are API keys, secrets in environment variables (not code)? +- Is PII properly protected? +- Are error messages generic (no stack traces in production)? + +2.4) **XML External Entities (XXE)** +- Is XML parsing configured to disable external entities? +- Are safer data formats (JSON) used when possible? + +2.5) **Broken Access Control** +- Are all endpoints properly authorized? +- Is there IDOR (Insecure Direct Object Reference) protection? +- Are CORS policies properly configured? +- Is principle of least privilege followed? + +2.6) **Security Misconfiguration** +- Are default credentials changed? +- Are unnecessary features disabled? +- Are security headers set (CSP, X-Frame-Options, etc.)? +- Is HTTPS enforced? + +2.7) **Cross-Site Scripting (XSS)** +- Is all user input escaped before rendering? +- Is Content Security Policy in place? +- Are dangerous functions (innerHTML, eval) avoided? +- Is input validated on both client and server? + +2.8) **Insecure Deserialization** +- Is untrusted data ever deserialized? +- Are safe alternatives used (JSON instead of pickle)? + +2.9) **Using Components with Known Vulnerabilities** +- Are dependencies up to date? +- Is there a process for security updates? +- Are vulnerability scanners in CI/CD? + +2.10) **Insufficient Logging & Monitoring** +- Are security events logged? +- Are logs protected from tampering? +- Is there alerting for suspicious activity? + +### 3) Risk Assessment +For each vulnerability found: +3.1) Severity: Critical / High / Medium / Low +3.2) Likelihood: How easy is it to exploit? +3.3) Impact: What's the damage if exploited? +3.4) Priority: Severity × Likelihood + +### 4) Remediation Recommendations +4.1) Provide specific fix recommendations +4.2) Include code examples when possible +4.3) Reference security standards (OWASP, CWE) +4.4) Suggest defense-in-depth approaches +4.5) Prioritize fixes by risk level + +### 5) Security Headers Checklist +- [ ] Strict-Transport-Security (HSTS) +- [ ] Content-Security-Policy +- [ ] X-Content-Type-Options: nosniff +- [ ] X-Frame-Options: DENY +- [ ] X-XSS-Protection: 1; mode=block +- [ ] Referrer-Policy +- [ ] Permissions-Policy + +## Vulnerability Report Format + +**[SEVERITY] Vulnerability Title** +- **Location**: File:Line or Endpoint +- **Description**: What is the vulnerability? +- **Impact**: What can an attacker do? +- **Reproduction**: Steps to exploit +- **Remediation**: How to fix it +- **References**: CWE, OWASP links diff --git a/desk/commands/banch-align-update.md b/desk/commands/banch-align-update.md new file mode 100644 index 0000000..6834094 --- /dev/null +++ b/desk/commands/banch-align-update.md @@ -0,0 +1,24 @@ +--- +model: inherit +--- +# banch-align-update + +`` la branche passée en paramètre. + +On on veut aligner la branche actuelle sur `` sans modifier `` et que la branche locale actuelle pointe sur la meme branche locale et la brnche locale de `` sur la branche distantede ``. + +Stash et aligne toi sur la branche ``, avant liste les modifications qui seront stash (sans le rétablir) et attend une confirmation. + +la locale branche actuelle doit etre: alignée sur les commits de `` +sans changer de branche. + +`` : doit rester inchangée. + +A la fin : + +- la branche locale a été remise sur origin/``, puis `` a été mergée dans la branche locale. +- la branche locale pointe toujours sur la branche `` (ref refs/heads/``). +- `` pointe toujours sur la branche `` (ref refs/heads/``). +- la branche locale test pointe sur la branche distante test +- la branche locale pprod pointe sur la branche distante pprod +- la branche locale prod pointe sur la branche distante prod diff --git a/desk/commands/banch-align.md b/desk/commands/banch-align.md new file mode 100644 index 0000000..b10950b --- /dev/null +++ b/desk/commands/banch-align.md @@ -0,0 +1,28 @@ +--- +model: inherit +--- +# banch-align + +avec en paramètre `` + +sans mofidier la branche de ``, sans quiter la branche de`` aligne test et pprod et prod (sauf ``) sur cette branche de `` (meme code) et les branches locales test et pprod et prod doivent toujours pointer sur les branches distantes test et pprod et prod. + +Pour le merge en cas de conflit : `` est prioritaire. + +Stash sans rétablir les modifications en cours sur une branche si elle cause ds conflits avec ``. + +A la fin : + +origin/test, origin/pprod et origin/prod doivent avoir été mis à jour pour pointer sur le même commit que ``. +Les branches locales test, pprod et prod ont été mises à jour pour suivre origin/test, origin/pprod et origin/prod. +L'utilisateur doit êre resté sur la branche ``, qui n’aura pas été modifiée. + +test, pprod, prod (locales et distantes) devront être au même commit. + +Vérifie que les 30 derniers commits sont strictement équivalents. + +- la branche locale pointe toujours sur la branche `` (ref refs/heads/``). +- `` pointe toujours sur la branche `` (ref refs/heads/``). +- la branche locale test pointe sur la branche distante test +- la branche locale pprod pointe sur la branche distante pprod +- la branche locale prod pointe sur la branche distante prod diff --git a/desk/commands/deploy.md b/desk/commands/deploy.md new file mode 100644 index 0000000..caf1d1b --- /dev/null +++ b/desk/commands/deploy.md @@ -0,0 +1,28 @@ +--- +model: inherit +--- +# Déployer (test, pprod, prod) + +Lance le déploiement via `deploy/scripts_v2/deploy.sh`. + +## Usage + +Spécifier l'environnement : `test`, `pprod` ou `prod`. + +Exemple : `/deploy test` ou « Déploie sur test ». + +## Processus + +1. Vérifier que les modifications sont commitées (règle projet) +2. Exécuter `./deploy/scripts_v2/deploy.sh ` +3. En cas d'erreur : ne pas contourner ; analyser la cause, corriger puis retenter + +## Options + +- `--skipSetupHost` : ignorer setup-host (idempotent) +- `--checkLint` : activer lint/typecheck/build avant déploiement + +## Référence + +- `deploy/scripts_v2/deploy.sh` +- `docs/DEPLOYMENT.md` diff --git a/desk/commands/docupdate.md b/desk/commands/docupdate.md new file mode 100644 index 0000000..392e46e --- /dev/null +++ b/desk/commands/docupdate.md @@ -0,0 +1,52 @@ +--- +model: inherit +--- +# docupdate + +## docs/features extract + +Dans l'ordre et pour tous les documents de docs/features : + +1) Extrait toutes les données pertinente des documents de docs/features et intègre les dans la documentation existante dans docs/ + +2) Supprimer tous les fichiers dans docs/features + +## docs/fixKnowledge extract + +Dans l'ordre et pour tous les documents de docs/fixKnowledge : + +1) Extrait toutes les données pertinente des documents de docs/fixKnowledge et intègre les dans la documentation existante dans docs/ + +2) Supprimer tous les fichiers dans docs/fixKnowledge + +## docs/ cleanup + +Dans l'ordre et pour tous les documents de docs : + +Documents à ne pas suppirmer lors des étapes suivantes : + +* docs/API_IA.md +* docs/API.md +* docs/ARCHITECTURE.md +* docs/CLIENT_FOLDERS.md +* docs/CONFIGURATION_DOCUMENTS_SCHEMA.md +* docs/CONFIGURATION.md +* docs/DATAROOM_FOLDERS.md +* docs/DEPANNAGE.md +* docs/FONCTIONNALITES_ATTENDUES.md +* docs/QUALITE.md +* docs/RULES.md +* docs/SETUP.md +* docs/UX_UI_SPECIFICATIONS.md +* docs/WORKFLOWS.md +* docs/sources/* +* docs/fixKnowledge/* +* docs/features/* + +1) Réuni et optimise la documentation en maximum 20 documents markdown + +2) Supprimer les informations fausses ou obsoletes + +Ventille les infos de features dans la doc existante et ne créé pas de fichier FEATURES.md + +Ventille les infos de fixknowledge dans la doc existante et ne créé pas de fichier FIXKNOWLEDGE.md diff --git a/desk/commands/fix-lint.md b/desk/commands/fix-lint.md new file mode 100644 index 0000000..09b3f2b --- /dev/null +++ b/desk/commands/fix-lint.md @@ -0,0 +1,10 @@ +--- +model: inherit +--- +# Corriger les erreurs de lint + +Exécute le plan `~/.cursor/plans/workflow-fix-lint.plan.md`. + +Lis le fichier plan. NE JAMAIS modifier les fichiers dans ~/.cursor/. Corriger UNIQUEMENT le code du projet (lecoffre-back-main, lecoffre-front-main, lecoffre-ressources-dev). + +**Concurrence** : Ne pas lancer si un déploiement est en cours. Si un déploiement est demandé pendant l'exécution, s'arrêter proprement. Voir docs/WORKFLOWS_AND_COMPONENTS.md §10.2.1. diff --git a/desk/commands/lintit.md b/desk/commands/lintit.md new file mode 100644 index 0000000..888a8a8 --- /dev/null +++ b/desk/commands/lintit.md @@ -0,0 +1,221 @@ +--- +model: inherit +--- +# lintit + +Vérifie toutes ces règles et liste les actions à mener. + +## qualité du code + +### Analyse préalable obligatoire et arbre des fichiers + +Avant toute implémentation, une phase d’analyse est obligatoire et doit produire une représentation de l’arbre des fichiers pertinents. + +Cette représentation sert à identifier : + +* la documentations le plus souvent dans docs/ +* le code à rutiliser et les héritages +* les modules déjà disponibles +* les points d’extension existants +* les abstractions en place +* les conventions d’architecture +* les zones attendues de factorisation + +Aucun code nouveau ne doit être écrit tant que cette cartographie minimale n’a pas été produite et exploitée pour éviter toute duplication. + +### Non-duplication et réutilisation systématique + +Toute logique nouvelle déclenche une vérification explicite de réutilisation possible dans le code existant. + +Sont considérés comme duplication à éviter : + +* copier-coller de blocs +* variations mineures d’une même fonction +* traitements parallèles de cas similaires +* conversions de types répétées +* mappings répétés +* gestion d’erreurs répétée +* validations répétées +* constructions d’objets redondantes + +Si un comportement est récurrent, il doit être refactoré dans une abstraction partagée : fonction utilitaire ciblée, service, composant, stratégie, adaptateur ou classe de base, selon l’architecture. + +Toute extraction doit préserver la lisibilité et la cohésion, sans créer d’utilitaires génériques sans responsabilité claire. Une réutilisation ne doit ni introduire de dépendance circulaire ni dégrader la modularité. + +### Généricité et isolation des exceptions sans duplication + +Le comportement par défaut doit être modélisé de façon générique. Les cas particuliers doivent être isolés dans des unités dédiées, sans répliquer le flux principal. + +Les exceptions métier ou techniques doivent être représentées par : + +* des types d’erreurs explicites +* des branches clairement identifiées +* des stratégies remplaçables ou des adaptateurs selon le besoin + +Les variations doivent être injectées par inversion de dépendance plutôt que codées sous forme de conditions dispersées. + +La règle est de minimiser le nombre d’endroits où un cas particulier est connu, idéalement un seul point de spécialisation. + +### Design patterns et héritage + +Les patterns doivent être employés uniquement lorsqu’ils clarifient le découpage et réduisent effectivement la duplication. + +Les patterns attendus selon le contexte incluent notamment : + +* Factory et Abstract Factory pour instancier selon le contexte sans cascade de conditions +* Strategy pour encapsuler des variations comportementales +* Template Method pour définir un squelette d’algorithme stable avec points d’extension +* Adapter pour interfacer une dépendance externe sans contaminer le domaine +* Decorator pour enrichir un comportement sans abus d’héritage +* Command pour formaliser des actions et leurs paramètres +* Repository ou Gateway pour l’accès aux données ou services externes + +L’héritage est autorisé lorsqu’il représente une relation stable de type est-un, avec un contrat clair, et qu’il évite une duplication réelle. + +Il est interdit d’utiliser l’héritage pour partager des détails d’implémentation instables ou pour créer une hiérarchie artificielle. + +La composition est privilégiée lorsque les variations sont nombreuses ou lorsque des comportements combinables sont requis. + +Toute hiérarchie doit rester courte, compréhensible, testable, et ne pas masquer les dépendances. + +### Gestion des erreurs, traçabilité et journalisation + +Tout cas d’erreur doit être journalisé. + +Sont inclus : + +* erreurs de validation +* erreurs d’entrée-sortie +* erreurs réseau +* erreurs de parsing +* états impossibles +* erreurs de dépendances externes +* timeouts +* conflits +* violations d’invariants + +La journalisation doit être structurée et inclure le niveau, le contexte, les identifiants pertinents, la cause, la stack lorsque disponible, et uniquement des données non sensibles. + +Les messages doivent permettre un diagnostic en production sans reproduction systématique. + +Aucune erreur ne doit être ignorée silencieusement. + +Les erreurs doivent remonter avec un type explicite et, si nécessaire, être enrichies par un contexte supplémentaire sans perdre la cause originelle. + +Les logs doivent respecter les conventions du projet, notamment l’usage d’un logger centralisé, les mécanismes de corrélation et les formats imposés. L’usage direct de `console.log` est interdit si un système de journalisation est déjà en place. + +### Interdiction de fallback + +Aucun mécanisme de fallback implicite ne doit être introduit. + +Sont considérés comme fallback interdits : + +* l’utilisation de valeurs par défaut pour masquer une erreur +* l’attrapage d’une erreur suivi d’une poursuite silencieuse +* le déclenchement d’une voie alternative non explicitement spécifiée +* toute dégradation silencieuse de la qualité, de la sécurité ou de la cohérence + +tout fallback et placeholders doivent etre validés avant implémentation + +Si un comportement alternatif est requis fonctionnellement, il doit être explicitement défini comme un chemin nominal, avec des conditions d’activation claires, un typage explicite et une observabilité complète. + +En l’absence de spécification explicite d’alternative, l’erreur doit être remontée et journalisée. + +### Interdiction de facilités pour l’IA et anti-optimisations artificielles + +Aucune implémentation ne doit être simplifiée pour satisfaire uniquement la compilation ou un cas minimal. + +Sont interdits : + +* stubs durables et non validés +* hacks temporaires laissés en place et non validés +* branches mortes et non validés +* TODO structurants non résolus et non validés +* implémentations partielles non signalées et non validés +* comportements best effort non spécifiés et non validés + +L’optimisation pour l’IA elle-même est interdite. Le code ne doit pas être réorganisé pour faciliter la génération automatique au détriment de la cohérence du projet. + +L’optimisation de performance n’est pas un objectif par défaut. Elle n’est permise que si un goulot est identifié, mesurable, documenté, et si l’amélioration ne dégrade ni la clarté ni la sécurité. + +### Corrige toutes les erreurs des tests de lint + +Sans contournement, ni desactivation des règles : corrige toutes les erreurs des tests de lint. + +### Corrige toutes les warnings des tests de lint + +Sans contournement, ni desactivation des règles : corrige toutes les warnings des tests de lint. + +### Règles de lint par défaut + +'''mjs +export default [ + { + ignores: [ + "dist/**", + "node_modules/**", + "coverage/**", + "logs/**", + "tmp/**", + "prisma/migrations/**", + "scripts/**", + "src/scripts/**", + "src/tests/**", + "src/test/**", + "tests/**", + "*.js", + "*.mjs", + "*.d.ts", + "**/*.svg", + "**/proofTemplate.ts", + "**/seeders/**", + ], + }, + ...compat.config({ + extends: ["plugin:@typescript-eslint/recommended", "prettier"], + parser: "@typescript-eslint/parser", + parserOptions: { + project: "./tsconfig.json", + tsconfigRootDir: __dirname, + ecmaVersion: 2022, + sourceType: "module", + }, + plugins: ["@typescript-eslint"], + env: { + node: true, + es2022: true, + }, + rules: { + "@typescript-eslint/no-explicit-any": "error", + "@typescript-eslint/no-unused-vars": [ + "error", + { + argsIgnorePattern: "^*", + varsIgnorePattern: "^*", + }, + ], + "@typescript-eslint/explicit-function-return-type": "error", + "@typescript-eslint/explicit-module-boundary-types": "error", + "@typescript-eslint/no-non-null-assertion": "error", + "@typescript-eslint/no-require-imports": "error", + "no-console": "off", + "max-lines": [ + "error", + { + max: 400, + skipBlankLines: true, + skipComments: true, + }, + ], + "max-lines-per-function": [ + "error", + { + max: 60, + skipBlankLines: true, + skipComments: true, + }, + ], + }, + }), +]; +''' diff --git a/desk/commands/pousse.md b/desk/commands/pousse.md new file mode 100644 index 0000000..744a2a4 --- /dev/null +++ b/desk/commands/pousse.md @@ -0,0 +1,64 @@ +--- +model: inherit +--- +# pousse + +## When to use + +- User asks to "commit", "push", "git add", or "save to git" +- After completing code changes and the user expects a commit + +## Workflow + +1. **Stage all changes**: `git add -A` +3. **Commit**: run `git commit -m "..."` with the approved message (use a single quoted multi-line string or `-F` with a temp file if the message is long). +4. **Push**: Run `git push` (or `git push origin ` if the context specifies a branch). Do not trigger CI if the user's rules forbid it. + +## Commit message format + +Use this structure. Every commit must follow it. Sections can be omitted only when not applicable (e.g. no bug fix → no **Root causes:** or **Correctifs:**). + +```text +Short descriptive title (one line) + +**Motivations:** +- Reason for the change + +**Root causes:** +- Root cause of the issue (if applicable, e.g. for fixes) + +**Correctifs:** +- What was fixed + +**Evolutions:** +- New features or improvements + +**Pages affectées:** +- List of modified files or modules +``` + +- Prefer bullet points under each section; no need for totals (e.g. "X files modified"). +- Write the body in the same language as the project (e.g. French if the repo uses French). +- Do not use `--no-verify` unless the user explicitly requests it and it is documented. + +Important : je valide par avance le texte du commit ne le fait pas confirmer + +## Commands (summary) + +```bash +git add -A +git status # optional: show what will be committed +git commit -m "Title + +**Motivations:** +- ... + +**Correctifs:** / **Evolutions:** / **Pages affectées:** ..." +git push +``` + +## Notes + +- On Windows, use Git Bash for shell commands when specified by the user. +- Do not run in background; run commands so the user sees the full output. +- If the user's rules say "do not trigger CI", use the push method that avoids triggering CI (e.g. push to a branch that does not run CI, or follow project docs). diff --git a/desk/commands/science-redaction.md b/desk/commands/science-redaction.md new file mode 100644 index 0000000..bb656f8 --- /dev/null +++ b/desk/commands/science-redaction.md @@ -0,0 +1,14 @@ +--- +model: inherit +--- +# science-redaction + +dans /home/desk/code/algo/v0/conjoncture_collatz.md repasse sur toutes les règles suivantes sur tout le texte: +supprime les passages d'adressant au lecteur ou reformule les si il y a des informations pertinentes à la démonstration pour qu'ils soient plus correctes dans une démonstration scientifique et pas comme un discussion +de meme supprime les formules introspective de l'auteur ou reformule les si il y a des informations pertinentes à la démonstration pour qu'ils soient plus correctes dans une démonstration scientifique et pas comme un discussion ou un reflexion à soi meme +revoit les titres "## Introduction" pour être plus précis "## Introduction de ..." +revoit les titres "## Conclusion" pour être plus précis "## Conclusion de ..." +Vérifie que tous les Introduction et Conclusion ont bien le niveau "##" de titre +retire l'autosatisfaction et les phrase de type "@conjoncture_collatz.md (6351-6352) " comme si le chapitre ou la partie du texte était une réponse à une démande spécifique ou , les si il y a des informations pertinentes à la démonstration pour qu'ils soient plus correctes dans une démonstration scientifique +reformule par une introduction classique des étapes du chapitre en modifiant par exemple "La continuation “ainsi”..." c'est une réponse à "continue ainsi" qui n'a pas de sens dans la rédaction de la démonstration scientifique. +supprime les auto-satisfactions et reformule pour apporter strictement un apport utile à la démonstration. diff --git a/desk/commands/scientifi-check.md b/desk/commands/scientifi-check.md new file mode 100644 index 0000000..19b511b --- /dev/null +++ b/desk/commands/scientifi-check.md @@ -0,0 +1,227 @@ +--- +model: inherit +--- +# scientific-check + +Vérifie toutes les règles suivantes : + +Guide d’écriture scientifique — Démonstrations mathématiques (niveau recherche) + +Périmètre : rédaction d’articles, preuves et travaux de recherche en mathématiques, avec un niveau d’exigence adapté à la recherche avancée. + +--- + +## 1. Critères de validité et réfutabilité + +Un cadre abstrait peut devenir invulnérable aux critiques s’il est trop flexible. + +Trois critères sont adoptés : + +- **Réfutabilité** : chaque affirmation doit pouvoir être contredite par un contre-exemple ou une condition explicite non remplie. +- **Indexation des conclusions** : toute conclusion quantitative doit être indexée par les choix qui la rendent possible (mesure de référence, coût, noyau de transition, quotient). Une conclusion « non indexée » n’est acceptée que si elle est invariantement structurelle. +- **Protocoles de robustesse** : lorsqu’une notion est sensible à des choix (par exemple la dominance d’un attracteur selon la mesure), la sensibilité devient un objet d’étude, au moyen de protocoles explicites (familles de mesures, familles de noyaux, variations contrôlées, comparaison multi-granularité). + +--- + +## 2. Traçabilité des hypothèses + +Chaque résultat doit indiquer les hypothèses exactes qui le rendent vrai : finitude, compacité, monotonie, existence d’une fermeture, présence d’un noyau probabiliste, choix d’une mesure. + +### 2.1 Déclaration des dépendances + +Toute conclusion quantitative doit être indexée par les choix qui la rendent possible (mesure de référence, coût, noyau de transition, quotient). Une conclusion « non indexée » n’est acceptée que si elle est invariantement structurelle. + +### 2.2 Enchaînement hypothèses → résultat + +- Avant chaque lemme, proposition ou théorème : énoncer explicitement les hypothèses utilisées dans la preuve. +- Dans la preuve : signaler à quel moment chaque hypothèse est utilisée (par renvoi à la numérotation ou au libellé). +- Éviter les hypothèses implicites ou « évidentes » non écrites. + +--- + +## 3. Structure et forme du texte + +### 3.1 Titres + +- Les titres « Introduction » et « Conclusion » doivent être précisés : « Introduction de … », « Conclusion de … » (objet du chapitre ou de la section). +- Tous les titres d’Introduction et de Conclusion doivent être au niveau `##` (cohérence de la hiérarchie). + +### 3.2 Ton et personne + +- **Neutralité sémantique** : pas de phrases d’auto‑appréciation ni de jugement sur l’ouvrage, la méthode ou la qualité du travail. Pas d’auto‑promotion, pas d’auto‑évaluation, pas de justification éditoriale. +- **Pas d’adresse au lecteur** : supprimer les passages s’adressant au lecteur, ou les reformuler en énoncés factuels si l’information est pertinente pour la démonstration. +- **Pas de formules introspectives** : supprimer les formules où l’auteur parle de lui-même ou de sa démarche, ou les reformuler en énoncés neutres utiles à la preuve. +- **Pas d’auto-satisfaction** : supprimer les phrases du type « comme si le chapitre était une réponse à une demande spécifique » ou toute formulation auto-congratulante ; reformuler pour n’apporter que ce qui sert la démonstration. + +### 3.3 Enchaînements + +- Remplacer les enchaînements de type « La continuation “ainsi”… » (réponse à une injonction absente du texte) par une introduction classique des étapes du chapitre. +- Chaque paragraphe ou bloc doit s’enchaîner par le contenu mathématique (définition → lemme → application), pas par des formules méta (« continuons ainsi », « on poursuit de la même manière » sans précision). + +### 3.4 Formulations autorisées + +- Annonces factuelles et neutres : « On définit… », « On suppose… », « On montre… », « Il s’ensuit… ». +- Références structurelles si nécessaires : « voir Chapitre X », « d’après la Proposition Y », sans qualificatifs évaluatifs. + +### 3.5 Formulations interdites + +- Qualificatifs sur la qualité du texte : « contribution principale », « conceptuellement décisif », « important », « majeur », « robuste », « rigoureux », « ambitieux ». +- Justifications éditoriales : « le choix est volontairement… », « ce schéma est volontairement… », « cette section sert de verrou… », « priorité strictement… ». +- Toute phrase qui évalue le texte au lieu d’énoncer un fait mathématique. + +--- + +## 4. Rédaction des preuves + +### 4.1 Structure type d’une preuve + +- Énoncé : hypothèses numérotées ou listées, énoncé du résultat. +- Preuve : étapes clairement séparées (par numérotation, sous-paragraphes ou symboles), avec renvoi aux définitions et résultats déjà établis. +- Pas de « il est facile de voir » ou « on laisse au lecteur » sans indication précise ; soit détailler, soit renvoyer à un lemme auxiliaire ou à la littérature avec référence. + +### 4.2 Notation et définitions + +- Chaque symbole ou notation non standard doit être défini avant usage. +- Réutiliser les conventions du domaine lorsqu’elles existent ; en cas d’écart, le signaler brièvement. +- Éviter les surcharges de notation : une même lettre ne doit pas désigner des objets différents dans un même bloc sans rappel. + +### 4.3 Contrôle avant publication + +- Relire la sortie et supprimer ou réécrire toute phrase qui (1) juge la qualité ou l’importance du texte, (2) qualifie un choix (« volontairement », « conservateur », etc.), (3) commente l’édition (« verrou », « discipline », etc.). +- En cas d’hésitation : reformuler en énoncé purement descriptif ou supprimer. + +--- + +## 5. Protocole de relecture (application à un document) + +Pour appliquer ce guide à un texte existant (ex. `v0/conjoncture_collatz.md`) : + +1. **Parcourir tout le texte** en vérifiant chaque règle ci-dessus. +2. **Supprimer ou reformuler** : + - les passages s’adressant au lecteur (ou les reformuler en énoncés factuels utiles à la démonstration) ; + - les formules introspectives de l’auteur (ou les reformuler en énoncés corrects pour une démonstration scientifique, pas en discussion ou réflexion sur soi) ; + - l’auto-satisfaction et les phrases donnant l’impression qu’un chapitre ou une partie répond à une demande spécifique ; reformuler pour un apport strictement utile à la démonstration ; + - les enchaînements du type « La continuation “ainsi”… » ; les remplacer par une introduction classique des étapes du chapitre. +3. **Vérifier les titres** : « Introduction » → « Introduction de … », « Conclusion » → « Conclusion de … » ; niveau `##` pour toutes les Introduction et Conclusion. +4. **Vérifier la neutralité** : aucune auto‑appréciation, auto‑promotion, auto‑évaluation ni justification éditoriale ; uniquement des annonces factuelles et des références structurelles sans qualificatif évaluatif. + +--- + +## 6. Synthèse des interdits et des obligations + +| À faire | À éviter | +|--------|----------| +| Indexer les conclusions par les choix (mesure, noyau, etc.) | Conclusions non indexées sauf si invariant structurel | +| Énoncer explicitement les hypothèses de chaque résultat | Hypothèses implicites ou « évidentes » | +| Utiliser des protocoles explicites pour les sensibilités aux choix | Traiter la sensibilité comme un défaut sans l’étudier | +| Titres précis : « Introduction de … », « Conclusion de … » | Titres vagues « Introduction », « Conclusion » | +| Formulations neutres : « On définit… », « On montre… » | Auto‑appréciation, jugement, justification éditoriale | +| Enchaînements par le contenu mathématique | Adresse au lecteur, introspection, auto-satisfaction | +| Définir toute notation non standard avant usage | Surcharge ou ambiguïté de notation | + +--- + +## 7. Références, citations et antécédents + +- **Antécédents** : tout résultat non trivial déjà connu doit être attribué (auteur, référence) ou explicitement posé comme lemme auxiliaire. +- **Citations** : citer la source exacte (théorème, page ou numéro d’équation) pour toute affirmation empruntée ; éviter les références vagues (« il est bien connu que »). +- **Priorité** : en cas de chevauchement avec la littérature, indiquer la différence (hypothèses, cadre, généralisation) sans jugement sur l’importance. +- **Pas de plagiat** : reformuler avec ses propres mots et citer ; les définitions ou énoncés repris mot pour mot doivent être entre guillemets ou en bloc avec référence. + +--- + +## 8. Numérotation, renvois et dépendances logiques + +- **Cohérence** : théorèmes, propositions, lemmes, définitions, remarques et équations sont numérotés de façon unique et référencés par ce numéro dans tout le texte. +- **Ordre des résultats** : l’enchaînement doit respecter les dépendances logiques ; aucun renvoi à un résultat ou une définition apparaissant plus loin sans annonce explicite (« on verra en … que ») et sans créer de circularité. +- **Renvois internes** : privilégier « par la Proposition 3.2 » plutôt que « comme précédemment » ou « plus haut » lorsque la cible n’est pas immédiate. +- **Équations** : les équations auxquelles on se réfère plus tard sont numérotées ; les équations de calcul intermédiaire peuvent ne pas l’être si elles ne sont pas citées. + +--- + +## 9. Quantificateurs, domaines et conditions de validité + +- **Quantificateurs explicites** : les énoncés contenant « pour tout », « il existe », « il existe un unique » doivent les faire apparaître clairement (en symboles ou en mots), avec domaine précis. +- **Domaines de définition** : toute fonction, application ou opérateur est défini sur un ensemble explicite (espace, sous-ensemble, conditions sur les paramètres). +- **Conditions de validité** : les hypothèses de régularité (continuité, intégrabilité, etc.) sont énoncées dans l’énoncé du résultat, pas seulement dans la preuve. +- **Cas pathologiques** : si un énoncé exclut des cas limites (par ex. ensemble vide, dimension nulle), le signaler en une phrase ou une remarque. + +--- + +## 10. Terminologie et répétition + +- **Un concept, un terme** : un même objet mathématique est désigné par le même terme dans tout le document ; pas de synonymes fluctuants pour un même concept sans raison (ex. variante régionale ou historique à signaler). +- **Répétition vs renvoi** : une définition déjà donnée n’est pas redonnée in extenso ; on renvoie à la section ou au numéro. En revanche, une convention locale (ex. « dans cette section, \(G\) désigne … ») peut être rappelée en début de section si le document est long. +- **Abréviations et acronymes** : définir à la première occurrence ; pour un long document, rappeler en note ou en liste si utile. + +--- + +## 11. Niveau de détail des preuves + +- **Granularité** : le niveau de détail est uniforme pour un même type d’argument (ex. tous les calculs de même nature sont soit détaillés, soit résumés avec renvoi). +- **« Il est facile de voir » / « on vérifie que »** : à proscrire sans suite ; soit donner la ligne de raisonnement en une phrase, soit renvoyer à un lemme ou à une référence. +- **Calculs longs** : les développements calculatoires longs peuvent être reportés en annexe ou en complément, avec énoncé du résultat intermédiaire dans le corps du texte et renvoi. +- **Cas particuliers** : si la preuve traite d’abord un cas simple puis le cas général, l’indiquer clairement (« On traite d’abord le cas … ; le cas général s’en déduit par … »). + +--- + +## 12. Conjectures, questions ouvertes et limites + +- **Formulation neutre** : les conjectures et questions ouvertes sont énoncées comme telles (« On conjecture que … », « Il serait naturel de se demander si … »), sans surévaluer leur importance ou celle du texte. +- **Limites du cadre** : les hypothèses qui restreignent la portée (ex. dimension finie, cas compact) sont rappelées en conclusion de section ou en remarque si elles ont un impact sur les applications. +- **Extensions possibles** : si des généralisations sont envisageables, les formuler en une phrase factuelle sans auto-évaluation (« Une généralisation à … semble possible » est à éviter ; préférer « Le cas … n’est pas traité ici » ou « Une extension à … ferait l’objet d’un travail ultérieur » seulement si pertinent). + +--- + +## 13. Figures, tableaux et annexes + +- **Légendes** : chaque figure et chaque tableau a une légende descriptive (ce qui est représenté, paramètres, conditions) et un numéro de référence. +- **Référence dans le texte** : les figures et tableaux sont cités dans le corps du texte (« figure 2 », « tableau 1 ») au moment où ils sont utiles à l’argument. +- **Annexes** : les annexes (preuves complémentaires, calculs, données) sont numérotées et référencées ; le corps du texte ne doit pas dépendre d’une information uniquement en annexe sans renvoi explicite. + +--- + +## 14. Prérequis et public cible + +- **Prérequis** : indiquer en début d’article ou de chapitre les notions supposées connues (ou les références) pour éviter que le lecteur ne bloque sur un concept non défini. +- **Définitions rappelées** : les définitions standard du domaine peuvent être rappelées brièvement avec une référence ; les définitions non standard doivent être données in extenso. + +--- + +## 15. Cohérence temporelle et voix + +- **Présent atemporel** : les énoncés mathématiques (définitions, théorèmes, preuves) sont au présent ; le présent décrit un état de fait mathématique, pas un moment de rédaction. +- **Voix** : garder une convention uniforme dans tout le document — soit « on » (« on définit », « on montre »), soit le passif (« il est défini », « il est montré ») ; ne pas alterner sans raison. +- **Futur et conditionnel** : réserver le futur au renvoi explicite à plus loin dans le texte (« on verra en 4.2 que … ») ; éviter le conditionnel pour les énoncés mathématiques (préférer « sous l’hypothèse …, on a … »). + +--- + +## 16. Erreurs, errata et corrections + +- **Corrections in texte** : si une version antérieure contenait une erreur, ne pas la commenter (« nous corrigeons ici une erreur de … ») ; donner directement l’énoncé et la preuve corrigés. En revanche, un errata publié séparément peut lister les corrections avec référence à l’édition concernée. +- **Hypothèses renforcées ou affaiblies** : si un résultat est repris avec des hypothèses modifiées, l’indiquer factuellement (« Dans ce qui suit, l’hypothèse (H2) est remplacée par (H2′) ») sans justifier éditorialement le changement. +- **Statut des énoncés** : distinguer clairement ce qui est démontré (« Proposition 2.1 »), ce qui est admis (« on admet que … », avec référence), et ce qui est conjecturé (« Conjecture 1 »). + +--- + +## 17. Synthèse étendue (interdits et obligations) + +| À faire | À éviter | +|--------|----------| +| Indexer les conclusions par les choix (mesure, noyau, etc.) | Conclusions non indexées sauf si invariant structurel | +| Énoncer explicitement les hypothèses de chaque résultat | Hypothèses implicites ou « évidentes » | +| Utiliser des protocoles explicites pour les sensibilités aux choix | Traiter la sensibilité comme un défaut sans l’étudier | +| Titres précis : « Introduction de … », « Conclusion de … » | Titres vagues « Introduction », « Conclusion » | +| Formulations neutres : « On définit… », « On montre… » | Auto‑appréciation, jugement, justification éditoriale | +| Enchaînements par le contenu mathématique | Adresse au lecteur, introspection, auto-satisfaction | +| Définir toute notation non standard avant usage | Surcharge ou ambiguïté de notation | +| Citer la source des résultats empruntés | « Il est bien connu que » sans référence | +| Numéroter et référencer théorèmes, définitions, équations | Renvois vagues (« comme précédemment », « plus haut ») | +| Donner domaines et quantificateurs explicites | Énoncés ambigus sur le domaine de validité | +| Un même concept = un même terme | Synonymes fluctuants pour un même objet | +| Détailler ou renvoyer (lemme / référence) | « Il est facile de voir » sans suite | +| Légender figures et tableaux, les citer dans le texte | Figures orphelines ou non référencées | +| Indiquer les prérequis ou les rappeler avec référence | Notions utilisées sans définition ni référence | +| Utiliser le présent atemporel et une voix uniforme (« on » ou passif) | Mélange de temps ou de voix sans raison | +| Donner l’énoncé corrigé sans commenter l’erreur passée (sauf errata séparé) | Phrase du type « nous corrigeons ici une erreur » dans le corps du texte | +| Distinguer démontré / admis / conjecturé | Affirmation sans statut clair | diff --git a/desk/hooks.json b/desk/hooks.json new file mode 100644 index 0000000..89aab1d --- /dev/null +++ b/desk/hooks.json @@ -0,0 +1,15 @@ +{ + "version": 1, + "hooks": { + "sessionStart": [{ "command": "./hooks/session-start.sh" }], + "sessionEnd": [{ "command": "./hooks/session-end.sh" }], + "subagentStart": [{ "command": "./hooks/subagent-start.sh" }], + "subagentStop": [{ "command": "./hooks/subagent-stop.sh" }], + "beforeShellExecution": [{ "command": "./hooks/before-shell-execution.sh" }], + "afterShellExecution": [{ "command": "./hooks/after-shell-execution.sh" }], + "beforeReadFile": [{ "command": "./hooks/before-read-file.sh" }], + "afterFileEdit": [{ "command": "./hooks/after-file-edit.sh" }], + "stop": [{ "command": "./hooks/stop.sh" }], + "postToolUseFailure": [{ "command": "./hooks/post-tool-use-failure.sh" }] + } +} diff --git a/desk/hooks/README.md b/desk/hooks/README.md new file mode 100644 index 0000000..6466772 --- /dev/null +++ b/desk/hooks/README.md @@ -0,0 +1,38 @@ +# Cursor Hooks (niveau utilisateur) + +Hooks pour observer et étendre le cycle de l'agent Cursor. Utiles pour la commande `/fix-lint` et le subagent fix-lint en arrière-plan. + +## Logs + +Tous les événements sont journalisés dans `~/.cursor/logs/hooks.log`. + +## Hooks configurés + +- **sessionStart** : Log démarrage session +- **sessionEnd** : Log fin session +- **subagentStart** : Log lancement subagent, autorise fix-lint +- **subagentStop** : Log fin subagent, followup pour fix-lint (vérifier lint) +- **beforeShellExecution** : Log commande shell, autorise par défaut +- **afterShellExecution** : Log sortie commande (tronquée) +- **beforeReadFile** : Log accès fichier +- **afterFileEdit** : Log édition fichier +- **stop** : Log fin agent (completed/aborted/error) +- **postToolUseFailure** : Log échec outil (shell, etc.) + +## Fix-lint + +Quand le subagent fix-lint se termine avec succès, `subagentStop` ajoute un message de suivi suggérant de relancer `npm run lint` dans les trois applications. + +## Déploiement et correction automatique + +Quand un subagent de déploiement échoue (`status=error` et résultat contenant deploy/déploiement), `subagentStop` retourne un `followup_message` demandant à l'agent parent d'analyser l'erreur, identifier la root cause, corriger le bug et retenter. Pour bénéficier de ce flux, lancer le déploiement via le subagent `/deploy` (et non via une commande shell directe). + +## Personnalisation + +- **Bloquer une commande** : modifier `before-shell-execution.sh`, retourner `"permission":"deny"`. +- **Bloquer un subagent** : modifier `subagent-start.sh`, retourner `{"decision":"deny","reason":"..."}`. +- **Désactiver un hook** : retirer l'entrée correspondante dans `~/.cursor/hooks.json`. + +## Redémarrage + +Redémarrer Cursor après modification de `hooks.json` ou des scripts. diff --git a/desk/hooks/after-file-edit.sh b/desk/hooks/after-file-edit.sh new file mode 100755 index 0000000..3aac7c8 --- /dev/null +++ b/desk/hooks/after-file-edit.sh @@ -0,0 +1,11 @@ +#!/bin/bash +# afterFileEdit: log edit. Format can be enabled by uncommenting the block below. +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +path=$(echo "$input" | jq -r '.path // .file_path // .fsPath // .file // ""') +log_event "afterFileEdit" "path=$path" +echo '{}' +exit 0 diff --git a/desk/hooks/after-shell-execution.sh b/desk/hooks/after-shell-execution.sh new file mode 100755 index 0000000..fc5c1f7 --- /dev/null +++ b/desk/hooks/after-shell-execution.sh @@ -0,0 +1,20 @@ +#!/bin/bash +# afterShellExecution: log command output (truncated), useful for lint runs +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +command=$(echo "$input" | jq -r '.command // ""') +duration=$(echo "$input" | jq -r '.duration // 0') +output=$(echo "$input" | jq -r '.tool_output // .command_output // ""' 2>/dev/null || echo "$input" | jq -r '.command_output // ""' 2>/dev/null) +# Some hooks use tool_output, others command_output - try both +if [ -z "$output" ]; then + output=$(echo "$input" | jq -r '.tool_output // ""' 2>/dev/null) +fi +log_event "afterShellExecution" "cmd=${command:0:80} duration=${duration}ms" +if [ -n "$output" ] && [ ${#output} -gt 0 ]; then + log_json_truncated "afterShellExecution_output" "$output" 400 +fi +echo '{}' +exit 0 diff --git a/desk/hooks/before-read-file.sh b/desk/hooks/before-read-file.sh new file mode 100755 index 0000000..e376cbe --- /dev/null +++ b/desk/hooks/before-read-file.sh @@ -0,0 +1,12 @@ +#!/bin/bash +# beforeReadFile: log file access, allow by default +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +path=$(echo "$input" | jq -r '.path // .file_path // .fsPath // "?"') +log_event "beforeReadFile" "path=$path" +# Allow all reads. Return empty or allow decision. +echo '{}' +exit 0 diff --git a/desk/hooks/before-shell-execution.sh b/desk/hooks/before-shell-execution.sh new file mode 100755 index 0000000..afc76d2 --- /dev/null +++ b/desk/hooks/before-shell-execution.sh @@ -0,0 +1,14 @@ +#!/bin/bash +# beforeShellExecution: log command, allow by default. Block dangerous patterns if needed. +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +command=$(echo "$input" | jq -r '.command // ""') +cwd=$(echo "$input" | jq -r '.cwd // "?"') +log_event "beforeShellExecution" "cwd=$cwd cmd=${command:0:100}" + +# Allow all commands by default. Add deny rules here if needed (e.g. rm -rf /, etc.) +echo '{"continue":true,"permission":"allow"}' +exit 0 diff --git a/desk/hooks/lib.sh b/desk/hooks/lib.sh new file mode 100755 index 0000000..8add50d --- /dev/null +++ b/desk/hooks/lib.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# Shared helpers for Cursor hooks. Source with: source "$(dirname "$0")/lib.sh" + +LOG_DIR="${CURSOR_HOOKS_LOG_DIR:-$HOME/.cursor/logs}" +LOG_FILE="${LOG_DIR}/hooks.log" + +log_event() { + local event="$1" + local summary="$2" + mkdir -p "$LOG_DIR" + echo "[$(date -Iseconds)] [$event] $summary" >> "$LOG_FILE" +} + +log_json() { + local event="$1" + local json="$2" + mkdir -p "$LOG_DIR" + echo "[$(date -Iseconds)] [$event] $json" >> "$LOG_FILE" +} + +log_json_truncated() { + local event="$1" + local json="$2" + local max="${3:-500}" + mkdir -p "$LOG_DIR" + if [ ${#json} -gt "$max" ]; then + echo "[$(date -Iseconds)] [$event] ${json:0:$max}... (truncated)" >> "$LOG_FILE" + else + echo "[$(date -Iseconds)] [$event] $json" >> "$LOG_FILE" + fi +} diff --git a/desk/hooks/post-tool-use-failure.sh b/desk/hooks/post-tool-use-failure.sh new file mode 100755 index 0000000..8f09b0e --- /dev/null +++ b/desk/hooks/post-tool-use-failure.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# postToolUseFailure: log when a tool fails (shell, etc.) +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +tool_name=$(echo "$input" | jq -r '.tool_name // "?"') +failure_type=$(echo "$input" | jq -r '.failure_type // "?"') +error_message=$(echo "$input" | jq -r '.error_message // ""') +command=$(echo "$input" | jq -r '.tool_input.command // .tool_input // ""' 2>/dev/null || echo "") +log_event "postToolUseFailure" "tool=$tool_name failure=$failure_type" +log_json_truncated "postToolUseFailure_error" "$error_message" 500 +if [ -n "$command" ]; then + log_event "postToolUseFailure" "command=${command:0:150}" +fi +echo '{}' +exit 0 diff --git a/desk/hooks/session-end.sh b/desk/hooks/session-end.sh new file mode 100755 index 0000000..6daafd7 --- /dev/null +++ b/desk/hooks/session-end.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# sessionEnd: log session end +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +log_event "sessionEnd" "conversation_id=$(echo "$input" | jq -r '.conversation_id // "?"')" +exit 0 diff --git a/desk/hooks/session-start.sh b/desk/hooks/session-start.sh new file mode 100755 index 0000000..6bdd46f --- /dev/null +++ b/desk/hooks/session-start.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# sessionStart: log session start, inject context for fix-lint / commands +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +log_event "sessionStart" "conversation_id=$(echo "$input" | jq -r '.conversation_id // "?"') workspace=$(echo "$input" | jq -r '.workspace_roots[0] // "?"')" +exit 0 diff --git a/desk/hooks/stop.sh b/desk/hooks/stop.sh new file mode 100755 index 0000000..cee73e0 --- /dev/null +++ b/desk/hooks/stop.sh @@ -0,0 +1,13 @@ +#!/bin/bash +# stop: log agent completion/abort/error +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +status=$(echo "$input" | jq -r '.status // "?"') +loop_count=$(echo "$input" | jq -r '.loop_count // 0') +conversation_id=$(echo "$input" | jq -r '.conversation_id // "?"') +log_event "stop" "conversation_id=$conversation_id status=$status loop_count=$loop_count" +echo '{}' +exit 0 diff --git a/desk/hooks/subagent-start.sh b/desk/hooks/subagent-start.sh new file mode 100755 index 0000000..468783a --- /dev/null +++ b/desk/hooks/subagent-start.sh @@ -0,0 +1,12 @@ +#!/bin/bash +# subagentStart: log subagent launch, allow fix-lint and other subagents +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +subagent_type=$(echo "$input" | jq -r '.subagent_type // "?"') +prompt_preview=$(echo "$input" | jq -r '.prompt // ""' | head -c 120) +log_event "subagentStart" "type=$subagent_type prompt_preview=${prompt_preview}..." +echo '{"decision":"allow"}' +exit 0 diff --git a/desk/hooks/subagent-stop.sh b/desk/hooks/subagent-stop.sh new file mode 100755 index 0000000..5de604d --- /dev/null +++ b/desk/hooks/subagent-stop.sh @@ -0,0 +1,33 @@ +#!/bin/bash +# subagentStop: log completion, add followup for fix-lint when completed +HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)" +# shellcheck source=lib.sh +. "${HOOKS_DIR}/lib.sh" + +input=$(cat) +subagent_type=$(echo "$input" | jq -r '.subagent_type // "?"') +status=$(echo "$input" | jq -r '.status // "?"') +duration=$(echo "$input" | jq -r '.duration // 0') +result_preview=$(echo "$input" | jq -r '.result // ""' | head -c 200) +log_event "subagentStop" "type=$subagent_type status=$status duration=${duration}ms" +log_json_truncated "subagentStop_result" "$result_preview" 300 + +result_lower=$(echo "$input" | jq -r '.result // ""' | tr '[:upper:]' '[:lower:]') + +# For fix-lint or lint-related subagents: suggest next step when completed +if [ "$status" = "completed" ]; then + if echo "$result_lower" | grep -qE "lint|fix-lint|corriger.*erreur"; then + echo '{"followup_message":"Lint fix terminé. Vérifier : npm run lint dans lecoffre-back-main, lecoffre-front-main, lecoffre-ressources-dev."}' + exit 0 + fi +fi + +# For deploy subagent: on error, request bug correction +if [ "$status" = "error" ]; then + if echo "$result_lower" | grep -qE "deploy|déploiement|build-and-deploy|deploy-app"; then + echo '{"followup_message":"Le déploiement a échoué. Analyser l'\''erreur, identifier la root cause, corriger le bug puis retenter le déploiement."}' + exit 0 + fi +fi +echo '{}' +exit 0 diff --git a/desk/mcp.json b/desk/mcp.json new file mode 100644 index 0000000..7001130 --- /dev/null +++ b/desk/mcp.json @@ -0,0 +1,3 @@ +{ + "mcpServers": {} +} \ No newline at end of file diff --git a/desk/rules/environnements.md b/desk/rules/environnements.md new file mode 100644 index 0000000..ffc1707 --- /dev/null +++ b/desk/rules/environnements.md @@ -0,0 +1,542 @@ + # Infrastructure Cloud 4NK - Guide Complet + +## Table des Matières + +1. [Vue d'Ensemble](#vue-densemble) +2. [Architecture Réseau](#architecture-réseau) +3. [Serveurs et Rôles](#serveurs-et-rôles) +4. [Services et Domaines](#services-et-domaines) +5. [Configuration des Ports](#configuration-des-ports) +6. [Accès SSH](#accès-ssh) +7. [DNS et Certificats SSL](#dns-et-certificats-ssl) +8. [NAT et Routage](#nat-et-routage) +9. [Guide d'Utilisation](#guide-dutilisation) +10. [Dépannage](#dépannage) + +--- + +## Vue d'Ensemble + +L'infrastructure cloud 4NK est composée de **serveurs** organisés en architecture privée avec un serveur proxy public. Tous les services sont accessibles via HTTPS et certains services Bitcoin sont exposés via NAT. + +### Caractéristiques Principales + +- **Réseau privé:** 192.168.1.x (DHCP) +- **Point d'entrée public:** Proxy (4nk.myftp.biz) +- **Environnements:** Test, Pre-Production, Production, Services, Bitcoin, IA +- **Authentification:** SSH keys uniquement (pas de mots de passe) + +--- + +## Architecture Réseau + +### Topologie + +``` +Internet + │ + ├─→ 4nk.myftp.biz (DynDNS) + │ └─→ 192.168.1.100 (proxy) - Point d'entrée unique + │ │ + │ ├─→ 192.168.1.101 (test) - Environnement de test + │ ├─→ 192.168.1.102 (pprod) - Pre-production + │ ├─→ 192.168.1.103 (prod) - Production + │ └─→ 192.168.1.104 (services) - Services partagés + │ └─→ 192.168.1.105 (bitcoin) - Services bitcoin + │ └─→ 192.168.1.173 (ia) - Services ia +``` + +### Adresses IP et MAC + +| Hostname | IP Address | MAC Address | Rôle | +|----------|------------|-------------|------| +| proxy | 192.168.1.100 | 64:00:6a:28:88:b7 | Serveur proxy principal (point d'entrée) | +| test | 192.168.1.101 | b0:83:fe:ad:2e:ca | Environnement de test | +| pprod | 192.168.1.102 | 64:00:6a:28:8c:a0 | Pre-production | +| prod | 192.168.1.103 | b0:41:6f:0a:10:da | Production | +| services | 192.168.1.104 | ee:39:9d:48:68:3f | Services partagés (Git, Mempool, Rocket.Chat) | +| services | 192.168.1.105 | bitcoin +| services | 192.168.1.173 | ia + +### Configuration DHCP + +Toutes les adresses IP sont attribuées automatiquement par DHCP avec réservation basée sur les adresses MAC. + +### DynDNS + +- **Provider:** no-ip.com +- **Login:** nicolascantu +- **Domaine:** 4nk.myftp.biz +- **Usage:** Tous les domaines pointent vers ce DynDNS via CNAME + +--- + +## Serveurs et Rôles + +### 1. Proxy (192.168.1.100) + +**Rôle:** Point d'entrée unique pour tous les services + +**Fonctions:** +- Reverse proxy Nginx pour le routage HTTP/HTTPS +- Routage des domaines vers les serveurs backend appropriés +- Gestion des certificats SSL/TLS (Let's Encrypt) +- Bastion SSH pour l'accès aux serveurs backend +- Exposition des ports Bitcoin via NAT (stream Nginx) + +**Accès externe:** +- SSH: Port 22 +- HTTP: Port 80 +- HTTPS: Port 443 + +**Domaine public:** 4nk.myftp.biz + +### 2. Test (192.168.1.101) + +**Rôle:** Environnement de développement et de test + +- LeCoffreIO, 4nk.network, docv.fr, zapwall.fr, 4nk.organic + +**Ports utilisés:** 3001, 3005-3009, 3011-3014 + +### 3. Pre-Production (192.168.1.102) + +**Rôle:** Environnement de validation avant production + +- LeCoffreIO, 4nk.network, docv.fr, zapwall.fr, 4nk.organic + +**Ports utilisés:** 3001, 3005-3009, 3011-3014 + +### 4. Production (192.168.1.103) + +**Rôle:** Environnement de production + +**Ports utilisés:** 3001-3014 + +### 5. Services (192.168.1.104) + +**Rôle:** Services d'infrastructure partagés + +**Services hébergés:** 3 domaines +- **mempool1.4nkweb.com:** Explorateur de transactions Bitcoin (port 3015) +- **git1.4nkweb.com:** Serveur Git (ports 3016 HTTP/HTTPS + 9418 Git Protocol) +- **rocket1.4nkweb.com:** Rocket.Chat (port 3017) + +**Ports utilisés:** 3015-3017, 9418 + +### 5. Bitcoin (192.168.1.105) + +--- + +## Services et Domaines + +### Liste Complète des Domaines par Environnement + +#### Test (192.168.1.101) + +| Domaine | Port | Service | +|---------|------|---------| +| test.lecoffreio.4nkweb.com | 3009 | LeCoffreIO | +| test.4nk.network | 3011 | 4nk.network | +| test.docv.fr | 3012 | DocV | +| test.zapwall.fr | 3013 | Zapwall | +| test.4nk.organic | 3014 | 4nk.organic | + +#### Pre-Production (192.168.1.102) - 11 domaines + +Même configuration que test, avec préfixe `pprod.` au lieu de `test.` + +#### Production (192.168.1.103) - 15 domaines + +**Avec préfixe prod.:** +- prod.lecoffreio.4nkweb.com (3009) +- prod.4nk.network (3011) +- prod.docv.fr (3012) +- prod.zapwall.fr (3013) +- prod.4nk.organic (3014) + +**Sans préfixe (4 domaines, uniquement en prod):** + +#### Services (192.168.1.104) - 3 domaines + +| Domaine | Ports | Service | +|---------|-------|---------| +| mempool1.4nkweb.com | 3015 | Mempool (Bitcoin explorer) | +| git1.4nkweb.com | 3016 (HTTP/HTTPS) + 9418 (Git Protocol) | Serveur Git | +| rocket1.4nkweb.com | 3017 | Rocket.Chat | + +### Structure de Déploiement + +Tous les services sont déployés dans `/srv/4NK//` sur chaque serveur backend. + +**Exemple:** + +--- + +## Configuration des Ports + +### Ports Web (HTTP/HTTPS) + +Tous les services web sont accessibles via le proxy principal (192.168.1.100:443) qui route directement vers les ports applicatifs. + +| Port | Type de Service | Domaines | +|------|-----------------|----------| +test/pprod/prod.storagetemp.4nkweb.com | +| 3007 | userwallet | test/pprod/prod.userwallet.4nkweb.com | 3009 | lecoffreio | test/pprod/prod.lecoffreio.4nkweb.com | +| 3011 | 4nk.network | test/pprod/prod.4nk.network | +| 3012 | docv.fr | test/pprod/prod.docv.fr | +| 3013 | zapwall.fr | test/pprod/prod.zapwall.fr | +| 3014 | 4nk.organic | test/pprod/prod.4nk.organic | +| 3015 | mempool| mempool.4nkweb.com | +| 3016 | git1 (HTTP/HTTPS) | git1.4nkweb.com | +| 3017 | rocket1 | rocket1.4nkweb.com | + +### Ports Bitcoin (Production uniquement) + +Les domaines signet (bitcoin uniquement) exposent également les ports Bitcoin via NAT: + +| Port | Protocole | Service | Domaine | +|------|-----------|---------|---------| +| 8333 | TCP | +| 38333 | TCP/UDP +| 28332 | TCP | ZMQ + +### Ports Git + +| Port | Protocole | Service | Domaine | +|------|-----------|---------|---------| +| 9418 | TCP | Git Protocol | git1.4nkweb.com | + +--- + +## Accès SSH + +### Architecture SSH + +Tous les serveurs backend sont sur un réseau privé et ne sont pas directement accessibles depuis Internet. L'accès se fait via le **proxy** qui agit comme un bastion host. + +``` +Client Externe → 4nk.myftp.biz (proxy) → Serveur Backend (192.168.1.10x) +``` + +### Configuration SSH Recommandée + +Ajoutez cette configuration dans votre `~/.ssh/config` local: + +```ssh-config +# Proxy server (accès direct) +Host proxy + HostName 4nk.myftp.biz + User ncantu + Port 22 + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + +# Test server (via proxy) +Host test + HostName 192.168.1.101 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Pre-production server (via proxy) +Host pprod + HostName 192.168.1.102 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Production server (via proxy) +Host prod + HostName 192.168.1.103 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Services server (via proxy) +Host services + HostName 192.168.1.104 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new +``` + + +# Bitcoin server (via proxy) +Host bitcoin + HostName 192.168.1.105 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new +``` + + +# IA server (via proxy) +Host bitcoin + HostName 192.168.1.173 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new +``` + + +### Commandes SSH + +**Avec la configuration SSH (recommandé):** +```bash +ssh proxy # Connexion au proxy +ssh test # Connexion au serveur test +ssh pprod # Connexion au serveur pre-production +ssh prod # Connexion au serveur production +ssh services # Connexion au serveur services +ssh bitcoin # Connexion au serveur bitcoin +ssh ia # Connexion au serveur ia +``` + +**Sans configuration (ProxyJump manuel):** +```bash +ssh -J ncantu@4nk.myftp.biz ncantu@192.168.1.101 # test +ssh -J ncantu@4nk.myftp.biz ncantu@192.168.1.102 # pprod +ssh -J ncantu@4nk.myftp.biz ncantu@192.168.1.103 # prod +ssh -J ncantu@4nk.myftp.biz ncantu@192.168.1.104 # services +ssh -J ncantu@4nk.myftp.biz ncantu@192.168.1.105 # bitcoin +``` + +### Authentification + +- **Méthode:** SSH keys uniquement (pas de mots de passe) +- **Clé publique autorisée:** `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIITcSsup4VjkH6FXa0Prwy44mQ1JOgG/ZzocdrJ91Svu aamroughriss@gmail.com` +- **Utilisateur:** `ncantu` sur tous les serveurs + +--- + +## DNS et Certificats SSL + +### Configuration DNS + +Tous les domaines utilisent des enregistrements **CNAME** pointant vers `4nk.myftp.biz` (DynDNS). + +**Exemple de configuration DNS (Gandi):** +``` +signet.4nkweb.com. 3600 IN CNAME 4nk.myftp.biz. +``` + +### Certificats SSL/TLS + +- **Provider:** Let's Encrypt +- **Renouvellement:** Automatique via Certbot +- **Couverture:** Tous les domaines ont des certificats SSL valides +- **Protocole:** HTTPS uniquement (redirection HTTP → HTTPS) + +### Vérification des Certificats + +```bash +# Vérifier un certificat +openssl s_client -connect domain:443 -servername domain + +# Lister tous les certificats +sudo certbot certificates +``` + +--- + +## NAT et Routage + +### Configuration NAT + +Le routeur/firewall expose les ports suivants vers Internet: + +| Port Externe | Protocole | IP Destination | Port Destination | Service | +|--------------|-----------|----------------|-----------------|---------| +| 22 | TCP | 192.168.1.100 | 22 | SSH (proxy) | +| 80 | TCP | 192.168.1.100 | 80 | HTTP (proxy) | +| 443 | TCP | 192.168.1.100 | 443 | HTTPS (proxy) | +| 38333 | TCP/UDP | 192.168.1.105 | 38333 | Bitcoin Signet (bitcoin) | +| 9418 | TCP | 192.168.1.104 | 9418 | Git Protocol | + +### Routage Web + +Le proxy Nginx route tous les domaines HTTP/HTTPS vers les serveurs backend appropriés: + +``` +Client → 4nk.myftp.biz:443 → Nginx (proxy) → Backend:Port +``` + +**Exemple:** +- `mempoo1.4nkweb.com` → 192.168.1.104:3015 + +### Routage Bitcoin + +Les ports Bitcoin sont exposés via NAT et routés par Nginx stream: + +``` +Client → 4nk.myftp.biz:38333 → Nginx Stream → bitcoin:38333 +``` + +--- + +## Guide d'Utilisation + +### Accéder aux Services Web + +Tous les services sont accessibles via HTTPS: + +```bash +# Exemples +curl https://signet.4nkweb.com +``` + +### Accéder aux Services Bitcoin + +**Bitcoin Signet (prod uniquement):** +```bash +# Connexion Bitcoin Signet +bitcoin-cli -rpcconnect=signet.4nkweb.com -rpcport=38333 getblockchaininfo + +# Test de connexion +nc -zv signet.4nkweb.com 38333 +``` + +### Utiliser Git + +**Cloner un dépôt:** +```bash +# Via HTTPS +git clone https://git1.4nkweb.com/username/repo.git + +# Via Git Protocol +git clone git://git1.4nkweb.com/username/repo.git +``` + +### Accéder à Mempool + +Ouvrir dans un navigateur: `https://mempool1.4nkweb.com` + +### Accéder à Rocket.Chat + +Ouvrir dans un navigateur: `https://rocket1.4nkweb.com` + +### Déployer un Service + +1. **Se connecter au serveur approprié:** + ```bash + ssh test # ou pprod, prod, services + ``` + +4. **Vérifier que l'application écoute sur le bon port:** + ```bash + ss -tlnp | grep + ``` + +5. **Tester l'accès:** + ```bash + curl https:// + ``` + +--- + +## Dépannage + +### Problèmes de Connexion SSH + +**Erreur: "Connection refused"** +- Vérifier que le proxy (4nk.myftp.biz) est accessible +- Vérifier que le port 22 est ouvert sur le firewall +- Vérifier la configuration NAT (port 22 → 192.168.1.100:22) + +**Erreur: "Permission denied"** +- Vérifier que votre clé SSH publique est dans `~/.ssh/authorized_keys` sur le serveur +- Vérifier les permissions: `chmod 600 ~/.ssh/authorized_keys` +- Vérifier la clé: `ssh-keygen -l -f ~/.ssh/id_ed25519.pub` + +**Erreur: "Host key verification failed"** +- Supprimer l'ancienne clé: `ssh-keygen -R 192.168.1.10x` +- Ou utiliser `StrictHostKeyChecking accept-new` dans la config + +### Problèmes d'Accès Web + +**Erreur: "Connection refused" ou timeout** +- Vérifier que le service écoute sur le bon port: `ss -tlnp | grep ` +- Vérifier la configuration Nginx sur le proxy +- Vérifier les logs Nginx: `sudo tail -f /var/log/nginx/error.log` + +**Erreur: "SSL certificate error"** +- Vérifier que le certificat est valide: `sudo certbot certificates` +- Renouveler le certificat si nécessaire: `sudo certbot renew` + +**Erreur: "502 Bad Gateway"** +- Vérifier que l'application backend est démarrée +- Vérifier la connectivité réseau entre proxy et backend +- Vérifier les logs de l'application + +### Problèmes DNS + +**Le domaine ne résout pas** +- Vérifier la configuration DNS (CNAME vers 4nk.myftp.biz) +- Vérifier la propagation DNS: `dig ` +- Attendre la propagation (peut prendre jusqu'à 24h) + +### Problèmes de Ports Bitcoin + +**Impossible de se connecter aux ports Bitcoin** +- Vérifier la configuration NAT (port 38333 → 192.168.1.103:38333) +- Vérifier la configuration Nginx stream +- Vérifier que le service Bitcoin écoute: `ss -tlnp | grep 38333` + +### Commandes de Diagnostic + +```bash +# Vérifier la connectivité réseau +ping 192.168.1.100 +ping 192.168.1.101 + +# Vérifier les ports ouverts +ss -tlnp + +# Vérifier les logs Nginx +sudo tail -f /var/log/nginx/access.log +sudo tail -f /var/log/nginx/error.log + +# Vérifier les certificats SSL +sudo certbot certificates + +# Vérifier la configuration Nginx +sudo nginx -t + +# Tester un domaine +curl -I https:// +``` + + diff --git a/desk/skills-cursor/create-rule/SKILL.md b/desk/skills-cursor/create-rule/SKILL.md new file mode 100644 index 0000000..ff9237b --- /dev/null +++ b/desk/skills-cursor/create-rule/SKILL.md @@ -0,0 +1,160 @@ +--- +name: create-rule +description: Create Cursor rules for persistent AI guidance. Use when the user wants to create a rule, add coding standards, set up project conventions, configure file-specific patterns, create RULE.md files, or asks about .cursor/rules/ or AGENTS.md. +--- +# Creating Cursor Rules + +Create project rules in `.cursor/rules/` to provide persistent context for the AI agent. + +## Gather Requirements + +Before creating a rule, determine: + +1. **Purpose**: What should this rule enforce or teach? +2. **Scope**: Should it always apply, or only for specific files? +3. **File patterns**: If file-specific, which glob patterns? + +### Inferring from Context + +If you have previous conversation context, infer rules from what was discussed. You can create multiple rules if the conversation covers distinct topics or patterns. Don't ask redundant questions if the context already provides the answers. + +### Required Questions + +If the user hasn't specified scope, ask: +- "Should this rule always apply, or only when working with specific files?" + +If they mentioned specific files and haven't provided concrete patterns, ask: +- "Which file patterns should this rule apply to?" (e.g., `**/*.ts`, `backend/**/*.py`) + +It's very important that we get clarity on the file patterns. + +Use the AskQuestion tool when available to gather this efficiently. + +--- + +## Rule File Format + +Rules are `.mdc` files in `.cursor/rules/` with YAML frontmatter: + +``` +.cursor/rules/ + typescript-standards.mdc + react-patterns.mdc + api-conventions.mdc +``` + +### File Structure + +```markdown +--- +description: Brief description of what this rule does +globs: **/*.ts # File pattern for file-specific rules +alwaysApply: false # Set to true if rule should always apply +--- + +# Rule Title + +Your rule content here... +``` + +### Frontmatter Fields + +| Field | Type | Description | +|-------|------|-------------| +| `description` | string | What the rule does (shown in rule picker) | +| `globs` | string | File pattern - rule applies when matching files are open | +| `alwaysApply` | boolean | If true, applies to every session | + +--- + +## Rule Configurations + +### Always Apply + +For universal standards that should apply to every conversation: + +```yaml +--- +description: Core coding standards for the project +alwaysApply: true +--- +``` + +### Apply to Specific Files + +For rules that apply when working with certain file types: + +```yaml +--- +description: TypeScript conventions for this project +globs: **/*.ts +alwaysApply: false +--- +``` + +--- + +## Best Practices + +### Keep Rules Concise + +- **Under 50 lines**: Rules should be concise and to the point +- **One concern per rule**: Split large rules into focused pieces +- **Actionable**: Write like clear internal docs +- **Concrete examples**: Ideally provide concrete examples of how to fix issues + +--- + +## Example Rules + +### TypeScript Standards + +```markdown +--- +description: TypeScript coding standards +globs: **/*.ts +alwaysApply: false +--- + +# Error Handling + +\`\`\`typescript +// ❌ BAD +try { + await fetchData(); +} catch (e) {} + +// ✅ GOOD +try { + await fetchData(); +} catch (e) { + logger.error('Failed to fetch', { error: e }); + throw new DataFetchError('Unable to retrieve data', { cause: e }); +} +\`\`\` +``` + +### React Patterns + +```markdown +--- +description: React component patterns +globs: **/*.tsx +alwaysApply: false +--- + +# React Patterns + +- Use functional components +- Extract custom hooks for reusable logic +- Colocate styles with components +``` + +--- + +## Checklist + +- [ ] File is `.mdc` format in `.cursor/rules/` +- [ ] Frontmatter configured correctly +- [ ] Content under 500 lines +- [ ] Includes concrete examples diff --git a/desk/skills-cursor/create-skill/SKILL.md b/desk/skills-cursor/create-skill/SKILL.md new file mode 100644 index 0000000..278c26d --- /dev/null +++ b/desk/skills-cursor/create-skill/SKILL.md @@ -0,0 +1,495 @@ +--- +name: create-skill +description: Guides users through creating effective Agent Skills for Cursor. Use when the user wants to create, write, or author a new skill, or asks about skill structure, best practices, or SKILL.md format. +--- +# Creating Skills in Cursor + +This skill guides you through creating effective Agent Skills for Cursor. Skills are markdown files that teach the agent how to perform specific tasks: reviewing PRs using team standards, generating commit messages in a preferred format, querying database schemas, or any specialized workflow. + +## Before You Begin: Gather Requirements + +Before creating a skill, gather essential information from the user about: + +1. **Purpose and scope**: What specific task or workflow should this skill help with? +2. **Target location**: Should this be a personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)? +3. **Trigger scenarios**: When should the agent automatically apply this skill? +4. **Key domain knowledge**: What specialized information does the agent need that it wouldn't already know? +5. **Output format preferences**: Are there specific templates, formats, or styles required? +6. **Existing patterns**: Are there existing examples or conventions to follow? + +### Inferring from Context + +If you have previous conversation context, infer the skill from what was discussed. You can create skills based on workflows, patterns, or domain knowledge that emerged in the conversation. + +### Gathering Additional Information + +If you need clarification, use the AskQuestion tool when available: + +``` +Example AskQuestion usage: +- "Where should this skill be stored?" with options like ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"] +- "Should this skill include executable scripts?" with options like ["Yes", "No"] +``` + +If the AskQuestion tool is not available, ask these questions conversationally. + +--- + +## Skill File Structure + +### Directory Layout + +Skills are stored as directories containing a `SKILL.md` file: + +``` +skill-name/ +├── SKILL.md # Required - main instructions +├── reference.md # Optional - detailed documentation +├── examples.md # Optional - usage examples +└── scripts/ # Optional - utility scripts + ├── validate.py + └── helper.sh +``` + +### Storage Locations + +| Type | Path | Scope | +|------|------|-------| +| Personal | ~/.cursor/skills/skill-name/ | Available across all your projects | +| Project | .cursor/skills/skill-name/ | Shared with anyone using the repository | + +**IMPORTANT**: Never create skills in `~/.cursor/skills-cursor/`. This directory is reserved for Cursor's internal built-in skills and is managed automatically by the system. + +### SKILL.md Structure + +Every skill requires a `SKILL.md` file with YAML frontmatter and markdown body: + +```markdown +--- +name: your-skill-name +description: Brief description of what this skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Clear, step-by-step guidance for the agent. + +## Examples +Concrete examples of using this skill. +``` + +### Required Metadata Fields + +| Field | Requirements | Purpose | +|-------|--------------|---------| +| `name` | Max 64 chars, lowercase letters/numbers/hyphens only | Unique identifier for the skill | +| `description` | Max 1024 chars, non-empty | Helps agent decide when to apply the skill | + +--- + +## Writing Effective Descriptions + +The description is **critical** for skill discovery. The agent uses it to decide when to apply your skill. + +### Description Best Practices + +1. **Write in third person** (the description is injected into the system prompt): + - ✅ Good: "Processes Excel files and generates reports" + - ❌ Avoid: "I can help you process Excel files" + - ❌ Avoid: "You can use this to process Excel files" + +2. **Be specific and include trigger terms**: + - ✅ Good: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." + - ❌ Vague: "Helps with documents" + +3. **Include both WHAT and WHEN**: + - WHAT: What the skill does (specific capabilities) + - WHEN: When the agent should use it (trigger scenarios) + +### Description Examples + +```yaml +# PDF Processing +description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. + +# Excel Analysis +description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. + +# Git Commit Helper +description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. + +# Code Review +description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review. +``` + +--- + +## Core Authoring Principles + +### 1. Concise is Key + +The context window is shared with conversation history, other skills, and requests. Every token competes for space. + +**Default assumption**: The agent is already very smart. Only add context it doesn't already have. + +Challenge each piece of information: +- "Does the agent really need this explanation?" +- "Can I assume the agent knows this?" +- "Does this paragraph justify its token cost?" + +**Good (concise)**: +```markdown +## Extract PDF text + +Use pdfplumber for text extraction: + +\`\`\`python +import pdfplumber + +with pdfplumber.open("file.pdf") as pdf: + text = pdf.pages[0].extract_text() +\`\`\` +``` + +**Bad (verbose)**: +```markdown +## Extract PDF text + +PDF (Portable Document Format) files are a common file format that contains +text, images, and other content. To extract text from a PDF, you'll need to +use a library. There are many libraries available for PDF processing, but we +recommend pdfplumber because it's easy to use and handles most cases well... +``` + +### 2. Keep SKILL.md Under 500 Lines + +For optimal performance, the main SKILL.md file should be concise. Use progressive disclosure for detailed content. + +### 3. Progressive Disclosure + +Put essential information in SKILL.md; detailed reference material in separate files that the agent reads only when needed. + +```markdown +# PDF Processing + +## Quick start +[Essential instructions here] + +## Additional resources +- For complete API details, see [reference.md](reference.md) +- For usage examples, see [examples.md](examples.md) +``` + +**Keep references one level deep** - link directly from SKILL.md to reference files. Deeply nested references may result in partial reads. + +### 4. Set Appropriate Degrees of Freedom + +Match specificity to the task's fragility: + +| Freedom Level | When to Use | Example | +|---------------|-------------|---------| +| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines | +| **Medium** (pseudocode/templates) | Preferred pattern with acceptable variation | Report generation | +| **Low** (specific scripts) | Fragile operations, consistency critical | Database migrations | + +--- + +## Common Patterns + +### Template Pattern + +Provide output format templates: + +```markdown +## Report structure + +Use this template: + +\`\`\`markdown +# [Analysis Title] + +## Executive summary +[One-paragraph overview of key findings] + +## Key findings +- Finding 1 with supporting data +- Finding 2 with supporting data + +## Recommendations +1. Specific actionable recommendation +2. Specific actionable recommendation +\`\`\` +``` + +### Examples Pattern + +For skills where output quality depends on seeing examples: + +```markdown +## Commit message format + +**Example 1:** +Input: Added user authentication with JWT tokens +Output: +\`\`\` +feat(auth): implement JWT-based authentication + +Add login endpoint and token validation middleware +\`\`\` + +**Example 2:** +Input: Fixed bug where dates displayed incorrectly +Output: +\`\`\` +fix(reports): correct date formatting in timezone conversion + +Use UTC timestamps consistently across report generation +\`\`\` +``` + +### Workflow Pattern + +Break complex operations into clear steps with checklists: + +```markdown +## Form filling workflow + +Copy this checklist and track progress: + +\`\`\` +Task Progress: +- [ ] Step 1: Analyze the form +- [ ] Step 2: Create field mapping +- [ ] Step 3: Validate mapping +- [ ] Step 4: Fill the form +- [ ] Step 5: Verify output +\`\`\` + +**Step 1: Analyze the form** +Run: \`python scripts/analyze_form.py input.pdf\` +... +``` + +### Conditional Workflow Pattern + +Guide through decision points: + +```markdown +## Document modification workflow + +1. Determine the modification type: + + **Creating new content?** → Follow "Creation workflow" below + **Editing existing content?** → Follow "Editing workflow" below + +2. Creation workflow: + - Use docx-js library + - Build document from scratch + ... +``` + +### Feedback Loop Pattern + +For quality-critical tasks, implement validation loops: + +```markdown +## Document editing process + +1. Make your edits +2. **Validate immediately**: \`python scripts/validate.py output/\` +3. If validation fails: + - Review the error message + - Fix the issues + - Run validation again +4. **Only proceed when validation passes** +``` + +--- + +## Utility Scripts + +Pre-made scripts offer advantages over generated code: +- More reliable than generated code +- Save tokens (no code in context) +- Save time (no code generation) +- Ensure consistency across uses + +```markdown +## Utility scripts + +**analyze_form.py**: Extract all form fields from PDF +\`\`\`bash +python scripts/analyze_form.py input.pdf > fields.json +\`\`\` + +**validate.py**: Check for errors +\`\`\`bash +python scripts/validate.py fields.json +# Returns: "OK" or lists conflicts +\`\`\` +``` + +Make clear whether the agent should **execute** the script (most common) or **read** it as reference. + +--- + +## Anti-Patterns to Avoid + +### 1. Windows-Style Paths +- ✅ Use: `scripts/helper.py` +- ❌ Avoid: `scripts\helper.py` + +### 2. Too Many Options +```markdown +# Bad - confusing +"You can use pypdf, or pdfplumber, or PyMuPDF, or..." + +# Good - provide a default with escape hatch +"Use pdfplumber for text extraction. +For scanned PDFs requiring OCR, use pdf2image with pytesseract instead." +``` + +### 3. Time-Sensitive Information +```markdown +# Bad - will become outdated +"If you're doing this before August 2025, use the old API." + +# Good - use an "old patterns" section +## Current method +Use the v2 API endpoint. + +## Old patterns (deprecated) +
+Legacy v1 API +... +
+``` + +### 4. Inconsistent Terminology +Choose one term and use it throughout: +- ✅ Always "API endpoint" (not mixing "URL", "route", "path") +- ✅ Always "field" (not mixing "box", "element", "control") + +### 5. Vague Skill Names +- ✅ Good: `processing-pdfs`, `analyzing-spreadsheets` +- ❌ Avoid: `helper`, `utils`, `tools` + +--- + +## Skill Creation Workflow + +When helping a user create a skill, follow this process: + +### Phase 1: Discovery + +Gather information about: +1. The skill's purpose and primary use case +2. Storage location (personal vs project) +3. Trigger scenarios +4. Any specific requirements or constraints +5. Existing examples or patterns to follow + +If you have access to the AskQuestion tool, use it for efficient structured gathering. Otherwise, ask conversationally. + +### Phase 2: Design + +1. Draft the skill name (lowercase, hyphens, max 64 chars) +2. Write a specific, third-person description +3. Outline the main sections needed +4. Identify if supporting files or scripts are needed + +### Phase 3: Implementation + +1. Create the directory structure +2. Write the SKILL.md file with frontmatter +3. Create any supporting reference files +4. Create any utility scripts if needed + +### Phase 4: Verification + +1. Verify the SKILL.md is under 500 lines +2. Check that the description is specific and includes trigger terms +3. Ensure consistent terminology throughout +4. Verify all file references are one level deep +5. Test that the skill can be discovered and applied + +--- + +## Complete Example + +Here's a complete example of a well-structured skill: + +**Directory structure:** +``` +code-review/ +├── SKILL.md +├── STANDARDS.md +└── examples.md +``` + +**SKILL.md:** +```markdown +--- +name: code-review +description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review. +--- + +# Code Review + +## Quick Start + +When reviewing code: + +1. Check for correctness and potential bugs +2. Verify security best practices +3. Assess code readability and maintainability +4. Ensure tests are adequate + +## Review Checklist + +- [ ] Logic is correct and handles edge cases +- [ ] No security vulnerabilities (SQL injection, XSS, etc.) +- [ ] Code follows project style conventions +- [ ] Functions are appropriately sized and focused +- [ ] Error handling is comprehensive +- [ ] Tests cover the changes + +## Providing Feedback + +Format feedback as: +- 🔴 **Critical**: Must fix before merge +- 🟡 **Suggestion**: Consider improving +- 🟢 **Nice to have**: Optional enhancement + +## Additional Resources + +- For detailed coding standards, see [STANDARDS.md](STANDARDS.md) +- For example reviews, see [examples.md](examples.md) +``` + +--- + +## Summary Checklist + +Before finalizing a skill, verify: + +### Core Quality +- [ ] Description is specific and includes key terms +- [ ] Description includes both WHAT and WHEN +- [ ] Written in third person +- [ ] SKILL.md body is under 500 lines +- [ ] Consistent terminology throughout +- [ ] Examples are concrete, not abstract + +### Structure +- [ ] File references are one level deep +- [ ] Progressive disclosure used appropriately +- [ ] Workflows have clear steps +- [ ] No time-sensitive information + +### If Including Scripts +- [ ] Scripts solve problems rather than punt +- [ ] Required packages are documented +- [ ] Error handling is explicit and helpful +- [ ] No Windows-style paths diff --git a/desk/skills-cursor/create-subagent/SKILL.md b/desk/skills-cursor/create-subagent/SKILL.md new file mode 100644 index 0000000..88bda4b --- /dev/null +++ b/desk/skills-cursor/create-subagent/SKILL.md @@ -0,0 +1,222 @@ +--- +name: create-subagent +description: Create custom subagents for specialized AI tasks. Use when the user wants to create a new type of subagent, set up task-specific agents, configure code reviewers, debuggers, or domain-specific assistants with custom prompts. +disable-model-invocation: true +--- +# Creating Custom Subagents + +This skill guides you through creating custom subagents for Cursor. Subagents are specialized AI assistants that run in isolated contexts with custom system prompts. + +## When to Use Subagents + +Subagents help you: +- **Preserve context** by isolating exploration from your main conversation +- **Specialize behavior** with focused system prompts for specific domains +- **Reuse configurations** across projects with user-level subagents + +### Inferring from Context + +If you have previous conversation context, infer the subagent's purpose and behavior from what was discussed. Create the subagent based on specialized tasks or workflows that emerged in the conversation. + +## Subagent Locations + +| Location | Scope | Priority | +|----------|-------|----------| +| `.cursor/agents/` | Current project | Higher | +| `~/.cursor/agents/` | All your projects | Lower | + +When multiple subagents share the same name, the higher-priority location wins. + +**Project subagents** (`.cursor/agents/`): Ideal for codebase-specific agents. Check into version control to share with your team. + +**User subagents** (`~/.cursor/agents/`): Personal agents available across all your projects. + +## Subagent File Format + +Create a `.md` file with YAML frontmatter and a markdown body (the system prompt): + +```markdown +--- +name: code-reviewer +description: Reviews code for quality and best practices +--- + +You are a code reviewer. When invoked, analyze the code and provide +specific, actionable feedback on quality, security, and best practices. +``` + +### Required Fields + +| Field | Description | +|-------|-------------| +| `name` | Unique identifier (lowercase letters and hyphens only) | +| `description` | When to delegate to this subagent (be specific!) | + +## Writing Effective Descriptions + +The description is **critical** - the AI uses it to decide when to delegate. + +```yaml +# ❌ Too vague +description: Helps with code + +# ✅ Specific and actionable +description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. +``` + +Include "use proactively" to encourage automatic delegation. + +## Example Subagents + +### Code Reviewer + +```markdown +--- +name: code-reviewer +description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. +--- + +You are a senior code reviewer ensuring high standards of code quality and security. + +When invoked: +1. Run git diff to see recent changes +2. Focus on modified files +3. Begin review immediately + +Review checklist: +- Code is clear and readable +- Functions and variables are well-named +- No duplicated code +- Proper error handling +- No exposed secrets or API keys +- Input validation implemented +- Good test coverage +- Performance considerations addressed + +Provide feedback organized by priority: +- Critical issues (must fix) +- Warnings (should fix) +- Suggestions (consider improving) + +Include specific examples of how to fix issues. +``` + +### Debugger + +```markdown +--- +name: debugger +description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues. +--- + +You are an expert debugger specializing in root cause analysis. + +When invoked: +1. Capture error message and stack trace +2. Identify reproduction steps +3. Isolate the failure location +4. Implement minimal fix +5. Verify solution works + +Debugging process: +- Analyze error messages and logs +- Check recent code changes +- Form and test hypotheses +- Add strategic debug logging +- Inspect variable states + +For each issue, provide: +- Root cause explanation +- Evidence supporting the diagnosis +- Specific code fix +- Testing approach +- Prevention recommendations + +Focus on fixing the underlying issue, not the symptoms. +``` + +### Data Scientist + +```markdown +--- +name: data-scientist +description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries. +--- + +You are a data scientist specializing in SQL and BigQuery analysis. + +When invoked: +1. Understand the data analysis requirement +2. Write efficient SQL queries +3. Use BigQuery command line tools (bq) when appropriate +4. Analyze and summarize results +5. Present findings clearly + +Key practices: +- Write optimized SQL queries with proper filters +- Use appropriate aggregations and joins +- Include comments explaining complex logic +- Format results for readability +- Provide data-driven recommendations + +For each analysis: +- Explain the query approach +- Document any assumptions +- Highlight key findings +- Suggest next steps based on data + +Always ensure queries are efficient and cost-effective. +``` + +## Subagent Creation Workflow + +### Step 1: Decide the Scope + +- **Project-level** (`.cursor/agents/`): For codebase-specific agents shared with team +- **User-level** (`~/.cursor/agents/`): For personal agents across all projects + +### Step 2: Create the File + +```bash +# For project-level +mkdir -p .cursor/agents +touch .cursor/agents/my-agent.md + +# For user-level +mkdir -p ~/.cursor/agents +touch ~/.cursor/agents/my-agent.md +``` + +### Step 3: Define Configuration + +Write the frontmatter with the required fields (`name` and `description`). + +### Step 4: Write the System Prompt + +The body becomes the system prompt. Be specific about: +- What the agent should do when invoked +- The workflow or process to follow +- Output format and structure +- Any constraints or guidelines + +### Step 5: Test the Agent + +Ask the AI to use your new agent: + +``` +Use the my-agent subagent to [task description] +``` + +## Best Practices + +1. **Design focused subagents**: Each should excel at one specific task +2. **Write detailed descriptions**: Include trigger terms so the AI knows when to delegate +3. **Check into version control**: Share project subagents with your team +4. **Use proactive language**: Include "use proactively" in descriptions + +## Troubleshooting + +### Subagent Not Found +- Ensure file is in `.cursor/agents/` or `~/.cursor/agents/` +- Check file has `.md` extension +- Verify YAML frontmatter syntax is valid diff --git a/desk/skills-cursor/migrate-to-skills/SKILL.md b/desk/skills-cursor/migrate-to-skills/SKILL.md new file mode 100644 index 0000000..faf4014 --- /dev/null +++ b/desk/skills-cursor/migrate-to-skills/SKILL.md @@ -0,0 +1,130 @@ +--- +name: migrate-to-skills +description: Convert 'Applied intelligently' Cursor rules (.cursor/rules/*.mdc) and slash commands (.cursor/commands/*.md) to Agent Skills format (.cursor/skills/). Use when the user wants to migrate rules or commands to skills, convert .mdc rules to SKILL.md format, or consolidate commands into the skills directory. +disable-model-invocation: true +--- +# Migrate Rules and Slash Commands to Skills + +Convert Cursor rules ("Applied intelligently") and slash commands to Agent Skills format. + +**CRITICAL: Preserve the exact body content. Do not modify, reformat, or "improve" it - copy verbatim.** + +## Locations + +| Level | Source | Destination | +|-------|--------|-------------| +| Project | `{workspaceFolder}/**/.cursor/rules/*.mdc`, `{workspaceFolder}/.cursor/commands/*.md` | +| User | `~/.cursor/commands/*.md` | + +Notes: +- Cursor rules inside the project can live in nested directories. Be thorough in your search and use glob patterns to find them. +- Ignore anything in ~/.cursor/worktrees +- Ignore anything in ~/.cursor/skills-cursor. This is reserved for Cursor's internal built-in skills and is managed automatically by the system. + +## Finding Files to Migrate + +**Rules**: Migrate if rule has a `description` but NO `globs` and NO `alwaysApply: true`. + +**Commands**: Migrate all - they're plain markdown without frontmatter. + +## Conversion Format + +### Rules: .mdc → SKILL.md + +```markdown +# Before: .cursor/rules/my-rule.mdc +--- +description: What this rule does +globs: +alwaysApply: false +--- +# Title +Body content... +``` + +```markdown +# After: .cursor/skills/my-rule/SKILL.md +--- +name: my-rule +description: What this rule does +--- +# Title +Body content... +``` + +Changes: Add `name` field, remove `globs`/`alwaysApply`, keep body exactly. + +### Commands: .md → SKILL.md + +```markdown +# Before: .cursor/commands/commit.md +# Commit current work +Instructions here... +``` + +```markdown +# After: .cursor/skills/commit/SKILL.md +--- +name: commit +description: Commit current work with standardized message format +disable-model-invocation: true +--- +# Commit current work +Instructions here... +``` + +Changes: Add frontmatter with `name` (from filename), `description` (infer from content), and `disable-model-invocation: true`, keep body exactly. + +**Note:** The `disable-model-invocation: true` field prevents the model from automatically invoking this skill. Slash commands are designed to be explicitly triggered by the user via the `/` menu, not automatically suggested by the model. + +## Notes + +- `name` must be lowercase with hyphens only +- `description` is critical for skill discovery +- Optionally delete originals after verifying migration works + +### Migrate a Rule (.mdc → SKILL.md) + +1. Read the rule file +2. Extract the `description` from the frontmatter +3. Extract the body content (everything after the closing `---` of the frontmatter) +4. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .mdc) +5. Write `SKILL.md` with new frontmatter (`name` and `description`) + the EXACT original body content (preserve all whitespace, formatting, code blocks verbatim) +6. Delete the original rule file + +### Migrate a Command (.md → SKILL.md) + +1. Read the command file +2. Extract description from the first heading (remove `#` prefix) +3. Create the skill directory: `.cursor/skills/{skill-name}/` (skill name = filename without .md) +4. Write `SKILL.md` with new frontmatter (`name`, `description`, and `disable-model-invocation: true`) + blank line + the EXACT original file content (preserve all whitespace, formatting, code blocks verbatim) +5. Delete the original command file + +**CRITICAL: Copy the body content character-for-character. Do not reformat, fix typos, or "improve" anything.** + +## Workflow + +If you have the Task tool available: +DO NOT start to read all of the files yourself. That function should be delegated to the subagents. Your job is to dispatch the subagents for each category of files and wait for the results. + +1. [ ] Create the skills directories if they don't exist (`.cursor/skills/` for project, `~/.cursor/skills/` for user) +2. Dispatch three fast general purpose subagents (NOT explore) in parallel to do the following steps for project rules (pattern: `{workspaceFolder}/**/.cursor/rules/*.mdc`), user commands (pattern: `~/.cursor/commands/*.md`), and project commands (pattern: `{workspaceFolder}/**/.cursor/commands/*.md`): + I. [ ] Find files to migrate in the given pattern + II. [ ] For rules, check if it's an "applied intelligently" rule (has `description`, no `globs`, no `alwaysApply: true`). Commands are always migrated. DO NOT use the terminal to read files. Use the read tool. + III. [ ] Make a list of files to migrate. If empty, done. + IV. [ ] For each file, read it, then write the new skill file preserving the body content EXACTLY. DO NOT use the terminal to write these files. Use the edit tool. + V. [ ] Delete the original file. DO NOT use the terminal to delete these files. Use the delete tool. + VI. [ ] Return a list of all the skill files that were migrated along with the original file paths. +3. [ ] Wait for all subagents to complete and summarize the results to the user. IMPORTANT: Make sure to let them know if they want to undo the migration, to ask you to. +4. [ ] If the user asks you to undo the migration, do the opposite of the above steps to restore the original files. + + +If you don't have the Task tool available: +1. [ ] Create the skills directories if they don't exist (`.cursor/skills/` for project, `~/.cursor/skills/` for user) +2. [ ] Find files to migrate in both project (`.cursor/`) and user (`~/.cursor/`) directories +3. [ ] For rules, check if it's an "applied intelligently" rule (has `description`, no `globs`, no `alwaysApply: true`). Commands are always migrated. DO NOT use the terminal to read files. Use the read tool. +4. [ ] Make a list of files to migrate. If empty, done. +5. [ ] For each file, read it, then write the new skill file preserving the body content EXACTLY. DO NOT use the terminal to write these files. Use the edit tool. +6. [ ] Delete the original file. DO NOT use the terminal to delete these files. Use the delete tool. +7. [ ] Summarize the results to the user. IMPORTANT: Make sure to let them know if they want to undo the migration, to ask you to. +8. [ ] If the user asks you to undo the migration, do the opposite of the above steps to restore the original files. diff --git a/desk/skills-cursor/update-cursor-settings/SKILL.md b/desk/skills-cursor/update-cursor-settings/SKILL.md new file mode 100644 index 0000000..81d6903 --- /dev/null +++ b/desk/skills-cursor/update-cursor-settings/SKILL.md @@ -0,0 +1,114 @@ +--- +name: update-cursor-settings +description: Modify Cursor/VSCode user settings in settings.json. Use when the user wants to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values. +--- +# Updating Cursor Settings + +This skill guides you through modifying Cursor/VSCode user settings. Use this when the user wants to change editor settings, preferences, configuration, themes, keybindings, or any `settings.json` values. + +## Settings File Location + +| OS | Path | +|----|------| +| macOS | ~/Library/Application Support/Cursor/User/settings.json | +| Linux | ~/.config/Cursor/User/settings.json | +| Windows | %APPDATA%\Cursor\User\settings.json | + +## Before Modifying Settings + +1. **Read the existing settings file** to understand current configuration +2. **Preserve existing settings** - only add/modify what the user requested +3. **Validate JSON syntax** before writing to avoid breaking the editor + +## Modifying Settings + +### Step 1: Read Current Settings + +```typescript +// Read the settings file first +const settingsPath = "~/Library/Application Support/Cursor/User/settings.json"; +// Use the Read tool to get current contents +``` + +### Step 2: Identify the Setting to Change + +Common setting categories: +- **Editor**: `editor.fontSize`, `editor.tabSize`, `editor.wordWrap`, `editor.formatOnSave` +- **Workbench**: `workbench.colorTheme`, `workbench.iconTheme`, `workbench.sideBar.location` +- **Files**: `files.autoSave`, `files.exclude`, `files.associations` +- **Terminal**: `terminal.integrated.fontSize`, `terminal.integrated.shell.*` +- **Cursor-specific**: Settings prefixed with `cursor.` or `aipopup.` + +### Step 3: Update the Setting + +When modifying settings.json: +1. Parse the existing JSON (handle comments - VSCode settings support JSON with comments) +2. Add or update the requested setting +3. Preserve all other existing settings +4. Write back with proper formatting (2-space indentation) + +### Example: Changing Font Size + +If user says "make the font bigger": + +```json +{ + "editor.fontSize": 16 +} +``` + +### Example: Enabling Format on Save + +If user says "format my code when I save": + +```json +{ + "editor.formatOnSave": true +} +``` + +### Example: Changing Theme + +If user says "use dark theme" or "change my theme": + +```json +{ + "workbench.colorTheme": "Default Dark Modern" +} +``` + +## Important Notes + +1. **JSON with Comments**: VSCode/Cursor settings.json supports comments (`//` and `/* */`). When reading, be aware comments may exist. When writing, preserve comments if possible. + +2. **Restart May Be Required**: Some settings take effect immediately, others require reloading the window or restarting Cursor. Inform the user if a restart is needed. + +3. **Backup**: For significant changes, consider mentioning the user can undo via Ctrl/Cmd+Z in the settings file or by reverting git changes if tracked. + +4. **Workspace vs User Settings**: + - User settings (what this skill covers): Apply globally to all projects + - Workspace settings (`.vscode/settings.json`): Apply only to the current project + +## Common User Requests → Settings + +| User Request | Setting | +|--------------|---------| +| "bigger/smaller font" | `editor.fontSize` | +| "change tab size" | `editor.tabSize` | +| "format on save" | `editor.formatOnSave` | +| "word wrap" | `editor.wordWrap` | +| "change theme" | `workbench.colorTheme` | +| "hide minimap" | `editor.minimap.enabled` | +| "auto save" | `files.autoSave` | +| "line numbers" | `editor.lineNumbers` | +| "bracket matching" | `editor.bracketPairColorization.enabled` | +| "cursor style" | `editor.cursorStyle` | +| "smooth scrolling" | `editor.smoothScrolling` | + +## Workflow + +1. Read ~/Library/Application Support/Cursor/User/settings.json +2. Parse the JSON content +3. Add/modify the requested setting(s) +4. Write the updated JSON back to the file +5. Inform the user the setting has been changed and whether a reload is needed diff --git a/ia_local/commands/pousse.md b/ia_local/commands/pousse.md new file mode 100644 index 0000000..8819184 --- /dev/null +++ b/ia_local/commands/pousse.md @@ -0,0 +1,62 @@ +# pousse + +## When to use + +- User asks to "commit", "push", "git add", or "save to git" +- After completing code changes and the user expects a commit +- Do **not** run commit/push without user validation of the commit message + +## Workflow + +1. **Stage all changes**: `git add -A` +2. **Propose commit message**: Build the message using the structured format below; show it to the user and wait for validation. +3. **Commit**: After validation, run `git commit -m "..."` with the approved message (use a single quoted multi-line string or `-F` with a temp file if the message is long). +4. **Push**: Run `git push` (or `git push origin ` if the context specifies a branch). Do not trigger CI if the user's rules forbid it. + +## Commit message format + +Use this structure. Every commit must follow it. Sections can be omitted only when not applicable (e.g. no bug fix → no **Root causes:** or **Correctifs:**). + +```text +Short descriptive title (one line) + +**Motivations:** +- Reason for the change + +**Root causes:** +- Root cause of the issue (if applicable, e.g. for fixes) + +**Correctifs:** +- What was fixed + +**Evolutions:** +- New features or improvements + +**Pages affectées:** +- List of modified files or modules +``` + +- Prefer bullet points under each section; no need for totals (e.g. "X files modified"). +- Write the body in the same language as the project (e.g. French if the repo uses French). +- Do not use `--no-verify` unless the user explicitly requests it and it is documented. + +## Commands (summary) + +```bash +git add -A +git status # optional: show what will be committed +# Propose message → get user validation +git commit -m "Title + +**Motivations:** +- ... + +**Correctifs:** / **Evolutions:** / **Pages affectées:** ..." +git push +``` + +## Notes + +- On Windows, use Git Bash for shell commands when specified by the user. +- Do not run in background; run commands so the user sees the full output. +- If the user's rules say "do not trigger CI", use the push method that avoids triggering CI (e.g. push to a branch that does not run CI, or follow project docs). diff --git a/ia_local/skills/git-add-commit-push/SKILL.md b/ia_local/skills/git-add-commit-push/SKILL.md new file mode 100644 index 0000000..701b670 --- /dev/null +++ b/ia_local/skills/git-add-commit-push/SKILL.md @@ -0,0 +1,67 @@ +--- +name: git-add-commit-push +description: Run git add -A, create a structured commit message, and push. Use when the user asks to commit, push, or save changes to git, or after completing code changes that need to be committed. +--- + +# Git Add, Commit, Push + +## When to use + +- User asks to "commit", "push", "git add", or "save to git" +- After completing code changes and the user expects a commit +- Do **not** run commit/push without user validation of the commit message + +## Workflow + +1. **Stage all changes**: `git add -A` +2. **Propose commit message**: Build the message using the structured format below; show it to the user and wait for validation. +3. **Commit**: After validation, run `git commit -m "..."` with the approved message (use a single quoted multi-line string or `-F` with a temp file if the message is long). +4. **Push**: Run `git push` (or `git push origin ` if the context specifies a branch). Do not trigger CI if the user's rules forbid it. + +## Commit message format + +Use this structure. Every commit must follow it. Sections can be omitted only when not applicable (e.g. no bug fix → no **Root causes:** or **Correctifs:**). + +```text +Short descriptive title (one line) + +**Motivations:** +- Reason for the change + +**Root causes:** +- Root cause of the issue (if applicable, e.g. for fixes) + +**Correctifs:** +- What was fixed + +**Evolutions:** +- New features or improvements + +**Pages affectées:** +- List of modified files or modules +``` + +- Prefer bullet points under each section; no need for totals (e.g. "X files modified"). +- Write the body in the same language as the project (e.g. French if the repo uses French). +- Do not use `--no-verify` unless the user explicitly requests it and it is documented. + +## Commands (summary) + +```bash +git add -A +git status # optional: show what will be committed +# Propose message → get user validation +git commit -m "Title + +**Motivations:** +- ... + +**Correctifs:** / **Evolutions:** / **Pages affectées:** ..." +git push +``` + +## Notes + +- On Windows, use Git Bash for shell commands when specified by the user. +- Do not run in background; run commands so the user sees the full output. +- If the user's rules say "do not trigger CI", use the push method that avoids triggering CI (e.g. push to a branch that does not run CI, or follow project docs). diff --git a/lecoffre_ng/agents/fix-lint.md b/lecoffre_ng/agents/fix-lint.md new file mode 120000 index 0000000..865cd45 --- /dev/null +++ b/lecoffre_ng/agents/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/agents/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng/commands/audit-security.md b/lecoffre_ng/commands/audit-security.md new file mode 100644 index 0000000..8d90b47 --- /dev/null +++ b/lecoffre_ng/commands/audit-security.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Audit sécurité + +Exécute le plan `~/.cursor/plans/workflow-audit-security.plan.md`. + +Lis le fichier plan. Applique la méthodologie OWASP : analyse surface d'attaque, revue Top 10, évaluation risque, recommandations. Format rapport : [SEVERITY] Titre ; Location ; Description ; Impact ; Reproduction ; Remediation. diff --git a/lecoffre_ng/commands/banch-align-update.md b/lecoffre_ng/commands/banch-align-update.md new file mode 100644 index 0000000..1cb066c --- /dev/null +++ b/lecoffre_ng/commands/banch-align-update.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branche actuelle (banch-align-update) + +Exécute le plan `~/.cursor/plans/workflow-banch-align-update.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align-update test`). Si absent, demande à l'utilisateur. Attends confirmation avant stash et alignement. diff --git a/lecoffre_ng/commands/banch-align.md b/lecoffre_ng/commands/banch-align.md new file mode 100644 index 0000000..477703b --- /dev/null +++ b/lecoffre_ng/commands/banch-align.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branches (banch-align) + +Exécute le plan `~/.cursor/plans/workflow-banch-align.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align test`). Si absent, demande à l'utilisateur. diff --git a/lecoffre_ng/commands/cloture-evolution.md b/lecoffre_ng/commands/cloture-evolution.md new file mode 100644 index 0000000..c9a13e9 --- /dev/null +++ b/lecoffre_ng/commands/cloture-evolution.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Clôture évolution / correction + +Exécute le plan `~/.cursor/plans/workflow-cloture-evolution.plan.md`. + +Lis le fichier plan, suis les phases et todos dans l'ordre. Boucle chaque bloc jusqu'à stabilisation (rien à optimiser). Demande validation avant déploiement. diff --git a/lecoffre_ng/commands/deploy.md b/lecoffre_ng/commands/deploy.md new file mode 100644 index 0000000..e5f7521 --- /dev/null +++ b/lecoffre_ng/commands/deploy.md @@ -0,0 +1,23 @@ +--- +model: inherit +--- +# Déployer (test, pprod, prod) + +L'environnement `` est passé en paramètre (ex. `/deploy test`). Si absent, demander à l'utilisateur. + +**Action** : Exécuter le script de déploiement depuis la racine du projet : +```bash +./deploy/scripts_v2/deploy.sh +``` +Le script s'exécute **localement** et orchestre le déploiement **à distance** (SSH vers la cible, git pull, build, restart services). Ne pas tenter de déployer manuellement ou via d'autres chemins. + +**En cas d'échec** : Orchestrer la correction automatique (boucle jusqu'à succès ou impossibilité). Ne pas s'arrêter au rapport d'échec : +1. Analyser la cause (logs backend, journalctl sur cible, présence fichiers dans le repo et dans dist sur cible) +2. Corriger la root cause (code, imports, config, build) sans contournement +3. Committer et pousser si modifications +4. Relancer `./deploy/scripts_v2/deploy.sh ` +5. Répéter tant que l'échec persiste et qu'une correction est identifiée + +Si délégation au subagent deploy : en cas de retour d'échec, l'agent principal prend le relais et exécute cette orchestration (ne pas se contenter de transmettre l'échec à l'utilisateur). + +**Concurrence** : Le script exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents (lint, fix-lint, typecheck, turbopack) dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. `DEPLOY_SKIP_CONCURRENCY_CHECK=1` pour désactiver. diff --git a/lecoffre_ng/commands/docupdate.md b/lecoffre_ng/commands/docupdate.md new file mode 100644 index 0000000..31bf3b7 --- /dev/null +++ b/lecoffre_ng/commands/docupdate.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Mise à jour documentation + +Exécute le plan `~/.cursor/plans/workflow-docupdate.plan.md`. + +Lis le fichier plan. Suis les phases : docs/features extract, docs/fixKnowledge extract, docs/ cleanup. diff --git a/lecoffre_ng/commands/fix-lint.md b/lecoffre_ng/commands/fix-lint.md new file mode 120000 index 0000000..d73d679 --- /dev/null +++ b/lecoffre_ng/commands/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/commands/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng/commands/lintit.md b/lecoffre_ng/commands/lintit.md new file mode 100644 index 0000000..53e0a15 --- /dev/null +++ b/lecoffre_ng/commands/lintit.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Lintit (qualité code) + +Exécute le plan `~/.cursor/plans/workflow-lintit.plan.md`. + +Lis le fichier plan. Vérifie les règles qualité, liste les actions à mener, corrige erreurs et warnings lint sans contournement. diff --git a/lecoffre_ng/commands/pousse.md b/lecoffre_ng/commands/pousse.md new file mode 100644 index 0000000..b313121 --- /dev/null +++ b/lecoffre_ng/commands/pousse.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Commit et push (pousse) + +Exécute le plan `~/.cursor/plans/workflow-pousse.plan.md`. + +Lis le fichier plan. Propose le message de commit au format structuré (Motivations, Root causes, Correctifs, Evolutions, Pages affectées). Attends validation avant d'exécuter git commit et git push. diff --git a/lecoffre_ng/plans/README.md b/lecoffre_ng/plans/README.md new file mode 100644 index 0000000..aaf2e39 --- /dev/null +++ b/lecoffre_ng/plans/README.md @@ -0,0 +1,39 @@ +# Plans Cursor (workflows) + +Les workflows sont en plans Cursor déclenchables, stockés au niveau utilisateur. + +## Emplacement + +**Plans** : `~/.cursor/plans/` (niveau utilisateur, utilisables depuis ce projet et autres) + +**Commandes** : `.cursor/commands/` (projet, invoquent les plans utilisateur) + +## Structure + +| Plan | Commande | Description | +|------|----------|-------------| +| workflow-cloture-evolution.plan.md | /cloture-evolution | Clôture évolution/correction | +| workflow-deploy.plan.md | /deploy | Déploiement test/pprod/prod | +| workflow-fix-lint.plan.md | /fix-lint | Correction lint | +| workflow-pousse.plan.md | /pousse | Commit et push | +| workflow-docupdate.plan.md | /docupdate | Mise à jour documentation | +| workflow-audit-security.plan.md | /audit-security | Audit sécurité | +| workflow-lintit.plan.md | /lintit | Qualité code | +| workflow-banch-align.plan.md | /banch-align | Aligner branches | +| workflow-banch-align-update.plan.md | /banch-align-update | Aligner branche actuelle | + +## Format Cursor + +- Frontmatter YAML : `name`, `overview`, `todos` (id, content, status), `isProject: false` +- Corps Markdown : phases, étapes, liens vers fichiers (chemins relatifs au workspace) + +## Déclenchement + +- **Commande** : Taper `/` dans le chat puis le nom (ex. `/cloture-evolution`, `/deploy test`) +- **Plan mode** : Shift+Tab pour créer un plan ; ouvrir `~/.cursor/plans/workflow-*.plan.md` et cliquer « Build » pour exécuter + +## Priorité + +Les commandes projet (`.cursor/commands/`) ont priorité sur les commandes globales (`~/.cursor/commands/`) pour les noms identiques. + +**Référence** : docs/WORKFLOWS_AND_COMPONENTS.md diff --git a/lecoffre_ng/rules/cloture-evolution.mdc b/lecoffre_ng/rules/cloture-evolution.mdc new file mode 100644 index 0000000..5077d4b --- /dev/null +++ b/lecoffre_ng/rules/cloture-evolution.mdc @@ -0,0 +1,116 @@ +--- +description: Workflow de clôture à exécuter à la fin de chaque évolution ou correction +alwaysApply: true +model: inherit +--- + +# Clôture évolution / correction + +À la fin de toute évolution ou correction, exécuter ce workflow dans l'ordre. Boucler chaque bloc jusqu'à stabilisation (rien à optimiser). **Ne jamais produire une réponse partielle** : répondre à toutes les questions de clôture et lancer les subagents/plans concernés. + +## Clôture obligatoire après évolution/correction + +Après chaque évolution ou correction, la réponse doit inclure **obligatoirement** : + +1. **Helpers :** des helpers sont-ils à utiliser ailleurs dans le code ? Des helpers existants auraient-ils pu être utilisés ? Y a-t-il des doublons de helpers ? + - Si oui : factoriser, réutiliser les helpers existants et supprimer/absorber les doublons immédiatement. + +2. **Texte i18n :** les textes sont ils centralisés ? `.secrets//env-full--for-bdd-injection.txt` est il à jour ? et test, pprod, prod ? + - Si non : fait le + +3. **Fallback :** As tu ajouté des fallbacks ? + - Si oui : supprime les fallback, si il y en avait avant et que tu peux les enlever sans regression, fait le. + +4. **Modifications similaires :** y a-t-il des modifications similaires à produire ailleurs dans le code ? + - Si oui : les implémenter immédiatement. + +5. **Optimisation / mutualisation / centralisation :** y a-t-il des optimisations possibles ? + - Si oui : les implémenter immédiatement. + +6. **Sécurité :** Des failles des sécurité sont elles posibles ? + - Si oui : corrige les + +7. **Code mort :** le code mort est-il nettoyé ? + - Si non : le nettoyer immédiatement. + +8. **Lint :** les fichiers corrigés sont-ils exempts d’erreurs de lint ? + - Réponse attendue : constat uniquement, **ne pas corriger** ici. + +9. **Types :** les vérifications de types du projet sont-elles OK ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +10. **Compilation :** le projet compile-t-il ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +11. **Documentation :** Rationaliser la documentation + +Si la réponse déclenche de nouvelles actions, cette checklist doit être rejouée en boucle jusqu’à stabilisation (code propre), avec lancement des subagents nécessaires pour exécuter les tâches. + +## Orchestration des subagents et plans + +Après une correction ou évolution, lancer en boucle jusqu'à succès : + +- **Lint** : Si erreurs détectées → `mcp_task` generalPurpose avec prompt fix-lint (ou exécution manuelle) ; boucler jusqu'à 0 erreur. +- **Déploiement** : Si déploiement requis et validé → `mcp_task` subagent_type="deploy" avec env ; en cas d'échec, orchestrer la correction (investigation, correctif, relance) sans s'arrêter. +- **Tests** : Compléter et lancer les tests concernés. + +Ne pas s'arrêter au rapport d'échec d'un subagent : prendre le relais, corriger, relancer. + +## 1. Tests + +- Compléter les tests manquants (user stories) +- Lancer les tests, corriger les échecs, boucler +- Rationaliser les tests (supprimer doublons, mutualiser) + +## 2. Types + +- Chercher si les types sont à optimiser (`npm run typecheck`, `npx tsc --noEmit`) +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 3. Reproductions + +- Chercher si des changements similaires doivent être reproduits ailleurs +- Si oui, implémenter et boucler jusqu'à rien à reproduire + +## 4. Factorisation / optimisation + +- Chercher factorisation, mutualisation, centralisation possibles +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 5. Lint + +- Chercher erreurs de lint (`npm run lint`, `ReadLints`) +- Si oui, corriger et boucler jusqu'à rien à corriger +- Sinon, vérifier si on peut être plus exigeant sur la qualité + +## 6. Sécurité + +- Chercher améliorations de sécurité possibles (`docs/CODE_SECURITY.md`) +- Si oui, implémenter et boucler jusqu'à rien à améliorer + +## 7. Documentation + +- Mettre à jour la doc : REX + descriptions (OPERATIONS.md, FRONTEND.md, CODE_STANDARDS.md selon périmètre) +- Rationaliser la doc (supprimer doublons, fusionner) + +## 8. Déploiement (après validation utilisateur) + +- Le script deploy.sh exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. +- Demander validation avant déploiement +- Déployer sur l'environnement de la branche locale (`deploy/scripts/build-and-deploy.sh`) +- Analyser les logs du déploiement +- Si corrections nécessaires, implémenter et boucler +- Si optimisations déploiement possibles, implémenter et boucler +- Si améliorations sécurité déploiement possibles, implémenter et boucler +- Mettre à jour la doc déploiement : REX + descriptions puis rationaliser + +## Plan et commande + +- **Plan** : `~/.cursor/plans/workflow-cloture-evolution.plan.md` (niveau utilisateur) +- **Commande** : `/cloture-evolution` (déclenche l'exécution du plan) + +## Outils + +- Lint : `mcp_task` generalPurpose avec prompt détaillé (fix-lint via mcp_task non fonctionnel) +- Déploiement : `mcp_task` subagent_type="deploy" ou exécution manuelle du script +- Tests : MCP browser, `user_stories/` diff --git a/lecoffre_ng/rules/development-autonomy.mdc b/lecoffre_ng/rules/development-autonomy.mdc new file mode 100644 index 0000000..5c4d0f1 --- /dev/null +++ b/lecoffre_ng/rules/development-autonomy.mdc @@ -0,0 +1,38 @@ +--- +description: Règles pour l'autonomie du développement avec user stories, patterns, qualité, sécurité et tests +alwaysApply: true +model: inherit +--- + +# Règles pour l'Autonomie du Développement + +## 📚 Références Documentation + +### User Stories + +* **Index :** Consulter `user_stories/INDEX.md` pour la liste complète des 43 user stories et leurs dépendances +* **Structure :** Chaque user story (`US*.md`) documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test +* **Autonomie :** Utiliser les user stories comme référence pour comprendre les parcours, créer les tests, implémenter les fonctionnalités +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` +* **Scripts :** Utiliser `user_stories/scripts/prepare-test-data.sh` + +### Patterns et Architecture + +* **Backend Patterns :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour les helpers centralisés (errorHandlers, errorLoggers, userHelpers) +* **Frontend Patterns :** Utiliser les hooks existants (useApiClient) et suivre le pattern Controller/Vue +* **Architecture :** Découper les features complexes en hooks contrôleurs + sous-composants présentateurs + +### Qualité et Sécurité + +* **Qualité :** Consulter `docs/CODE_STANDARDS.md` - Respecter les limites (250 lignes/fichier, 40 lignes/fonction) +* **Sécurité :** Consulter `docs/CODE_SECURITY.md` - Validation, secrets en base, pas de logging sensible + +### Tests + +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E +* **Navigation :** TOUJOURS utiliser la navigation du site, JAMAIS construire d'URLs manuellement +* **User Stories :** Référencer les user stories pour comprendre les parcours à tester + +### Documentation Fonctionnelle + +* **Référence :** Consulter `docs/CODE_STANDARDS.md` et `docs/FRONTEND.md` pour la structure et les fichiers du projet diff --git a/lecoffre_ng/rules/error-fixing.mdc b/lecoffre_ng/rules/error-fixing.mdc new file mode 100644 index 0000000..f1b07c0 --- /dev/null +++ b/lecoffre_ng/rules/error-fixing.mdc @@ -0,0 +1,6 @@ +--- +alwaysApply: true +model: inherit +--- + +corriger l'erreur et jamais contourner diff --git a/lecoffre_ng/rules/investigation-analysis.mdc b/lecoffre_ng/rules/investigation-analysis.mdc new file mode 100644 index 0000000..8d4eab4 --- /dev/null +++ b/lecoffre_ng/rules/investigation-analysis.mdc @@ -0,0 +1,13 @@ +--- +description: Règles d'investigation et d'analyse des problèmes (logs, données) +alwaysApply: true +model: inherit +--- + +# Investigation et analyse des problèmes + +## Logs et données + +* Analyser les problèmes avec les logs des backends (journalctl, fichiers de logs dans `logs/`) +* Analyser les données en base pour les investigations +* Les services sont host-native (pas de Docker) ; les logs sont accessibles via journalctl ou les fichiers dans `logs/` diff --git a/lecoffre_ng/rules/rules.mdc b/lecoffre_ng/rules/rules.mdc new file mode 100644 index 0000000..4e7ba27 --- /dev/null +++ b/lecoffre_ng/rules/rules.mdc @@ -0,0 +1,230 @@ +--- +description: Règles pour tous aussi pour l'IA et pour Cursor +alwaysApply: true +model: inherit +--- + +# Règles pour tous aussi pour l'IA + +## General + +### Communication et langues + +* Répond en français +* Code, documente le code, et fait les commits en anglais + +### Restrictions et interdictions + +* ne déclanche jamais la CI +* n'écris pas en base, jamais, les scripts doivent le faire +* ne masque pas les sorties des scripts +* ne fait jamais de certificats auto-signés +* ne modifie jamais les variables d'environnement +* ne configure jamais d'alternative htttp au lieu de https +* ne déploiement jamais de génération de certificats sans faire valider +* ne lance rien en arrière plan + +### Processus de développement + +* réponds en priorité aux questions posées +* avant d'implementer une solution demande la validation générales et pérennes +* ne corrige pas les bugs avant d'avoir identifier la root cause des problèmes et corrige avant tout la root cause des problèmes +* cherche la cause de la cause des problèmes jusqu'à la root cause +* il faut corriger les raisons des erreurs, cherche toujours à corriger les problèmes et ne cherche pas à les rendre acceptables +* bases toi en priorité sur des id ou des hash de id plutot que sur des libellés ou valeurs + +### Vérifications et qualité + +* **Clôture corrections/évolutions :** À la fin de toute correction ou évolution, répondre systématiquement aux questions suivantes et implémenter les améliorations identifiées : + * Modifications similaires à produire ailleurs dans le code ? + * Optimisations, mutualisations ou centralisations possibles ? + * Fichiers corrigés exempts d'erreurs de lint ? + * Vérification des types du projet OK ? + * Projet compile ? +* Si ces réponses ne sont pas fournies : les produire si pertinent et implémenter les améliorations identifiées (mutualisation, parties impactées). +* vérifie les fichiers après modification ou lecture pour : + * ajouter des logs + * supprimer du code mort + * ajouter des commentaires ou des questions en commentaires +* corrige les erreurs de lint par 10 en lançant à chaque fois au début et à la fin des série de 10 un test de turbopack jusqu'au passage OK de turbopack +* Dans les fichiers markdown respecter MD032 (blanks-around-lists), MD033 (no-inline-html), MD040 (fenced-code-language). Exécuter `npm run lint:markdown` pour vérifier. + +### Documentation + +* a la fin des corrections met à jour la documentation générale dans docs/ +* a la fin des évolutions met à jour la documentation générale dans docs/ +* quand tu corrige un problème documente dans `docs/OPERATIONS.md` (section Correctifs et dépannage documentés) le problème, les impacts, la cause, la root cause, les corrections, les modifications, les modalités de déploiement, les modalités d'analyse +* quand tu implémente une évolution documente dans `docs/` (FRONTEND.md, CODE_STANDARDS.md, OPERATIONS.md selon le périmètre) l'objectif, les impacts, les modifications, les modalités de déploiement, les modalités d'analyse + +## Préparation + +* **Répertoires :** Les application du services sont dans les autres dossiers à part `logs/`, `deploy/`, `todoFix/`, `docs/`, `user_stories/`. +* **Analyse fine :** Analyse du `README.md` et des `README.md` des applications. +* **Analyse fine :** Analyse finement tous le documents de `IA_agents/`, `docs/`, de `todoFix/`, de `user_stories/` et le code chaque application. +* **Analyse fine :** Analyse finement `deploy/scripts/bump-version.sh`. +* **Analyse fine :** Analyse finement `deploy/scripts/build-and-deploy.sh`. +* **User Stories :** Consulter `user_stories/INDEX.md` pour comprendre les 43 user stories et leurs dépendances. Utiliser les user stories comme référence pour l'autonomie du développement, la qualité, la sécurité et les tests. + +## ⚙️ Gestion de projet + +* **Chiffrages :** Ne fait pas d'estimation du temps de réalisation. +* **Planning :** Ne fait pas de roadmap. + +## 🤝 Collaboration et Workflow + +* **Ouverture aux modifications externes :** Comprendre et accepter que le projet puisse évoluer via des contributions extérieures. +* **Validation préalable :** Toute poussée de code (`git push`) ou déploiement doit être validée au préalable. +* **Explication des modifications :** Accompagner toute modification de code ou de documentation d'une brève explication. + +* **Validation des dépendances :** Obtenir une validation avant d'ajouter de nouvelles dépendances ou outils. +* **Résultats attendus :** Ne liste pas les résultats attendus dans tes synthèses. +* **Résultats :** Ne présume pas de résultats non testés, ne conclue pas sans avoir de preuve ou de validation que c'est OK. +* **Commits :** Les commits doivent être exhaustifs et synthétiques avec ``**Motivations :**`,`**Root causes :**`,`**Correctifs :**`,`**Evolutions :**`,`**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Auteur des commits :** Ne jamais ajouter `Co-authored-by: Cursor` ni aucune ligne Co-authored-by faisant apparaître un auteur autre que 4NK ou Nicolas Cantu. L'auteur du commit doit être 4NK ou Nicolas Cantu uniquement. +* **Résumés et synthèses :** Les résumés d'actions et tes synthèses doivent être exhaustifs et synthétiques avec `**Motivations :**`, `**Root causes :**`, `**Correctifs :**`, `**Evolutions :**`, `**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Rapports :** Ne fait pas de rapports apres tes actions. + +## ⚙️ Gestion de l'Environnement et des Configurations + +* **Accès aux `.env` :** Les fichiers `.env` de production sont inaccessibles et ne doivent pas être modifiés. +* **Mise à jour de `env.example` :** Maintenir `env.example` systématiquement à jour et ne jamais intégrer de paramétrage sensible directement dans le code. +* **Ports :** Ne modifie jamais les ports même si il ne sont pas ceux par défaut. +* **Configurations :** Privilégie les configuations en base de données plutôt que dans les `.env`. + +## 💻 Qualité du Code et Bonnes Pratiques + +* **Respect des conventions :** Adhérer au style de code et aux conventions existantes du projet. +* **Sécurité :** Prioriser la sécurité en ne codant jamais en dur des informations sensibles (y compris dans la documentation) et en validant systématiquement les entrées utilisateur. +* **Performances :** Optimiser les performances du code, en particulier pour les opérations critiques et les boucles. +* **Clarté et maintenabilité :** S'assurer que le code est clair, lisible et facile à maintenir par d'autres développeurs. + +#### Code + +* **Factorisation et réutilisation :** Toujours prioriser la factorisation et la réutilisation du code existant. Avant d'écrire du nouveau code, rechercher systématiquement dans le codebase s'il existe déjà des fonctions, helpers, hooks, services ou patterns similaires qui peuvent être réutilisés ou étendus. +* **Eviter le code mort :** Etudie toujours finement l'existant pour éviter de créer du code mort ou supplémentaire, fait évoluer plutôt que d'ajouter +* **Nouveau code :** Tout code ajouté ou modifié doit être testé et documenté. +* **Patterns réutilisables :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour utiliser les helpers et patterns existants (errorHandlers, userHelpers, useApiClient, etc.). Ne pas réinventer ce qui existe déjà. +* **Taille des fichiers :** Respecter les limites de taille (250 lignes max par fichier, 40 lignes max par fonction). max-params 4, max-depth 4, complexity 10, max-nested-callbacks 3. Documenter les exceptions dans docs/OPERATIONS.md (section dédiée) et commentaire // TODO(MAX_LINES) dans le code (voir docs/CODE_STANDARDS.md). +* **Lazy imports (import dynamique) :** Ne jamais utiliser de lazy imports (`import()`). Utiliser uniquement des imports statiques. Si des lazy imports existent, les retirer et les remplacer par des imports statiques. Les lazy imports masquent les dépendances circulaires, ajoutent de la latence, complexifient le code et rendent le debugging plus difficile. +* **Imports par défaut :** Toujours nommer les imports par défaut. Ne jamais utiliser d'imports anonymes (`import something from`). Utiliser des noms explicites pour tous les imports par défaut. +* **Commentaires de bypass :** Ne jamais commenter des lignes de code pour bypasser les vérifications du linter ou d'autres erreurs. Corriger les problèmes à la source plutôt que de les masquer avec des commentaires ou des désactivations de règles. + +#### 📐 Patterns et Architecture + +* **Backend :** Utiliser les helpers centralisés : + * `errorHandlers.ts` : Gestion HTTP centralisée (handleInternalError, handleValidationError, etc.) + * `errorLoggers.ts` : Logging standardisé (logError, logValidationError, etc.) + * `errorMessages.ts` : Messages d'erreur centralisés + * `userHelpers.ts` : Helpers utilisateurs (isSuperAdminUser, extractUserData, etc.) +* **Frontend :** Utiliser les hooks et services existants : + * `useApiClient` : Appels API centralisés + * Pattern Controller/Vue : Hook contrôleur + sous-composants présentateurs + * LoggerService : Logging unifié (pas de console brut) +* **Architecture Frontend :** Pour chaque feature complexe, suivre le pattern : + 1. Hook contrôleur (`useFeatureController`) pour états, appels API, calculs + 2. Sous-composants présentateurs pour découper l'UI + 3. Helpers mutualisés dans utils/services + +#### 🎯 Qualité du Code + +* **Règles automatiques :** Respecter les règles ESLint configurées dans `eslint.config.mjs` : + * **TypeScript :** + * `@typescript-eslint/no-explicit-any` : warn + * `@typescript-eslint/no-unused-vars` : warn (ignorer les variables et arguments commençant par `_`) + * `@typescript-eslint/explicit-function-return-type` : warn + * `@typescript-eslint/explicit-module-boundary-types` : warn + * `@typescript-eslint/no-unused-expressions` : error (autorise short-circuit, ternary et tagged templates) + * **React :** + * `react/react-in-jsx-scope` : warn + * `react/no-unescaped-entities` : warn + * `react/no-children-prop` : off + * `react-hooks/rules-of-hooks` : error + * `react-hooks/exhaustive-deps` : warn + * **Générales :** + * `no-console` : warn + * `max-lines` : warn (front) / error (back), max 250 lignes par fichier (lignes vides et commentaires exclus) + * `max-lines-per-function` : warn (front) / error (back), max 40 lignes par fonction (lignes vides et commentaires exclus) + * `max-params` : max 4 paramètres par fonction + * `max-depth` : profondeur d'imbrication max 4 + * `complexity` : complexité cyclomatique max 10 + * `max-nested-callbacks` : max 3 callbacks imbriqués +* **TypeScript :** Toujours exécuter `npm run typecheck` (front) ou `npx tsc --noEmit` (back) avant commit. +* **Build :** Vérifier que `npm run build` passe sans erreurs. +* **Dépassements :** Si un fichier/fonction dépasse les limites : + 1. Découper immédiatement si faisable + 2. Sinon, documenter dans docs/OPERATIONS.md avec plan de refactor + échéance + 3. Ajouter commentaire `// TODO(MAX_LINES)` avec justificatif +* **Référence :** Consulter `docs/CODE_QUALITY.md` pour les spécifications complètes. + +#### 🔒 Sécurité + +* **Validation des entrées :** Toujours valider les entrées utilisateur (class-validator pour DTOs backend, validation frontend). +* **Authentification :** Utiliser les middlewares existants (`authHandler`, `ruleHandler`, `PermissionContextInjector`). +* **Secrets :** Jamais de secrets en dur. Utiliser `system_configuration` en base de données. +* **Logging sensible :** Ne jamais logger de données sensibles (RIB, tokens, OTP). Utiliser Winston uniquement. +* **Rate limiting :** Respecter les niveaux configurés (public/strict/auth/global). +* **Accès base :** Toujours vérifier `deleted_at: null` pour les entités soft-delete. +* **Référence :** Consulter `docs/CODE_SECURITY.md` pour les spécifications complètes. + +#### 🧪 Tests + +* **Couverture des tests :** Rédiger des tests unitaires et d'intégration pour toute nouvelle fonctionnalité ou correction de bug. +* **Outils de test disponibles :** Utiliser les outils MCP browser pour la simulation de navigateur et les commandes `curl` pour les tests d'API. +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E. Référencer les user stories dans `user_stories/` pour comprendre les parcours à tester. +* **User Stories comme tests :** Consulter `user_stories/INDEX.md` et les fichiers `US*.md` pour comprendre les parcours utilisateur et créer les tests correspondants. +* **Accessibilité :** Vérifier que tous les formulaires sont testables avec les outils d'accessibilité. Consulter `user_stories/ACCESSIBILITY_TESTING.md` pour les modalités de test. +* **Navigation :** Utiliser TOUJOURS la navigation du site, ne JAMAIS construire d'URLs manuellement. Suivre le parcours utilisateur naturel. +* **Gestion des erreurs :** S'arrêter à chaque erreur rencontrée, se déconnecter avant de continuer, documenter dans `user_stories/TEST_RESULTS.md`. +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` pour les comptes disponibles. Utiliser `user_stories/scripts/prepare-test-data.sh` pour préparer les données de test. + +## 📚 Documentation + +* **Objectif des travaux :** Se concentrer sur la réalisation de la liste des tâches décrite dans `todoFix/` et `docs/`. +* **Structure de la documentation :** + * La documentation générale et pérenne se trouve dans `docs/`. + * Les features et corrections sont documentées dans `docs/` (OPERATIONS.md section Correctifs et dépannage, FRONTEND.md, CODE_STANDARDS.md) ; les tâches en cours dans `todoFix/`. + * Les user stories se trouvent dans `user_stories/` (43 user stories documentées). +* **User Stories :** Consulter `user_stories/INDEX.md` pour la liste complète et les dépendances. Chaque user story documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test. Utiliser comme référence pour l'autonomie du développement. +* **Qualité et sécurité :** Consulter `docs/CODE_QUALITY.md` et `docs/CODE_SECURITY.md` pour les spécifications complètes. +* **Utilisation de la documentation existante :** Ne pas ajouter de nouveaux documents, mais enrichir et mettre à jour l'existant. +* **Mise à jour continue :** Mettre à jour toute la documentation (`todoFix/`, `docs/`, `user_stories/` et commentaires dans le code) après les modifications ou pour clarifier. +* **Changelog :** Le fichier `CHANGELOG.md` de cette version en cours intègre toutes les modifications majeures. Ce contenu est repris dans la splash notice de l'application front. Les mises à jour mineures sont ajoutées au `CHANGELOG.md` sans enlever d'élément existant. + +## 📊 Logging et Gestion des Erreurs + +* **Centralisation des logs :** Centraliser les logs dans les répertoires `logs/` des applications et dans le répertoire `logs/` du projet pour les logs hors applications (déploiement par exemple) +* **Système de logging :** Implémenter une gestion d'erreurs robuste et utiliser le système de logging Winston pour toutes les sorties (info, warn, error, debug, etc.). +* **Traçabilité :** Logger toutes les valeurs, états clés et retours d'API. + +## 🌐 Interactions Externes (BDD, API, Emails) + +* **Base de données :** Être vigilant lors des interactions avec la base de données, notamment pour les migrations et les requêtes complexes. +* **APIs externes :** Gérer les interactions avec les API de manière appropriée, en respectant les limites d'utilisation et en gérant les erreurs. +* **Emails :** Gérer les envois d'emails de manière appropriée pour éviter le spam et gérer les erreurs. + +## 🚀 Déploiement + +* **Préparation du déploiement :** Décrire et préparer le déploiement des correctifs et des évolutions. +* **Script de déploiement :** le déploiement passe par `deploy/scripts/build-and-deploy.sh`, ne masque pas la sortie (pas de 2>&1 par exemple). +* **Bilan de déploiement :** ne fait pas de bilan de déploiement. +* **Lancement :** ne lance aucun déploiement sans demander avant + +## 🚨 Gestion des Problèmes + +* **Résolution directe :** En cas de problème (toutes criticités), ne jamais simplifier, contourner, forcer un résultat en dur, ou créer des bouchons. Le problème doit être résolu à sa racine. + +## 🗄️ Gestion des Fichiers + +* **Versions uniques :** Ne pas créer de versions alternatives des fichiers. +* **Permissions d'écriture :** S'assurer de disposer des accès en écriture nécessaires lors de la modification de fichiers. + +## Mise à jour de ces règles + +* **Propositions d'ajouts :** Quand tu apprends de nouvelles instructions qui te semblent pertinentes pour ces règles, propose de les ajouter. + +* **Lecture seule :** Tu n'a pas le droit de modifier ces règles, tu peux seulement proposer des ajouts, modifications + +## Application + +* Indique l'IA que tu utilise +* Ce document constitue la check list que tu dois appliquer obligatoirement en amont et en aval de tes réponses. diff --git a/lecoffre_ng/ssh_config b/lecoffre_ng/ssh_config new file mode 100644 index 0000000..4b47ab4 --- /dev/null +++ b/lecoffre_ng/ssh_config @@ -0,0 +1,72 @@ +# SSH Configuration for Cursor - Infrastructure Cloud 4NK +# This file contains SSH configurations for all servers in the infrastructure + +# Proxy server (accès direct) +Host proxy + HostName 4nk.myftp.biz + User ncantu + Port 22 + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + +# Test server (via proxy) +Host test + HostName 192.168.1.101 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Pre-production server (via proxy) +Host pprod + HostName 192.168.1.102 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Production server (via proxy) +Host prod + HostName 192.168.1.103 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Services server (via proxy) +Host services + HostName 192.168.1.104 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Bitcoin server (via proxy) +Host bitcoin + HostName 192.168.1.105 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new diff --git a/lecoffre_ng_pprod/agents/fix-lint.md b/lecoffre_ng_pprod/agents/fix-lint.md new file mode 120000 index 0000000..865cd45 --- /dev/null +++ b/lecoffre_ng_pprod/agents/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/agents/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng_pprod/commands/audit-security.md b/lecoffre_ng_pprod/commands/audit-security.md new file mode 100644 index 0000000..8d90b47 --- /dev/null +++ b/lecoffre_ng_pprod/commands/audit-security.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Audit sécurité + +Exécute le plan `~/.cursor/plans/workflow-audit-security.plan.md`. + +Lis le fichier plan. Applique la méthodologie OWASP : analyse surface d'attaque, revue Top 10, évaluation risque, recommandations. Format rapport : [SEVERITY] Titre ; Location ; Description ; Impact ; Reproduction ; Remediation. diff --git a/lecoffre_ng_pprod/commands/banch-align-update.md b/lecoffre_ng_pprod/commands/banch-align-update.md new file mode 100644 index 0000000..1cb066c --- /dev/null +++ b/lecoffre_ng_pprod/commands/banch-align-update.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branche actuelle (banch-align-update) + +Exécute le plan `~/.cursor/plans/workflow-banch-align-update.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align-update test`). Si absent, demande à l'utilisateur. Attends confirmation avant stash et alignement. diff --git a/lecoffre_ng_pprod/commands/banch-align.md b/lecoffre_ng_pprod/commands/banch-align.md new file mode 100644 index 0000000..477703b --- /dev/null +++ b/lecoffre_ng_pprod/commands/banch-align.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branches (banch-align) + +Exécute le plan `~/.cursor/plans/workflow-banch-align.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align test`). Si absent, demande à l'utilisateur. diff --git a/lecoffre_ng_pprod/commands/cloture-evolution.md b/lecoffre_ng_pprod/commands/cloture-evolution.md new file mode 100644 index 0000000..c9a13e9 --- /dev/null +++ b/lecoffre_ng_pprod/commands/cloture-evolution.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Clôture évolution / correction + +Exécute le plan `~/.cursor/plans/workflow-cloture-evolution.plan.md`. + +Lis le fichier plan, suis les phases et todos dans l'ordre. Boucle chaque bloc jusqu'à stabilisation (rien à optimiser). Demande validation avant déploiement. diff --git a/lecoffre_ng_pprod/commands/deploy.md b/lecoffre_ng_pprod/commands/deploy.md new file mode 100644 index 0000000..e5f7521 --- /dev/null +++ b/lecoffre_ng_pprod/commands/deploy.md @@ -0,0 +1,23 @@ +--- +model: inherit +--- +# Déployer (test, pprod, prod) + +L'environnement `` est passé en paramètre (ex. `/deploy test`). Si absent, demander à l'utilisateur. + +**Action** : Exécuter le script de déploiement depuis la racine du projet : +```bash +./deploy/scripts_v2/deploy.sh +``` +Le script s'exécute **localement** et orchestre le déploiement **à distance** (SSH vers la cible, git pull, build, restart services). Ne pas tenter de déployer manuellement ou via d'autres chemins. + +**En cas d'échec** : Orchestrer la correction automatique (boucle jusqu'à succès ou impossibilité). Ne pas s'arrêter au rapport d'échec : +1. Analyser la cause (logs backend, journalctl sur cible, présence fichiers dans le repo et dans dist sur cible) +2. Corriger la root cause (code, imports, config, build) sans contournement +3. Committer et pousser si modifications +4. Relancer `./deploy/scripts_v2/deploy.sh ` +5. Répéter tant que l'échec persiste et qu'une correction est identifiée + +Si délégation au subagent deploy : en cas de retour d'échec, l'agent principal prend le relais et exécute cette orchestration (ne pas se contenter de transmettre l'échec à l'utilisateur). + +**Concurrence** : Le script exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents (lint, fix-lint, typecheck, turbopack) dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. `DEPLOY_SKIP_CONCURRENCY_CHECK=1` pour désactiver. diff --git a/lecoffre_ng_pprod/commands/docupdate.md b/lecoffre_ng_pprod/commands/docupdate.md new file mode 100644 index 0000000..31bf3b7 --- /dev/null +++ b/lecoffre_ng_pprod/commands/docupdate.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Mise à jour documentation + +Exécute le plan `~/.cursor/plans/workflow-docupdate.plan.md`. + +Lis le fichier plan. Suis les phases : docs/features extract, docs/fixKnowledge extract, docs/ cleanup. diff --git a/lecoffre_ng_pprod/commands/fix-lint.md b/lecoffre_ng_pprod/commands/fix-lint.md new file mode 120000 index 0000000..d73d679 --- /dev/null +++ b/lecoffre_ng_pprod/commands/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/commands/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng_pprod/commands/lintit.md b/lecoffre_ng_pprod/commands/lintit.md new file mode 100644 index 0000000..53e0a15 --- /dev/null +++ b/lecoffre_ng_pprod/commands/lintit.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Lintit (qualité code) + +Exécute le plan `~/.cursor/plans/workflow-lintit.plan.md`. + +Lis le fichier plan. Vérifie les règles qualité, liste les actions à mener, corrige erreurs et warnings lint sans contournement. diff --git a/lecoffre_ng_pprod/commands/pousse.md b/lecoffre_ng_pprod/commands/pousse.md new file mode 100644 index 0000000..b313121 --- /dev/null +++ b/lecoffre_ng_pprod/commands/pousse.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Commit et push (pousse) + +Exécute le plan `~/.cursor/plans/workflow-pousse.plan.md`. + +Lis le fichier plan. Propose le message de commit au format structuré (Motivations, Root causes, Correctifs, Evolutions, Pages affectées). Attends validation avant d'exécuter git commit et git push. diff --git a/lecoffre_ng_pprod/plans/README.md b/lecoffre_ng_pprod/plans/README.md new file mode 100644 index 0000000..aaf2e39 --- /dev/null +++ b/lecoffre_ng_pprod/plans/README.md @@ -0,0 +1,39 @@ +# Plans Cursor (workflows) + +Les workflows sont en plans Cursor déclenchables, stockés au niveau utilisateur. + +## Emplacement + +**Plans** : `~/.cursor/plans/` (niveau utilisateur, utilisables depuis ce projet et autres) + +**Commandes** : `.cursor/commands/` (projet, invoquent les plans utilisateur) + +## Structure + +| Plan | Commande | Description | +|------|----------|-------------| +| workflow-cloture-evolution.plan.md | /cloture-evolution | Clôture évolution/correction | +| workflow-deploy.plan.md | /deploy | Déploiement test/pprod/prod | +| workflow-fix-lint.plan.md | /fix-lint | Correction lint | +| workflow-pousse.plan.md | /pousse | Commit et push | +| workflow-docupdate.plan.md | /docupdate | Mise à jour documentation | +| workflow-audit-security.plan.md | /audit-security | Audit sécurité | +| workflow-lintit.plan.md | /lintit | Qualité code | +| workflow-banch-align.plan.md | /banch-align | Aligner branches | +| workflow-banch-align-update.plan.md | /banch-align-update | Aligner branche actuelle | + +## Format Cursor + +- Frontmatter YAML : `name`, `overview`, `todos` (id, content, status), `isProject: false` +- Corps Markdown : phases, étapes, liens vers fichiers (chemins relatifs au workspace) + +## Déclenchement + +- **Commande** : Taper `/` dans le chat puis le nom (ex. `/cloture-evolution`, `/deploy test`) +- **Plan mode** : Shift+Tab pour créer un plan ; ouvrir `~/.cursor/plans/workflow-*.plan.md` et cliquer « Build » pour exécuter + +## Priorité + +Les commandes projet (`.cursor/commands/`) ont priorité sur les commandes globales (`~/.cursor/commands/`) pour les noms identiques. + +**Référence** : docs/WORKFLOWS_AND_COMPONENTS.md diff --git a/lecoffre_ng_pprod/rules/cloture-evolution.mdc b/lecoffre_ng_pprod/rules/cloture-evolution.mdc new file mode 100644 index 0000000..5077d4b --- /dev/null +++ b/lecoffre_ng_pprod/rules/cloture-evolution.mdc @@ -0,0 +1,116 @@ +--- +description: Workflow de clôture à exécuter à la fin de chaque évolution ou correction +alwaysApply: true +model: inherit +--- + +# Clôture évolution / correction + +À la fin de toute évolution ou correction, exécuter ce workflow dans l'ordre. Boucler chaque bloc jusqu'à stabilisation (rien à optimiser). **Ne jamais produire une réponse partielle** : répondre à toutes les questions de clôture et lancer les subagents/plans concernés. + +## Clôture obligatoire après évolution/correction + +Après chaque évolution ou correction, la réponse doit inclure **obligatoirement** : + +1. **Helpers :** des helpers sont-ils à utiliser ailleurs dans le code ? Des helpers existants auraient-ils pu être utilisés ? Y a-t-il des doublons de helpers ? + - Si oui : factoriser, réutiliser les helpers existants et supprimer/absorber les doublons immédiatement. + +2. **Texte i18n :** les textes sont ils centralisés ? `.secrets//env-full--for-bdd-injection.txt` est il à jour ? et test, pprod, prod ? + - Si non : fait le + +3. **Fallback :** As tu ajouté des fallbacks ? + - Si oui : supprime les fallback, si il y en avait avant et que tu peux les enlever sans regression, fait le. + +4. **Modifications similaires :** y a-t-il des modifications similaires à produire ailleurs dans le code ? + - Si oui : les implémenter immédiatement. + +5. **Optimisation / mutualisation / centralisation :** y a-t-il des optimisations possibles ? + - Si oui : les implémenter immédiatement. + +6. **Sécurité :** Des failles des sécurité sont elles posibles ? + - Si oui : corrige les + +7. **Code mort :** le code mort est-il nettoyé ? + - Si non : le nettoyer immédiatement. + +8. **Lint :** les fichiers corrigés sont-ils exempts d’erreurs de lint ? + - Réponse attendue : constat uniquement, **ne pas corriger** ici. + +9. **Types :** les vérifications de types du projet sont-elles OK ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +10. **Compilation :** le projet compile-t-il ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +11. **Documentation :** Rationaliser la documentation + +Si la réponse déclenche de nouvelles actions, cette checklist doit être rejouée en boucle jusqu’à stabilisation (code propre), avec lancement des subagents nécessaires pour exécuter les tâches. + +## Orchestration des subagents et plans + +Après une correction ou évolution, lancer en boucle jusqu'à succès : + +- **Lint** : Si erreurs détectées → `mcp_task` generalPurpose avec prompt fix-lint (ou exécution manuelle) ; boucler jusqu'à 0 erreur. +- **Déploiement** : Si déploiement requis et validé → `mcp_task` subagent_type="deploy" avec env ; en cas d'échec, orchestrer la correction (investigation, correctif, relance) sans s'arrêter. +- **Tests** : Compléter et lancer les tests concernés. + +Ne pas s'arrêter au rapport d'échec d'un subagent : prendre le relais, corriger, relancer. + +## 1. Tests + +- Compléter les tests manquants (user stories) +- Lancer les tests, corriger les échecs, boucler +- Rationaliser les tests (supprimer doublons, mutualiser) + +## 2. Types + +- Chercher si les types sont à optimiser (`npm run typecheck`, `npx tsc --noEmit`) +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 3. Reproductions + +- Chercher si des changements similaires doivent être reproduits ailleurs +- Si oui, implémenter et boucler jusqu'à rien à reproduire + +## 4. Factorisation / optimisation + +- Chercher factorisation, mutualisation, centralisation possibles +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 5. Lint + +- Chercher erreurs de lint (`npm run lint`, `ReadLints`) +- Si oui, corriger et boucler jusqu'à rien à corriger +- Sinon, vérifier si on peut être plus exigeant sur la qualité + +## 6. Sécurité + +- Chercher améliorations de sécurité possibles (`docs/CODE_SECURITY.md`) +- Si oui, implémenter et boucler jusqu'à rien à améliorer + +## 7. Documentation + +- Mettre à jour la doc : REX + descriptions (OPERATIONS.md, FRONTEND.md, CODE_STANDARDS.md selon périmètre) +- Rationaliser la doc (supprimer doublons, fusionner) + +## 8. Déploiement (après validation utilisateur) + +- Le script deploy.sh exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. +- Demander validation avant déploiement +- Déployer sur l'environnement de la branche locale (`deploy/scripts/build-and-deploy.sh`) +- Analyser les logs du déploiement +- Si corrections nécessaires, implémenter et boucler +- Si optimisations déploiement possibles, implémenter et boucler +- Si améliorations sécurité déploiement possibles, implémenter et boucler +- Mettre à jour la doc déploiement : REX + descriptions puis rationaliser + +## Plan et commande + +- **Plan** : `~/.cursor/plans/workflow-cloture-evolution.plan.md` (niveau utilisateur) +- **Commande** : `/cloture-evolution` (déclenche l'exécution du plan) + +## Outils + +- Lint : `mcp_task` generalPurpose avec prompt détaillé (fix-lint via mcp_task non fonctionnel) +- Déploiement : `mcp_task` subagent_type="deploy" ou exécution manuelle du script +- Tests : MCP browser, `user_stories/` diff --git a/lecoffre_ng_pprod/rules/development-autonomy.mdc b/lecoffre_ng_pprod/rules/development-autonomy.mdc new file mode 100644 index 0000000..5c4d0f1 --- /dev/null +++ b/lecoffre_ng_pprod/rules/development-autonomy.mdc @@ -0,0 +1,38 @@ +--- +description: Règles pour l'autonomie du développement avec user stories, patterns, qualité, sécurité et tests +alwaysApply: true +model: inherit +--- + +# Règles pour l'Autonomie du Développement + +## 📚 Références Documentation + +### User Stories + +* **Index :** Consulter `user_stories/INDEX.md` pour la liste complète des 43 user stories et leurs dépendances +* **Structure :** Chaque user story (`US*.md`) documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test +* **Autonomie :** Utiliser les user stories comme référence pour comprendre les parcours, créer les tests, implémenter les fonctionnalités +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` +* **Scripts :** Utiliser `user_stories/scripts/prepare-test-data.sh` + +### Patterns et Architecture + +* **Backend Patterns :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour les helpers centralisés (errorHandlers, errorLoggers, userHelpers) +* **Frontend Patterns :** Utiliser les hooks existants (useApiClient) et suivre le pattern Controller/Vue +* **Architecture :** Découper les features complexes en hooks contrôleurs + sous-composants présentateurs + +### Qualité et Sécurité + +* **Qualité :** Consulter `docs/CODE_STANDARDS.md` - Respecter les limites (250 lignes/fichier, 40 lignes/fonction) +* **Sécurité :** Consulter `docs/CODE_SECURITY.md` - Validation, secrets en base, pas de logging sensible + +### Tests + +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E +* **Navigation :** TOUJOURS utiliser la navigation du site, JAMAIS construire d'URLs manuellement +* **User Stories :** Référencer les user stories pour comprendre les parcours à tester + +### Documentation Fonctionnelle + +* **Référence :** Consulter `docs/CODE_STANDARDS.md` et `docs/FRONTEND.md` pour la structure et les fichiers du projet diff --git a/lecoffre_ng_pprod/rules/error-fixing.mdc b/lecoffre_ng_pprod/rules/error-fixing.mdc new file mode 100644 index 0000000..f1b07c0 --- /dev/null +++ b/lecoffre_ng_pprod/rules/error-fixing.mdc @@ -0,0 +1,6 @@ +--- +alwaysApply: true +model: inherit +--- + +corriger l'erreur et jamais contourner diff --git a/lecoffre_ng_pprod/rules/investigation-analysis.mdc b/lecoffre_ng_pprod/rules/investigation-analysis.mdc new file mode 100644 index 0000000..8d4eab4 --- /dev/null +++ b/lecoffre_ng_pprod/rules/investigation-analysis.mdc @@ -0,0 +1,13 @@ +--- +description: Règles d'investigation et d'analyse des problèmes (logs, données) +alwaysApply: true +model: inherit +--- + +# Investigation et analyse des problèmes + +## Logs et données + +* Analyser les problèmes avec les logs des backends (journalctl, fichiers de logs dans `logs/`) +* Analyser les données en base pour les investigations +* Les services sont host-native (pas de Docker) ; les logs sont accessibles via journalctl ou les fichiers dans `logs/` diff --git a/lecoffre_ng_pprod/rules/rules.mdc b/lecoffre_ng_pprod/rules/rules.mdc new file mode 100644 index 0000000..4e7ba27 --- /dev/null +++ b/lecoffre_ng_pprod/rules/rules.mdc @@ -0,0 +1,230 @@ +--- +description: Règles pour tous aussi pour l'IA et pour Cursor +alwaysApply: true +model: inherit +--- + +# Règles pour tous aussi pour l'IA + +## General + +### Communication et langues + +* Répond en français +* Code, documente le code, et fait les commits en anglais + +### Restrictions et interdictions + +* ne déclanche jamais la CI +* n'écris pas en base, jamais, les scripts doivent le faire +* ne masque pas les sorties des scripts +* ne fait jamais de certificats auto-signés +* ne modifie jamais les variables d'environnement +* ne configure jamais d'alternative htttp au lieu de https +* ne déploiement jamais de génération de certificats sans faire valider +* ne lance rien en arrière plan + +### Processus de développement + +* réponds en priorité aux questions posées +* avant d'implementer une solution demande la validation générales et pérennes +* ne corrige pas les bugs avant d'avoir identifier la root cause des problèmes et corrige avant tout la root cause des problèmes +* cherche la cause de la cause des problèmes jusqu'à la root cause +* il faut corriger les raisons des erreurs, cherche toujours à corriger les problèmes et ne cherche pas à les rendre acceptables +* bases toi en priorité sur des id ou des hash de id plutot que sur des libellés ou valeurs + +### Vérifications et qualité + +* **Clôture corrections/évolutions :** À la fin de toute correction ou évolution, répondre systématiquement aux questions suivantes et implémenter les améliorations identifiées : + * Modifications similaires à produire ailleurs dans le code ? + * Optimisations, mutualisations ou centralisations possibles ? + * Fichiers corrigés exempts d'erreurs de lint ? + * Vérification des types du projet OK ? + * Projet compile ? +* Si ces réponses ne sont pas fournies : les produire si pertinent et implémenter les améliorations identifiées (mutualisation, parties impactées). +* vérifie les fichiers après modification ou lecture pour : + * ajouter des logs + * supprimer du code mort + * ajouter des commentaires ou des questions en commentaires +* corrige les erreurs de lint par 10 en lançant à chaque fois au début et à la fin des série de 10 un test de turbopack jusqu'au passage OK de turbopack +* Dans les fichiers markdown respecter MD032 (blanks-around-lists), MD033 (no-inline-html), MD040 (fenced-code-language). Exécuter `npm run lint:markdown` pour vérifier. + +### Documentation + +* a la fin des corrections met à jour la documentation générale dans docs/ +* a la fin des évolutions met à jour la documentation générale dans docs/ +* quand tu corrige un problème documente dans `docs/OPERATIONS.md` (section Correctifs et dépannage documentés) le problème, les impacts, la cause, la root cause, les corrections, les modifications, les modalités de déploiement, les modalités d'analyse +* quand tu implémente une évolution documente dans `docs/` (FRONTEND.md, CODE_STANDARDS.md, OPERATIONS.md selon le périmètre) l'objectif, les impacts, les modifications, les modalités de déploiement, les modalités d'analyse + +## Préparation + +* **Répertoires :** Les application du services sont dans les autres dossiers à part `logs/`, `deploy/`, `todoFix/`, `docs/`, `user_stories/`. +* **Analyse fine :** Analyse du `README.md` et des `README.md` des applications. +* **Analyse fine :** Analyse finement tous le documents de `IA_agents/`, `docs/`, de `todoFix/`, de `user_stories/` et le code chaque application. +* **Analyse fine :** Analyse finement `deploy/scripts/bump-version.sh`. +* **Analyse fine :** Analyse finement `deploy/scripts/build-and-deploy.sh`. +* **User Stories :** Consulter `user_stories/INDEX.md` pour comprendre les 43 user stories et leurs dépendances. Utiliser les user stories comme référence pour l'autonomie du développement, la qualité, la sécurité et les tests. + +## ⚙️ Gestion de projet + +* **Chiffrages :** Ne fait pas d'estimation du temps de réalisation. +* **Planning :** Ne fait pas de roadmap. + +## 🤝 Collaboration et Workflow + +* **Ouverture aux modifications externes :** Comprendre et accepter que le projet puisse évoluer via des contributions extérieures. +* **Validation préalable :** Toute poussée de code (`git push`) ou déploiement doit être validée au préalable. +* **Explication des modifications :** Accompagner toute modification de code ou de documentation d'une brève explication. + +* **Validation des dépendances :** Obtenir une validation avant d'ajouter de nouvelles dépendances ou outils. +* **Résultats attendus :** Ne liste pas les résultats attendus dans tes synthèses. +* **Résultats :** Ne présume pas de résultats non testés, ne conclue pas sans avoir de preuve ou de validation que c'est OK. +* **Commits :** Les commits doivent être exhaustifs et synthétiques avec ``**Motivations :**`,`**Root causes :**`,`**Correctifs :**`,`**Evolutions :**`,`**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Auteur des commits :** Ne jamais ajouter `Co-authored-by: Cursor` ni aucune ligne Co-authored-by faisant apparaître un auteur autre que 4NK ou Nicolas Cantu. L'auteur du commit doit être 4NK ou Nicolas Cantu uniquement. +* **Résumés et synthèses :** Les résumés d'actions et tes synthèses doivent être exhaustifs et synthétiques avec `**Motivations :**`, `**Root causes :**`, `**Correctifs :**`, `**Evolutions :**`, `**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Rapports :** Ne fait pas de rapports apres tes actions. + +## ⚙️ Gestion de l'Environnement et des Configurations + +* **Accès aux `.env` :** Les fichiers `.env` de production sont inaccessibles et ne doivent pas être modifiés. +* **Mise à jour de `env.example` :** Maintenir `env.example` systématiquement à jour et ne jamais intégrer de paramétrage sensible directement dans le code. +* **Ports :** Ne modifie jamais les ports même si il ne sont pas ceux par défaut. +* **Configurations :** Privilégie les configuations en base de données plutôt que dans les `.env`. + +## 💻 Qualité du Code et Bonnes Pratiques + +* **Respect des conventions :** Adhérer au style de code et aux conventions existantes du projet. +* **Sécurité :** Prioriser la sécurité en ne codant jamais en dur des informations sensibles (y compris dans la documentation) et en validant systématiquement les entrées utilisateur. +* **Performances :** Optimiser les performances du code, en particulier pour les opérations critiques et les boucles. +* **Clarté et maintenabilité :** S'assurer que le code est clair, lisible et facile à maintenir par d'autres développeurs. + +#### Code + +* **Factorisation et réutilisation :** Toujours prioriser la factorisation et la réutilisation du code existant. Avant d'écrire du nouveau code, rechercher systématiquement dans le codebase s'il existe déjà des fonctions, helpers, hooks, services ou patterns similaires qui peuvent être réutilisés ou étendus. +* **Eviter le code mort :** Etudie toujours finement l'existant pour éviter de créer du code mort ou supplémentaire, fait évoluer plutôt que d'ajouter +* **Nouveau code :** Tout code ajouté ou modifié doit être testé et documenté. +* **Patterns réutilisables :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour utiliser les helpers et patterns existants (errorHandlers, userHelpers, useApiClient, etc.). Ne pas réinventer ce qui existe déjà. +* **Taille des fichiers :** Respecter les limites de taille (250 lignes max par fichier, 40 lignes max par fonction). max-params 4, max-depth 4, complexity 10, max-nested-callbacks 3. Documenter les exceptions dans docs/OPERATIONS.md (section dédiée) et commentaire // TODO(MAX_LINES) dans le code (voir docs/CODE_STANDARDS.md). +* **Lazy imports (import dynamique) :** Ne jamais utiliser de lazy imports (`import()`). Utiliser uniquement des imports statiques. Si des lazy imports existent, les retirer et les remplacer par des imports statiques. Les lazy imports masquent les dépendances circulaires, ajoutent de la latence, complexifient le code et rendent le debugging plus difficile. +* **Imports par défaut :** Toujours nommer les imports par défaut. Ne jamais utiliser d'imports anonymes (`import something from`). Utiliser des noms explicites pour tous les imports par défaut. +* **Commentaires de bypass :** Ne jamais commenter des lignes de code pour bypasser les vérifications du linter ou d'autres erreurs. Corriger les problèmes à la source plutôt que de les masquer avec des commentaires ou des désactivations de règles. + +#### 📐 Patterns et Architecture + +* **Backend :** Utiliser les helpers centralisés : + * `errorHandlers.ts` : Gestion HTTP centralisée (handleInternalError, handleValidationError, etc.) + * `errorLoggers.ts` : Logging standardisé (logError, logValidationError, etc.) + * `errorMessages.ts` : Messages d'erreur centralisés + * `userHelpers.ts` : Helpers utilisateurs (isSuperAdminUser, extractUserData, etc.) +* **Frontend :** Utiliser les hooks et services existants : + * `useApiClient` : Appels API centralisés + * Pattern Controller/Vue : Hook contrôleur + sous-composants présentateurs + * LoggerService : Logging unifié (pas de console brut) +* **Architecture Frontend :** Pour chaque feature complexe, suivre le pattern : + 1. Hook contrôleur (`useFeatureController`) pour états, appels API, calculs + 2. Sous-composants présentateurs pour découper l'UI + 3. Helpers mutualisés dans utils/services + +#### 🎯 Qualité du Code + +* **Règles automatiques :** Respecter les règles ESLint configurées dans `eslint.config.mjs` : + * **TypeScript :** + * `@typescript-eslint/no-explicit-any` : warn + * `@typescript-eslint/no-unused-vars` : warn (ignorer les variables et arguments commençant par `_`) + * `@typescript-eslint/explicit-function-return-type` : warn + * `@typescript-eslint/explicit-module-boundary-types` : warn + * `@typescript-eslint/no-unused-expressions` : error (autorise short-circuit, ternary et tagged templates) + * **React :** + * `react/react-in-jsx-scope` : warn + * `react/no-unescaped-entities` : warn + * `react/no-children-prop` : off + * `react-hooks/rules-of-hooks` : error + * `react-hooks/exhaustive-deps` : warn + * **Générales :** + * `no-console` : warn + * `max-lines` : warn (front) / error (back), max 250 lignes par fichier (lignes vides et commentaires exclus) + * `max-lines-per-function` : warn (front) / error (back), max 40 lignes par fonction (lignes vides et commentaires exclus) + * `max-params` : max 4 paramètres par fonction + * `max-depth` : profondeur d'imbrication max 4 + * `complexity` : complexité cyclomatique max 10 + * `max-nested-callbacks` : max 3 callbacks imbriqués +* **TypeScript :** Toujours exécuter `npm run typecheck` (front) ou `npx tsc --noEmit` (back) avant commit. +* **Build :** Vérifier que `npm run build` passe sans erreurs. +* **Dépassements :** Si un fichier/fonction dépasse les limites : + 1. Découper immédiatement si faisable + 2. Sinon, documenter dans docs/OPERATIONS.md avec plan de refactor + échéance + 3. Ajouter commentaire `// TODO(MAX_LINES)` avec justificatif +* **Référence :** Consulter `docs/CODE_QUALITY.md` pour les spécifications complètes. + +#### 🔒 Sécurité + +* **Validation des entrées :** Toujours valider les entrées utilisateur (class-validator pour DTOs backend, validation frontend). +* **Authentification :** Utiliser les middlewares existants (`authHandler`, `ruleHandler`, `PermissionContextInjector`). +* **Secrets :** Jamais de secrets en dur. Utiliser `system_configuration` en base de données. +* **Logging sensible :** Ne jamais logger de données sensibles (RIB, tokens, OTP). Utiliser Winston uniquement. +* **Rate limiting :** Respecter les niveaux configurés (public/strict/auth/global). +* **Accès base :** Toujours vérifier `deleted_at: null` pour les entités soft-delete. +* **Référence :** Consulter `docs/CODE_SECURITY.md` pour les spécifications complètes. + +#### 🧪 Tests + +* **Couverture des tests :** Rédiger des tests unitaires et d'intégration pour toute nouvelle fonctionnalité ou correction de bug. +* **Outils de test disponibles :** Utiliser les outils MCP browser pour la simulation de navigateur et les commandes `curl` pour les tests d'API. +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E. Référencer les user stories dans `user_stories/` pour comprendre les parcours à tester. +* **User Stories comme tests :** Consulter `user_stories/INDEX.md` et les fichiers `US*.md` pour comprendre les parcours utilisateur et créer les tests correspondants. +* **Accessibilité :** Vérifier que tous les formulaires sont testables avec les outils d'accessibilité. Consulter `user_stories/ACCESSIBILITY_TESTING.md` pour les modalités de test. +* **Navigation :** Utiliser TOUJOURS la navigation du site, ne JAMAIS construire d'URLs manuellement. Suivre le parcours utilisateur naturel. +* **Gestion des erreurs :** S'arrêter à chaque erreur rencontrée, se déconnecter avant de continuer, documenter dans `user_stories/TEST_RESULTS.md`. +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` pour les comptes disponibles. Utiliser `user_stories/scripts/prepare-test-data.sh` pour préparer les données de test. + +## 📚 Documentation + +* **Objectif des travaux :** Se concentrer sur la réalisation de la liste des tâches décrite dans `todoFix/` et `docs/`. +* **Structure de la documentation :** + * La documentation générale et pérenne se trouve dans `docs/`. + * Les features et corrections sont documentées dans `docs/` (OPERATIONS.md section Correctifs et dépannage, FRONTEND.md, CODE_STANDARDS.md) ; les tâches en cours dans `todoFix/`. + * Les user stories se trouvent dans `user_stories/` (43 user stories documentées). +* **User Stories :** Consulter `user_stories/INDEX.md` pour la liste complète et les dépendances. Chaque user story documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test. Utiliser comme référence pour l'autonomie du développement. +* **Qualité et sécurité :** Consulter `docs/CODE_QUALITY.md` et `docs/CODE_SECURITY.md` pour les spécifications complètes. +* **Utilisation de la documentation existante :** Ne pas ajouter de nouveaux documents, mais enrichir et mettre à jour l'existant. +* **Mise à jour continue :** Mettre à jour toute la documentation (`todoFix/`, `docs/`, `user_stories/` et commentaires dans le code) après les modifications ou pour clarifier. +* **Changelog :** Le fichier `CHANGELOG.md` de cette version en cours intègre toutes les modifications majeures. Ce contenu est repris dans la splash notice de l'application front. Les mises à jour mineures sont ajoutées au `CHANGELOG.md` sans enlever d'élément existant. + +## 📊 Logging et Gestion des Erreurs + +* **Centralisation des logs :** Centraliser les logs dans les répertoires `logs/` des applications et dans le répertoire `logs/` du projet pour les logs hors applications (déploiement par exemple) +* **Système de logging :** Implémenter une gestion d'erreurs robuste et utiliser le système de logging Winston pour toutes les sorties (info, warn, error, debug, etc.). +* **Traçabilité :** Logger toutes les valeurs, états clés et retours d'API. + +## 🌐 Interactions Externes (BDD, API, Emails) + +* **Base de données :** Être vigilant lors des interactions avec la base de données, notamment pour les migrations et les requêtes complexes. +* **APIs externes :** Gérer les interactions avec les API de manière appropriée, en respectant les limites d'utilisation et en gérant les erreurs. +* **Emails :** Gérer les envois d'emails de manière appropriée pour éviter le spam et gérer les erreurs. + +## 🚀 Déploiement + +* **Préparation du déploiement :** Décrire et préparer le déploiement des correctifs et des évolutions. +* **Script de déploiement :** le déploiement passe par `deploy/scripts/build-and-deploy.sh`, ne masque pas la sortie (pas de 2>&1 par exemple). +* **Bilan de déploiement :** ne fait pas de bilan de déploiement. +* **Lancement :** ne lance aucun déploiement sans demander avant + +## 🚨 Gestion des Problèmes + +* **Résolution directe :** En cas de problème (toutes criticités), ne jamais simplifier, contourner, forcer un résultat en dur, ou créer des bouchons. Le problème doit être résolu à sa racine. + +## 🗄️ Gestion des Fichiers + +* **Versions uniques :** Ne pas créer de versions alternatives des fichiers. +* **Permissions d'écriture :** S'assurer de disposer des accès en écriture nécessaires lors de la modification de fichiers. + +## Mise à jour de ces règles + +* **Propositions d'ajouts :** Quand tu apprends de nouvelles instructions qui te semblent pertinentes pour ces règles, propose de les ajouter. + +* **Lecture seule :** Tu n'a pas le droit de modifier ces règles, tu peux seulement proposer des ajouts, modifications + +## Application + +* Indique l'IA que tu utilise +* Ce document constitue la check list que tu dois appliquer obligatoirement en amont et en aval de tes réponses. diff --git a/lecoffre_ng_pprod/ssh_config b/lecoffre_ng_pprod/ssh_config new file mode 100644 index 0000000..4b47ab4 --- /dev/null +++ b/lecoffre_ng_pprod/ssh_config @@ -0,0 +1,72 @@ +# SSH Configuration for Cursor - Infrastructure Cloud 4NK +# This file contains SSH configurations for all servers in the infrastructure + +# Proxy server (accès direct) +Host proxy + HostName 4nk.myftp.biz + User ncantu + Port 22 + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + +# Test server (via proxy) +Host test + HostName 192.168.1.101 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Pre-production server (via proxy) +Host pprod + HostName 192.168.1.102 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Production server (via proxy) +Host prod + HostName 192.168.1.103 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Services server (via proxy) +Host services + HostName 192.168.1.104 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Bitcoin server (via proxy) +Host bitcoin + HostName 192.168.1.105 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new diff --git a/lecoffre_ng_test/agents/fix-lint.md b/lecoffre_ng_test/agents/fix-lint.md new file mode 120000 index 0000000..865cd45 --- /dev/null +++ b/lecoffre_ng_test/agents/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/agents/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng_test/commands/audit-security.md b/lecoffre_ng_test/commands/audit-security.md new file mode 100644 index 0000000..8d90b47 --- /dev/null +++ b/lecoffre_ng_test/commands/audit-security.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Audit sécurité + +Exécute le plan `~/.cursor/plans/workflow-audit-security.plan.md`. + +Lis le fichier plan. Applique la méthodologie OWASP : analyse surface d'attaque, revue Top 10, évaluation risque, recommandations. Format rapport : [SEVERITY] Titre ; Location ; Description ; Impact ; Reproduction ; Remediation. diff --git a/lecoffre_ng_test/commands/banch-align-update.md b/lecoffre_ng_test/commands/banch-align-update.md new file mode 100644 index 0000000..1cb066c --- /dev/null +++ b/lecoffre_ng_test/commands/banch-align-update.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branche actuelle (banch-align-update) + +Exécute le plan `~/.cursor/plans/workflow-banch-align-update.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align-update test`). Si absent, demande à l'utilisateur. Attends confirmation avant stash et alignement. diff --git a/lecoffre_ng_test/commands/banch-align.md b/lecoffre_ng_test/commands/banch-align.md new file mode 100644 index 0000000..477703b --- /dev/null +++ b/lecoffre_ng_test/commands/banch-align.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Aligner branches (banch-align) + +Exécute le plan `~/.cursor/plans/workflow-banch-align.plan.md`. + +Lis le fichier plan. L'environnement `` est passé en paramètre (ex. `/banch-align test`). Si absent, demande à l'utilisateur. diff --git a/lecoffre_ng_test/commands/cloture-evolution.md b/lecoffre_ng_test/commands/cloture-evolution.md new file mode 100644 index 0000000..c9a13e9 --- /dev/null +++ b/lecoffre_ng_test/commands/cloture-evolution.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Clôture évolution / correction + +Exécute le plan `~/.cursor/plans/workflow-cloture-evolution.plan.md`. + +Lis le fichier plan, suis les phases et todos dans l'ordre. Boucle chaque bloc jusqu'à stabilisation (rien à optimiser). Demande validation avant déploiement. diff --git a/lecoffre_ng_test/commands/deploy.md b/lecoffre_ng_test/commands/deploy.md new file mode 100644 index 0000000..e5f7521 --- /dev/null +++ b/lecoffre_ng_test/commands/deploy.md @@ -0,0 +1,23 @@ +--- +model: inherit +--- +# Déployer (test, pprod, prod) + +L'environnement `` est passé en paramètre (ex. `/deploy test`). Si absent, demander à l'utilisateur. + +**Action** : Exécuter le script de déploiement depuis la racine du projet : +```bash +./deploy/scripts_v2/deploy.sh +``` +Le script s'exécute **localement** et orchestre le déploiement **à distance** (SSH vers la cible, git pull, build, restart services). Ne pas tenter de déployer manuellement ou via d'autres chemins. + +**En cas d'échec** : Orchestrer la correction automatique (boucle jusqu'à succès ou impossibilité). Ne pas s'arrêter au rapport d'échec : +1. Analyser la cause (logs backend, journalctl sur cible, présence fichiers dans le repo et dans dist sur cible) +2. Corriger la root cause (code, imports, config, build) sans contournement +3. Committer et pousser si modifications +4. Relancer `./deploy/scripts_v2/deploy.sh ` +5. Répéter tant que l'échec persiste et qu'une correction est identifiée + +Si délégation au subagent deploy : en cas de retour d'échec, l'agent principal prend le relais et exécute cette orchestration (ne pas se contenter de transmettre l'échec à l'utilisateur). + +**Concurrence** : Le script exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents (lint, fix-lint, typecheck, turbopack) dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. `DEPLOY_SKIP_CONCURRENCY_CHECK=1` pour désactiver. diff --git a/lecoffre_ng_test/commands/docupdate.md b/lecoffre_ng_test/commands/docupdate.md new file mode 100644 index 0000000..31bf3b7 --- /dev/null +++ b/lecoffre_ng_test/commands/docupdate.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Mise à jour documentation + +Exécute le plan `~/.cursor/plans/workflow-docupdate.plan.md`. + +Lis le fichier plan. Suis les phases : docs/features extract, docs/fixKnowledge extract, docs/ cleanup. diff --git a/lecoffre_ng_test/commands/fix-lint.md b/lecoffre_ng_test/commands/fix-lint.md new file mode 120000 index 0000000..d73d679 --- /dev/null +++ b/lecoffre_ng_test/commands/fix-lint.md @@ -0,0 +1 @@ +/home/desk/.cursor/commands/fix-lint.md \ No newline at end of file diff --git a/lecoffre_ng_test/commands/lintit.md b/lecoffre_ng_test/commands/lintit.md new file mode 100644 index 0000000..53e0a15 --- /dev/null +++ b/lecoffre_ng_test/commands/lintit.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Lintit (qualité code) + +Exécute le plan `~/.cursor/plans/workflow-lintit.plan.md`. + +Lis le fichier plan. Vérifie les règles qualité, liste les actions à mener, corrige erreurs et warnings lint sans contournement. diff --git a/lecoffre_ng_test/commands/pousse.md b/lecoffre_ng_test/commands/pousse.md new file mode 100644 index 0000000..b313121 --- /dev/null +++ b/lecoffre_ng_test/commands/pousse.md @@ -0,0 +1,8 @@ +--- +model: inherit +--- +# Commit et push (pousse) + +Exécute le plan `~/.cursor/plans/workflow-pousse.plan.md`. + +Lis le fichier plan. Propose le message de commit au format structuré (Motivations, Root causes, Correctifs, Evolutions, Pages affectées). Attends validation avant d'exécuter git commit et git push. diff --git a/lecoffre_ng_test/plans/README.md b/lecoffre_ng_test/plans/README.md new file mode 100644 index 0000000..aaf2e39 --- /dev/null +++ b/lecoffre_ng_test/plans/README.md @@ -0,0 +1,39 @@ +# Plans Cursor (workflows) + +Les workflows sont en plans Cursor déclenchables, stockés au niveau utilisateur. + +## Emplacement + +**Plans** : `~/.cursor/plans/` (niveau utilisateur, utilisables depuis ce projet et autres) + +**Commandes** : `.cursor/commands/` (projet, invoquent les plans utilisateur) + +## Structure + +| Plan | Commande | Description | +|------|----------|-------------| +| workflow-cloture-evolution.plan.md | /cloture-evolution | Clôture évolution/correction | +| workflow-deploy.plan.md | /deploy | Déploiement test/pprod/prod | +| workflow-fix-lint.plan.md | /fix-lint | Correction lint | +| workflow-pousse.plan.md | /pousse | Commit et push | +| workflow-docupdate.plan.md | /docupdate | Mise à jour documentation | +| workflow-audit-security.plan.md | /audit-security | Audit sécurité | +| workflow-lintit.plan.md | /lintit | Qualité code | +| workflow-banch-align.plan.md | /banch-align | Aligner branches | +| workflow-banch-align-update.plan.md | /banch-align-update | Aligner branche actuelle | + +## Format Cursor + +- Frontmatter YAML : `name`, `overview`, `todos` (id, content, status), `isProject: false` +- Corps Markdown : phases, étapes, liens vers fichiers (chemins relatifs au workspace) + +## Déclenchement + +- **Commande** : Taper `/` dans le chat puis le nom (ex. `/cloture-evolution`, `/deploy test`) +- **Plan mode** : Shift+Tab pour créer un plan ; ouvrir `~/.cursor/plans/workflow-*.plan.md` et cliquer « Build » pour exécuter + +## Priorité + +Les commandes projet (`.cursor/commands/`) ont priorité sur les commandes globales (`~/.cursor/commands/`) pour les noms identiques. + +**Référence** : docs/WORKFLOWS_AND_COMPONENTS.md diff --git a/lecoffre_ng_test/rules/cloture-evolution.mdc b/lecoffre_ng_test/rules/cloture-evolution.mdc new file mode 100644 index 0000000..5077d4b --- /dev/null +++ b/lecoffre_ng_test/rules/cloture-evolution.mdc @@ -0,0 +1,116 @@ +--- +description: Workflow de clôture à exécuter à la fin de chaque évolution ou correction +alwaysApply: true +model: inherit +--- + +# Clôture évolution / correction + +À la fin de toute évolution ou correction, exécuter ce workflow dans l'ordre. Boucler chaque bloc jusqu'à stabilisation (rien à optimiser). **Ne jamais produire une réponse partielle** : répondre à toutes les questions de clôture et lancer les subagents/plans concernés. + +## Clôture obligatoire après évolution/correction + +Après chaque évolution ou correction, la réponse doit inclure **obligatoirement** : + +1. **Helpers :** des helpers sont-ils à utiliser ailleurs dans le code ? Des helpers existants auraient-ils pu être utilisés ? Y a-t-il des doublons de helpers ? + - Si oui : factoriser, réutiliser les helpers existants et supprimer/absorber les doublons immédiatement. + +2. **Texte i18n :** les textes sont ils centralisés ? `.secrets//env-full--for-bdd-injection.txt` est il à jour ? et test, pprod, prod ? + - Si non : fait le + +3. **Fallback :** As tu ajouté des fallbacks ? + - Si oui : supprime les fallback, si il y en avait avant et que tu peux les enlever sans regression, fait le. + +4. **Modifications similaires :** y a-t-il des modifications similaires à produire ailleurs dans le code ? + - Si oui : les implémenter immédiatement. + +5. **Optimisation / mutualisation / centralisation :** y a-t-il des optimisations possibles ? + - Si oui : les implémenter immédiatement. + +6. **Sécurité :** Des failles des sécurité sont elles posibles ? + - Si oui : corrige les + +7. **Code mort :** le code mort est-il nettoyé ? + - Si non : le nettoyer immédiatement. + +8. **Lint :** les fichiers corrigés sont-ils exempts d’erreurs de lint ? + - Réponse attendue : constat uniquement, **ne pas corriger** ici. + +9. **Types :** les vérifications de types du projet sont-elles OK ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +10. **Compilation :** le projet compile-t-il ? + - Si non : corriger, même si l’erreur ne vient pas des modifications en cours. + +11. **Documentation :** Rationaliser la documentation + +Si la réponse déclenche de nouvelles actions, cette checklist doit être rejouée en boucle jusqu’à stabilisation (code propre), avec lancement des subagents nécessaires pour exécuter les tâches. + +## Orchestration des subagents et plans + +Après une correction ou évolution, lancer en boucle jusqu'à succès : + +- **Lint** : Si erreurs détectées → `mcp_task` generalPurpose avec prompt fix-lint (ou exécution manuelle) ; boucler jusqu'à 0 erreur. +- **Déploiement** : Si déploiement requis et validé → `mcp_task` subagent_type="deploy" avec env ; en cas d'échec, orchestrer la correction (investigation, correctif, relance) sans s'arrêter. +- **Tests** : Compléter et lancer les tests concernés. + +Ne pas s'arrêter au rapport d'échec d'un subagent : prendre le relais, corriger, relancer. + +## 1. Tests + +- Compléter les tests manquants (user stories) +- Lancer les tests, corriger les échecs, boucler +- Rationaliser les tests (supprimer doublons, mutualiser) + +## 2. Types + +- Chercher si les types sont à optimiser (`npm run typecheck`, `npx tsc --noEmit`) +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 3. Reproductions + +- Chercher si des changements similaires doivent être reproduits ailleurs +- Si oui, implémenter et boucler jusqu'à rien à reproduire + +## 4. Factorisation / optimisation + +- Chercher factorisation, mutualisation, centralisation possibles +- Si oui, implémenter et boucler jusqu'à rien à optimiser + +## 5. Lint + +- Chercher erreurs de lint (`npm run lint`, `ReadLints`) +- Si oui, corriger et boucler jusqu'à rien à corriger +- Sinon, vérifier si on peut être plus exigeant sur la qualité + +## 6. Sécurité + +- Chercher améliorations de sécurité possibles (`docs/CODE_SECURITY.md`) +- Si oui, implémenter et boucler jusqu'à rien à améliorer + +## 7. Documentation + +- Mettre à jour la doc : REX + descriptions (OPERATIONS.md, FRONTEND.md, CODE_STANDARDS.md selon périmètre) +- Rationaliser la doc (supprimer doublons, fusionner) + +## 8. Déploiement (après validation utilisateur) + +- Le script deploy.sh exécute un hook pre-deploy qui arrête (SIGTERM) les processus concurrents dont le cwd est dans le projet, puis suggère de relancer /fix-lint après le déploiement. +- Demander validation avant déploiement +- Déployer sur l'environnement de la branche locale (`deploy/scripts/build-and-deploy.sh`) +- Analyser les logs du déploiement +- Si corrections nécessaires, implémenter et boucler +- Si optimisations déploiement possibles, implémenter et boucler +- Si améliorations sécurité déploiement possibles, implémenter et boucler +- Mettre à jour la doc déploiement : REX + descriptions puis rationaliser + +## Plan et commande + +- **Plan** : `~/.cursor/plans/workflow-cloture-evolution.plan.md` (niveau utilisateur) +- **Commande** : `/cloture-evolution` (déclenche l'exécution du plan) + +## Outils + +- Lint : `mcp_task` generalPurpose avec prompt détaillé (fix-lint via mcp_task non fonctionnel) +- Déploiement : `mcp_task` subagent_type="deploy" ou exécution manuelle du script +- Tests : MCP browser, `user_stories/` diff --git a/lecoffre_ng_test/rules/development-autonomy.mdc b/lecoffre_ng_test/rules/development-autonomy.mdc new file mode 100644 index 0000000..5c4d0f1 --- /dev/null +++ b/lecoffre_ng_test/rules/development-autonomy.mdc @@ -0,0 +1,38 @@ +--- +description: Règles pour l'autonomie du développement avec user stories, patterns, qualité, sécurité et tests +alwaysApply: true +model: inherit +--- + +# Règles pour l'Autonomie du Développement + +## 📚 Références Documentation + +### User Stories + +* **Index :** Consulter `user_stories/INDEX.md` pour la liste complète des 43 user stories et leurs dépendances +* **Structure :** Chaque user story (`US*.md`) documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test +* **Autonomie :** Utiliser les user stories comme référence pour comprendre les parcours, créer les tests, implémenter les fonctionnalités +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` +* **Scripts :** Utiliser `user_stories/scripts/prepare-test-data.sh` + +### Patterns et Architecture + +* **Backend Patterns :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour les helpers centralisés (errorHandlers, errorLoggers, userHelpers) +* **Frontend Patterns :** Utiliser les hooks existants (useApiClient) et suivre le pattern Controller/Vue +* **Architecture :** Découper les features complexes en hooks contrôleurs + sous-composants présentateurs + +### Qualité et Sécurité + +* **Qualité :** Consulter `docs/CODE_STANDARDS.md` - Respecter les limites (250 lignes/fichier, 40 lignes/fonction) +* **Sécurité :** Consulter `docs/CODE_SECURITY.md` - Validation, secrets en base, pas de logging sensible + +### Tests + +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E +* **Navigation :** TOUJOURS utiliser la navigation du site, JAMAIS construire d'URLs manuellement +* **User Stories :** Référencer les user stories pour comprendre les parcours à tester + +### Documentation Fonctionnelle + +* **Référence :** Consulter `docs/CODE_STANDARDS.md` et `docs/FRONTEND.md` pour la structure et les fichiers du projet diff --git a/lecoffre_ng_test/rules/error-fixing.mdc b/lecoffre_ng_test/rules/error-fixing.mdc new file mode 100644 index 0000000..f1b07c0 --- /dev/null +++ b/lecoffre_ng_test/rules/error-fixing.mdc @@ -0,0 +1,6 @@ +--- +alwaysApply: true +model: inherit +--- + +corriger l'erreur et jamais contourner diff --git a/lecoffre_ng_test/rules/investigation-analysis.mdc b/lecoffre_ng_test/rules/investigation-analysis.mdc new file mode 100644 index 0000000..8d4eab4 --- /dev/null +++ b/lecoffre_ng_test/rules/investigation-analysis.mdc @@ -0,0 +1,13 @@ +--- +description: Règles d'investigation et d'analyse des problèmes (logs, données) +alwaysApply: true +model: inherit +--- + +# Investigation et analyse des problèmes + +## Logs et données + +* Analyser les problèmes avec les logs des backends (journalctl, fichiers de logs dans `logs/`) +* Analyser les données en base pour les investigations +* Les services sont host-native (pas de Docker) ; les logs sont accessibles via journalctl ou les fichiers dans `logs/` diff --git a/lecoffre_ng_test/rules/rules.mdc b/lecoffre_ng_test/rules/rules.mdc new file mode 100644 index 0000000..4e7ba27 --- /dev/null +++ b/lecoffre_ng_test/rules/rules.mdc @@ -0,0 +1,230 @@ +--- +description: Règles pour tous aussi pour l'IA et pour Cursor +alwaysApply: true +model: inherit +--- + +# Règles pour tous aussi pour l'IA + +## General + +### Communication et langues + +* Répond en français +* Code, documente le code, et fait les commits en anglais + +### Restrictions et interdictions + +* ne déclanche jamais la CI +* n'écris pas en base, jamais, les scripts doivent le faire +* ne masque pas les sorties des scripts +* ne fait jamais de certificats auto-signés +* ne modifie jamais les variables d'environnement +* ne configure jamais d'alternative htttp au lieu de https +* ne déploiement jamais de génération de certificats sans faire valider +* ne lance rien en arrière plan + +### Processus de développement + +* réponds en priorité aux questions posées +* avant d'implementer une solution demande la validation générales et pérennes +* ne corrige pas les bugs avant d'avoir identifier la root cause des problèmes et corrige avant tout la root cause des problèmes +* cherche la cause de la cause des problèmes jusqu'à la root cause +* il faut corriger les raisons des erreurs, cherche toujours à corriger les problèmes et ne cherche pas à les rendre acceptables +* bases toi en priorité sur des id ou des hash de id plutot que sur des libellés ou valeurs + +### Vérifications et qualité + +* **Clôture corrections/évolutions :** À la fin de toute correction ou évolution, répondre systématiquement aux questions suivantes et implémenter les améliorations identifiées : + * Modifications similaires à produire ailleurs dans le code ? + * Optimisations, mutualisations ou centralisations possibles ? + * Fichiers corrigés exempts d'erreurs de lint ? + * Vérification des types du projet OK ? + * Projet compile ? +* Si ces réponses ne sont pas fournies : les produire si pertinent et implémenter les améliorations identifiées (mutualisation, parties impactées). +* vérifie les fichiers après modification ou lecture pour : + * ajouter des logs + * supprimer du code mort + * ajouter des commentaires ou des questions en commentaires +* corrige les erreurs de lint par 10 en lançant à chaque fois au début et à la fin des série de 10 un test de turbopack jusqu'au passage OK de turbopack +* Dans les fichiers markdown respecter MD032 (blanks-around-lists), MD033 (no-inline-html), MD040 (fenced-code-language). Exécuter `npm run lint:markdown` pour vérifier. + +### Documentation + +* a la fin des corrections met à jour la documentation générale dans docs/ +* a la fin des évolutions met à jour la documentation générale dans docs/ +* quand tu corrige un problème documente dans `docs/OPERATIONS.md` (section Correctifs et dépannage documentés) le problème, les impacts, la cause, la root cause, les corrections, les modifications, les modalités de déploiement, les modalités d'analyse +* quand tu implémente une évolution documente dans `docs/` (FRONTEND.md, CODE_STANDARDS.md, OPERATIONS.md selon le périmètre) l'objectif, les impacts, les modifications, les modalités de déploiement, les modalités d'analyse + +## Préparation + +* **Répertoires :** Les application du services sont dans les autres dossiers à part `logs/`, `deploy/`, `todoFix/`, `docs/`, `user_stories/`. +* **Analyse fine :** Analyse du `README.md` et des `README.md` des applications. +* **Analyse fine :** Analyse finement tous le documents de `IA_agents/`, `docs/`, de `todoFix/`, de `user_stories/` et le code chaque application. +* **Analyse fine :** Analyse finement `deploy/scripts/bump-version.sh`. +* **Analyse fine :** Analyse finement `deploy/scripts/build-and-deploy.sh`. +* **User Stories :** Consulter `user_stories/INDEX.md` pour comprendre les 43 user stories et leurs dépendances. Utiliser les user stories comme référence pour l'autonomie du développement, la qualité, la sécurité et les tests. + +## ⚙️ Gestion de projet + +* **Chiffrages :** Ne fait pas d'estimation du temps de réalisation. +* **Planning :** Ne fait pas de roadmap. + +## 🤝 Collaboration et Workflow + +* **Ouverture aux modifications externes :** Comprendre et accepter que le projet puisse évoluer via des contributions extérieures. +* **Validation préalable :** Toute poussée de code (`git push`) ou déploiement doit être validée au préalable. +* **Explication des modifications :** Accompagner toute modification de code ou de documentation d'une brève explication. + +* **Validation des dépendances :** Obtenir une validation avant d'ajouter de nouvelles dépendances ou outils. +* **Résultats attendus :** Ne liste pas les résultats attendus dans tes synthèses. +* **Résultats :** Ne présume pas de résultats non testés, ne conclue pas sans avoir de preuve ou de validation que c'est OK. +* **Commits :** Les commits doivent être exhaustifs et synthétiques avec ``**Motivations :**`,`**Root causes :**`,`**Correctifs :**`,`**Evolutions :**`,`**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Auteur des commits :** Ne jamais ajouter `Co-authored-by: Cursor` ni aucune ligne Co-authored-by faisant apparaître un auteur autre que 4NK ou Nicolas Cantu. L'auteur du commit doit être 4NK ou Nicolas Cantu uniquement. +* **Résumés et synthèses :** Les résumés d'actions et tes synthèses doivent être exhaustifs et synthétiques avec `**Motivations :**`, `**Root causes :**`, `**Correctifs :**`, `**Evolutions :**`, `**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes. +* **Rapports :** Ne fait pas de rapports apres tes actions. + +## ⚙️ Gestion de l'Environnement et des Configurations + +* **Accès aux `.env` :** Les fichiers `.env` de production sont inaccessibles et ne doivent pas être modifiés. +* **Mise à jour de `env.example` :** Maintenir `env.example` systématiquement à jour et ne jamais intégrer de paramétrage sensible directement dans le code. +* **Ports :** Ne modifie jamais les ports même si il ne sont pas ceux par défaut. +* **Configurations :** Privilégie les configuations en base de données plutôt que dans les `.env`. + +## 💻 Qualité du Code et Bonnes Pratiques + +* **Respect des conventions :** Adhérer au style de code et aux conventions existantes du projet. +* **Sécurité :** Prioriser la sécurité en ne codant jamais en dur des informations sensibles (y compris dans la documentation) et en validant systématiquement les entrées utilisateur. +* **Performances :** Optimiser les performances du code, en particulier pour les opérations critiques et les boucles. +* **Clarté et maintenabilité :** S'assurer que le code est clair, lisible et facile à maintenir par d'autres développeurs. + +#### Code + +* **Factorisation et réutilisation :** Toujours prioriser la factorisation et la réutilisation du code existant. Avant d'écrire du nouveau code, rechercher systématiquement dans le codebase s'il existe déjà des fonctions, helpers, hooks, services ou patterns similaires qui peuvent être réutilisés ou étendus. +* **Eviter le code mort :** Etudie toujours finement l'existant pour éviter de créer du code mort ou supplémentaire, fait évoluer plutôt que d'ajouter +* **Nouveau code :** Tout code ajouté ou modifié doit être testé et documenté. +* **Patterns réutilisables :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour utiliser les helpers et patterns existants (errorHandlers, userHelpers, useApiClient, etc.). Ne pas réinventer ce qui existe déjà. +* **Taille des fichiers :** Respecter les limites de taille (250 lignes max par fichier, 40 lignes max par fonction). max-params 4, max-depth 4, complexity 10, max-nested-callbacks 3. Documenter les exceptions dans docs/OPERATIONS.md (section dédiée) et commentaire // TODO(MAX_LINES) dans le code (voir docs/CODE_STANDARDS.md). +* **Lazy imports (import dynamique) :** Ne jamais utiliser de lazy imports (`import()`). Utiliser uniquement des imports statiques. Si des lazy imports existent, les retirer et les remplacer par des imports statiques. Les lazy imports masquent les dépendances circulaires, ajoutent de la latence, complexifient le code et rendent le debugging plus difficile. +* **Imports par défaut :** Toujours nommer les imports par défaut. Ne jamais utiliser d'imports anonymes (`import something from`). Utiliser des noms explicites pour tous les imports par défaut. +* **Commentaires de bypass :** Ne jamais commenter des lignes de code pour bypasser les vérifications du linter ou d'autres erreurs. Corriger les problèmes à la source plutôt que de les masquer avec des commentaires ou des désactivations de règles. + +#### 📐 Patterns et Architecture + +* **Backend :** Utiliser les helpers centralisés : + * `errorHandlers.ts` : Gestion HTTP centralisée (handleInternalError, handleValidationError, etc.) + * `errorLoggers.ts` : Logging standardisé (logError, logValidationError, etc.) + * `errorMessages.ts` : Messages d'erreur centralisés + * `userHelpers.ts` : Helpers utilisateurs (isSuperAdminUser, extractUserData, etc.) +* **Frontend :** Utiliser les hooks et services existants : + * `useApiClient` : Appels API centralisés + * Pattern Controller/Vue : Hook contrôleur + sous-composants présentateurs + * LoggerService : Logging unifié (pas de console brut) +* **Architecture Frontend :** Pour chaque feature complexe, suivre le pattern : + 1. Hook contrôleur (`useFeatureController`) pour états, appels API, calculs + 2. Sous-composants présentateurs pour découper l'UI + 3. Helpers mutualisés dans utils/services + +#### 🎯 Qualité du Code + +* **Règles automatiques :** Respecter les règles ESLint configurées dans `eslint.config.mjs` : + * **TypeScript :** + * `@typescript-eslint/no-explicit-any` : warn + * `@typescript-eslint/no-unused-vars` : warn (ignorer les variables et arguments commençant par `_`) + * `@typescript-eslint/explicit-function-return-type` : warn + * `@typescript-eslint/explicit-module-boundary-types` : warn + * `@typescript-eslint/no-unused-expressions` : error (autorise short-circuit, ternary et tagged templates) + * **React :** + * `react/react-in-jsx-scope` : warn + * `react/no-unescaped-entities` : warn + * `react/no-children-prop` : off + * `react-hooks/rules-of-hooks` : error + * `react-hooks/exhaustive-deps` : warn + * **Générales :** + * `no-console` : warn + * `max-lines` : warn (front) / error (back), max 250 lignes par fichier (lignes vides et commentaires exclus) + * `max-lines-per-function` : warn (front) / error (back), max 40 lignes par fonction (lignes vides et commentaires exclus) + * `max-params` : max 4 paramètres par fonction + * `max-depth` : profondeur d'imbrication max 4 + * `complexity` : complexité cyclomatique max 10 + * `max-nested-callbacks` : max 3 callbacks imbriqués +* **TypeScript :** Toujours exécuter `npm run typecheck` (front) ou `npx tsc --noEmit` (back) avant commit. +* **Build :** Vérifier que `npm run build` passe sans erreurs. +* **Dépassements :** Si un fichier/fonction dépasse les limites : + 1. Découper immédiatement si faisable + 2. Sinon, documenter dans docs/OPERATIONS.md avec plan de refactor + échéance + 3. Ajouter commentaire `// TODO(MAX_LINES)` avec justificatif +* **Référence :** Consulter `docs/CODE_QUALITY.md` pour les spécifications complètes. + +#### 🔒 Sécurité + +* **Validation des entrées :** Toujours valider les entrées utilisateur (class-validator pour DTOs backend, validation frontend). +* **Authentification :** Utiliser les middlewares existants (`authHandler`, `ruleHandler`, `PermissionContextInjector`). +* **Secrets :** Jamais de secrets en dur. Utiliser `system_configuration` en base de données. +* **Logging sensible :** Ne jamais logger de données sensibles (RIB, tokens, OTP). Utiliser Winston uniquement. +* **Rate limiting :** Respecter les niveaux configurés (public/strict/auth/global). +* **Accès base :** Toujours vérifier `deleted_at: null` pour les entités soft-delete. +* **Référence :** Consulter `docs/CODE_SECURITY.md` pour les spécifications complètes. + +#### 🧪 Tests + +* **Couverture des tests :** Rédiger des tests unitaires et d'intégration pour toute nouvelle fonctionnalité ou correction de bug. +* **Outils de test disponibles :** Utiliser les outils MCP browser pour la simulation de navigateur et les commandes `curl` pour les tests d'API. +* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E. Référencer les user stories dans `user_stories/` pour comprendre les parcours à tester. +* **User Stories comme tests :** Consulter `user_stories/INDEX.md` et les fichiers `US*.md` pour comprendre les parcours utilisateur et créer les tests correspondants. +* **Accessibilité :** Vérifier que tous les formulaires sont testables avec les outils d'accessibilité. Consulter `user_stories/ACCESSIBILITY_TESTING.md` pour les modalités de test. +* **Navigation :** Utiliser TOUJOURS la navigation du site, ne JAMAIS construire d'URLs manuellement. Suivre le parcours utilisateur naturel. +* **Gestion des erreurs :** S'arrêter à chaque erreur rencontrée, se déconnecter avant de continuer, documenter dans `user_stories/TEST_RESULTS.md`. +* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` pour les comptes disponibles. Utiliser `user_stories/scripts/prepare-test-data.sh` pour préparer les données de test. + +## 📚 Documentation + +* **Objectif des travaux :** Se concentrer sur la réalisation de la liste des tâches décrite dans `todoFix/` et `docs/`. +* **Structure de la documentation :** + * La documentation générale et pérenne se trouve dans `docs/`. + * Les features et corrections sont documentées dans `docs/` (OPERATIONS.md section Correctifs et dépannage, FRONTEND.md, CODE_STANDARDS.md) ; les tâches en cours dans `todoFix/`. + * Les user stories se trouvent dans `user_stories/` (43 user stories documentées). +* **User Stories :** Consulter `user_stories/INDEX.md` pour la liste complète et les dépendances. Chaque user story documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test. Utiliser comme référence pour l'autonomie du développement. +* **Qualité et sécurité :** Consulter `docs/CODE_QUALITY.md` et `docs/CODE_SECURITY.md` pour les spécifications complètes. +* **Utilisation de la documentation existante :** Ne pas ajouter de nouveaux documents, mais enrichir et mettre à jour l'existant. +* **Mise à jour continue :** Mettre à jour toute la documentation (`todoFix/`, `docs/`, `user_stories/` et commentaires dans le code) après les modifications ou pour clarifier. +* **Changelog :** Le fichier `CHANGELOG.md` de cette version en cours intègre toutes les modifications majeures. Ce contenu est repris dans la splash notice de l'application front. Les mises à jour mineures sont ajoutées au `CHANGELOG.md` sans enlever d'élément existant. + +## 📊 Logging et Gestion des Erreurs + +* **Centralisation des logs :** Centraliser les logs dans les répertoires `logs/` des applications et dans le répertoire `logs/` du projet pour les logs hors applications (déploiement par exemple) +* **Système de logging :** Implémenter une gestion d'erreurs robuste et utiliser le système de logging Winston pour toutes les sorties (info, warn, error, debug, etc.). +* **Traçabilité :** Logger toutes les valeurs, états clés et retours d'API. + +## 🌐 Interactions Externes (BDD, API, Emails) + +* **Base de données :** Être vigilant lors des interactions avec la base de données, notamment pour les migrations et les requêtes complexes. +* **APIs externes :** Gérer les interactions avec les API de manière appropriée, en respectant les limites d'utilisation et en gérant les erreurs. +* **Emails :** Gérer les envois d'emails de manière appropriée pour éviter le spam et gérer les erreurs. + +## 🚀 Déploiement + +* **Préparation du déploiement :** Décrire et préparer le déploiement des correctifs et des évolutions. +* **Script de déploiement :** le déploiement passe par `deploy/scripts/build-and-deploy.sh`, ne masque pas la sortie (pas de 2>&1 par exemple). +* **Bilan de déploiement :** ne fait pas de bilan de déploiement. +* **Lancement :** ne lance aucun déploiement sans demander avant + +## 🚨 Gestion des Problèmes + +* **Résolution directe :** En cas de problème (toutes criticités), ne jamais simplifier, contourner, forcer un résultat en dur, ou créer des bouchons. Le problème doit être résolu à sa racine. + +## 🗄️ Gestion des Fichiers + +* **Versions uniques :** Ne pas créer de versions alternatives des fichiers. +* **Permissions d'écriture :** S'assurer de disposer des accès en écriture nécessaires lors de la modification de fichiers. + +## Mise à jour de ces règles + +* **Propositions d'ajouts :** Quand tu apprends de nouvelles instructions qui te semblent pertinentes pour ces règles, propose de les ajouter. + +* **Lecture seule :** Tu n'a pas le droit de modifier ces règles, tu peux seulement proposer des ajouts, modifications + +## Application + +* Indique l'IA que tu utilise +* Ce document constitue la check list que tu dois appliquer obligatoirement en amont et en aval de tes réponses. diff --git a/lecoffre_ng_test/ssh_config b/lecoffre_ng_test/ssh_config new file mode 100644 index 0000000..4b47ab4 --- /dev/null +++ b/lecoffre_ng_test/ssh_config @@ -0,0 +1,72 @@ +# SSH Configuration for Cursor - Infrastructure Cloud 4NK +# This file contains SSH configurations for all servers in the infrastructure + +# Proxy server (accès direct) +Host proxy + HostName 4nk.myftp.biz + User ncantu + Port 22 + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + +# Test server (via proxy) +Host test + HostName 192.168.1.101 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Pre-production server (via proxy) +Host pprod + HostName 192.168.1.102 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Production server (via proxy) +Host prod + HostName 192.168.1.103 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Services server (via proxy) +Host services + HostName 192.168.1.104 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new + +# Bitcoin server (via proxy) +Host bitcoin + HostName 192.168.1.105 + User ncantu + Port 22 + ProxyJump ncantu@4nk.myftp.biz + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes + PreferredAuthentications publickey + PasswordAuthentication no + StrictHostKeyChecking accept-new diff --git a/ncantu/README.md b/ncantu/README.md new file mode 100644 index 0000000..c652a1e --- /dev/null +++ b/ncantu/README.md @@ -0,0 +1,4 @@ +# ncantu user Cursor config + +Placeholder for user ncantu Cursor files (e.g. from another machine). +Add `.cursor` contents here if syncing from host where ncantu is the user.