zen/core

Files

T

hykocx 16db807004 docs: rewrite DEV.md with detailed dev and security guidelines

Replace the terse DEV.md with a comprehensive French-language guide
covering code standards, security rules, and the npm publish workflow.

Key changes:
- Expand code principles into readable prose (single responsibility,
  control flow, input validation, promise handling, minimal scope)
- Add concrete security sections: parameterized queries, secret
  management via env vars, dependency auditing, and opaque error
  messages
- Document the full publish procedure (version bump, build, audit,
  npm publish with provenance, git tag)
- Remove the NASA Power of Ten bullet list in favor of actionable,
  project-specific guidelines

2026-04-13 13:34:17 -04:00

3.4 KiB

Raw Blame History

Guide de développement

Ce document couvre les conventions de code, les règles de sécurité et la procédure de publication du package @zen/core.

Pour les conventions de rédaction : LANGUE.md et REDACTION.md.

Standards de code

Principes généraux

Une fonction, une responsabilité. Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.

Le flux de contrôle se lit de haut en bas. Pas de récursion non bornée, pas de callbacks imbriqués à plus de deux niveaux. Quelqu'un qui lit le code pour la première fois doit pouvoir suivre l'exécution sans se perdre.

Les données entrantes sont suspectes. On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.

Les promesses ne s'ignorent pas. Chaque Promise est awaitée ou .catch()ée. Une promesse silencieuse qui échoue est un bug invisible.

La portée des variables est minimale. On déclare au plus près de l'usage. Pas de variables réutilisées pour deux rôles différents.

ESLint passe sans avertissement. Un warning ignoré aujourd'hui est un bug non détecté demain.

Sécurité

Données entrantes

Toute donnée externe est considérée malveillante par défaut : requêtes HTTP, données formulaire, réponses d'API tierce, contenu de fichier. On valide côté serveur. Le client ne contrôle rien de critique.

Base de données

On n'écrit jamais de SQL par concaténation de chaînes. Uniquement des requêtes paramétrées :

// ✓
await pool.query('SELECT * FROM users WHERE id = $1', [userId])

// ✗
await pool.query(`SELECT * FROM users WHERE id = '${userId}'`)

Secrets

Aucun token, clé API ou mot de passe dans le code. Tout passe par des variables d'environnement. Les clés Stripe, les tokens Resend et les credentials PostgreSQL ne sont jamais commités.

# .env.local — jamais dans git
DATABASE_URL=...
STRIPE_SECRET_KEY=...
RESEND_API_KEY=...

Dépendances

Avant chaque publication :

npm audit

Ne pas publier avec des vulnérabilités de sévérité high ou critical non corrigées.

Erreurs exposées

Les messages d'erreur retournés à l'utilisateur ne contiennent pas de détails internes : pas de stack trace, pas de nom de table, pas de requête SQL. On log côté serveur, on renvoie un message générique côté client.

Publier le package

Le package @zen/core est publié sur le registre npm privé à https://git.hyko.cx.

Configurer l'authentification (une seule fois)

Créer un token dans Gitea : Settings → Applications → Generate Token, puis :

npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN

Checklist avant publication

npm audit — aucune vulnérabilité high ou critical
npm run build — build sans erreur ni warning TypeScript
Version mise à jour dans package.json

Versionner

On suit semver :

patch (1.3.x) — correction de bug, sans changement d'interface
minor (1.x.0) — nouvelle fonctionnalité, rétrocompatible
major (x.0.0) — changement cassant

npm version patch   # ou minor, ou major

Publier

npm publish

Le script prepublishOnly lance le build automatiquement. Si le build échoue, la publication est annulée.

3.4 KiB Raw Blame History