zen/start

Files

T

hykocx ca0fafe6ff docs: rewrite DEV.md with security guidelines and structure

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

2026-04-13 15:19:41 -04:00

2.8 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/start.

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

Pour les conventions de commit : COMMITS.md.

Pour la procédure de publication du package : voir section 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 :

// ✓
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 :

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 :

Type	Version
`fix`	PATCH `1.x.X`
`feat`	MINOR `1.X.0`
Breaking change	MAJOR `X.0.0`

3. Build et publish

npm publish

2.8 KiB Raw Blame History