# 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
```