hykocx
ca0fafe6ff
Expand the development guide from a minimal overview into a comprehensive reference covering: - Code standards: single responsibility, control flow, input validation, promise handling, and variable scoping - Security section: treat all external input as malicious, use path.join over string concatenation, no secrets in code - Reorganize publication steps to include version bump before build/publish for a logical workflow - Add project context note clarifying the scaffolding role of @zen/start
84 lines
2.8 KiB
Markdown
84 lines
2.8 KiB
Markdown
# 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/start`.
|
|
|
|
Pour les conventions de rédaction : [LANGUE.md](./dev/LANGUE.md) et [REDACTION.md](./dev/REDACTION.md).
|
|
|
|
Pour les conventions de commit : [COMMITS.md](./dev/COMMITS.md).
|
|
|
|
Pour la procédure de publication du package : voir section [Publication](#publication) ci-dessous.
|
|
|
|
> **Contexte projet** : `@zen/start` est un CLI qui génère un projet Next.js avec le CMS `@zen/core` déjà intégré. Lors d'une assistance ou d'une revue, partez du principe que le rôle de ce package est de scaffolder — pas d'exécuter du code applicatif.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Sécurité
|
|
|
|
### Données entrantes
|
|
|
|
Toute donnée externe est considérée malveillante par défaut : arguments CLI, chemins de fichiers, noms de projet fournis par l'utilisateur. On valide et on assainit avant tout usage dans des chemins ou des commandes shell.
|
|
|
|
### Système de fichiers
|
|
|
|
On ne construit jamais un chemin par concaténation de chaînes brutes. On utilise `path.join` ou `path.resolve` :
|
|
|
|
```js
|
|
// ✓
|
|
const dest = path.join(targetDir, 'package.json')
|
|
|
|
// ✗
|
|
const dest = targetDir + '/package.json'
|
|
```
|
|
|
|
### Secrets
|
|
|
|
Aucun token, clé API ou credential dans le code. Le token d'authentification au registre npm est configuré localement, jamais commité.
|
|
|
|
---
|
|
|
|
## Publication
|
|
|
|
Le package `@zen/start` est publié sur le registre npm hébergé sur `https://git.hyko.cx`.
|
|
|
|
### 1. Configurer l'authentification
|
|
|
|
Créer un token d'accès dans Gitea (Settings → Applications → Generate Token), puis l'enregistrer localement :
|
|
|
|
```bash
|
|
npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
|
|
```
|
|
|
|
Remplacer `TOKEN` par le token généré.
|
|
|
|
### 2. Bump de version
|
|
|
|
Modifier `"version"` dans `package.json` en suivant [semver](https://semver.org/) :
|
|
|
|
| Type | Version |
|
|
|------|---------|
|
|
| `fix` | PATCH `1.x.X` |
|
|
| `feat` | MINOR `1.X.0` |
|
|
| Breaking change | MAJOR `X.0.0` |
|
|
|
|
### 3. Build et publish
|
|
|
|
```bash
|
|
npm publish
|
|
```
|