Développement

Les sources de production sont réparties sur trois emplacements : le dépôt privé Agent/Worker, le dépôt privé Frontend et le dépôt public désensibilisé. Le dépôt public est généré à sens unique par un script d'assainissement ; n'y modifiez pas la logique de production.

Worker et Frontend

node --test tests/*.test.mjs
node --check app.js
node --check js/admin.js

Vérification complète avant publication :

bash test.sh
pnpm run build
pnpm test
pnpm run test:update
pnpm exec wrangler deploy --dry-run --outdir .wrangler-dry-run

pnpm run build prépare les Static Assets du Worker ; ne copiez jamais d'anciennes copies Frontend dans le répertoire de build. Avant de déployer, confirmez que le dry-run liste les bindings D1, R2, Durable Object, Assets et Cron attendus.

Agent Rust

Une chaîne d'outils Rust stable est requise ; les publications Linux multi-architectures exigent aussi la configuration Zig/cibles du projet. Vérifications minimales :

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

Tester en local ne suffit pas pour publier. Les publications Agent doivent produire des binaires ELF Linux statiques pour chaque architecture prise en charge, mettre à jour VERSION et SHA256SUMS, et vérifier la chaîne de hachage par étapes de l'installeur.

Configuration et secrets

La configuration publique et les secrets sont traités séparément :

• ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_PATH sont requis au premier déploiement.
• Après connexion, l'admin utilise la session courte x-admin-session ; les clients ne doivent pas conserver ni rejouer le mot de passe.
• Les Agents et nœuds de latence utilisent des jetons scoped par nœud qui n'apparaissent jamais dans l'API publique.
• DEVELOPER_API_ORIGINS ne contrôle que les lectures navigateur de /api/v1.
• L'URL et le jeton d'hébergeur d'images NQ ne sont que des Worker Secrets ; ils n'entrent jamais dans les réglages D1, les sauvegardes normales ni le frontend.
• Les URL personnalisées doivent être en HTTPS sans identifiants et passer les contrôles serveur de privé/redirection.

Utilisez des ressources Cloudflare séparées et des identifiants de test pour le développement. Ne pointez pas les aperçus locaux vers l'API admin de production et n'acceptez jamais une base API arbitraire via un paramètre d'URL ?api=.

Modifier l'API publique

/api/v1 est la ligne de compatibilité stable :

1. Des champs optionnels et de nouvelles capacités d'endpoint peuvent être ajoutés.
2. Dans v1, les champs existants ne peuvent pas être supprimés, renommés ou re-sémantisés silencieusement.
3. Les nouveaux paramètres de requête exigent des valeurs par défaut, des bornes et des clés de cache normalisées.
4. Les endpoints d'historique doivent avoir des limites ; 0 ou les valeurs négatives ne signifient jamais « illimité ».
5. La sortie publique doit être assainie des IP, ports, identifiants d'URL et erreurs internes.
6. Le CORS navigateur ne renvoie que les Origines exactes de la liste d'autorisation.
7. Mettez à jour le manifest, la documentation des endpoints, les tests de contrat et les exemples de frontend alternatif.

Les clients doivent lire le manifest /api/v1 pour découvrir les capacités plutôt que deviner depuis worker_version.

Règles frontend

• L'état public et l'état de l'Agent sont des sources différentes ; ne les fusionnez pas en un seul booléen.
• lite=1 sert le premier affichage ; les graphiques se chargent à l'ouverture des détails.
• Erreurs, données vides et warnings[] doivent s'afficher séparément.
• Rendez le texte API avec textContent ou un helper d'échappement unifié.
• Vérifiez les largeurs 320, 375, 390, 768, 1280 et 1440 px sans débordement horizontal de page.
• Les modales exigent un piège de focus, Échap pour fermer, verrouillage du défilement en arrière-plan et restauration du focus de l'ouvreur.
• Incrémentez la clé de cache de contenu quand les assets statiques changent et figez la clé courante dans les tests.

Règles Agent

• La capacité disque root est le volume système, pas une somme de montages ; l'IO Linux utilise un seul niveau de comptabilité cohérent pour éviter le double comptage entre partitions, LVM et périphériques physiques.
• La file hors ligne écrit avec des permissions restreintes, un remplacement atomique et fsync ; en cas d'échec, elle reste dirty.
• Videz avant l'ACK d'envoi, la sortie et les redémarrages de mise à jour.
• Les métriques d'entrée exigent une validation de type, de plage et de fenêtre temporelle.
• Installation, mise à jour et rollback préservent la propriété du binaire, les permissions d'exécution et la chaîne SHA-256.
• Les actions fixes NQ/IP n'acceptent que les énumérations d'actions compilées ; ne les étendez jamais en commandes, URL, arguments ou plannings arbitraires.

Versions et publication

L'application, le Worker, la documentation et l'Agent partagent un seul numéro de version. Les versions stables s'incrémentent en décimal : patch 1.1.93, prochaine mineure 1.2.0 ; jamais de bascule à 1.0.99.

App/Worker/docs : 1.1.93
Agent : v1.1.93
Tag source App : app-v1.1.93
Tag/Release Agent : v1.1.93

Ne réécrivez jamais un binaire publié de la même version et ne déplacez pas les tags publics. Incrémentez la version avant les changements au niveau publication, puis testez, buildiez, générez les sommes de contrôle et créez les assets de release en local. Les corrections purement documentaires peuvent conserver la version produit mais doivent préciser que le runtime est inchangé.

Le dépôt public est le seul instantané de source, manifest de mise à jour et point d'entrée de distribution des releases pour les auto-hébergeurs ; les dépôts privés Agent/Worker et Frontend sont les sources de production, exportées à sens unique via l'assainisseur. Les builds un clic publics téléchargent la release épinglée par update-manifest.json ; les Agents de production s'installent et se mettent à jour depuis /bin du site déployé et n'interrogent jamais l'API GitHub.

Publication et déploiement

1. Porte locale : bash test.sh exécute toute la suite Worker, frontend et manifeste d'installation ; agent/build-release.sh construit les binaires des sept architectures et écrit bin/VERSION et bin/SHA256SUMS.
2. Chaîne de hachage : les nouvelles empreintes vont dans setup.sh/update.sh (SHA256SUMS_SHA256), puis install.sh/quick-install.sh (DEFAULT_SETUP_SHA256), enfin dans les tests du manifeste et le modèle de commande d'installation du panneau.
3. Publication : commit et push du dépôt Agent privé avec tag vX.Y.Z et GitHub Release (sept assets) → commit et tag du dépôt frontend → export public unidirectionnel et copie des tags vX.Y.Z/app-vX.Y.Z avec les assets de release dans le dépôt public (le déploiement en un clic et la mise à jour en ligne en dépendent) → déploiement via worker/deploy.sh → vérification avec scripts/smoke-prod.mjs.
4. Mises à jour auto-hébergées : le workflow NIE-SLA Online Update vérifie la version stable toutes les 6 heures ; pour mettre à jour immédiatement, utilisez Run workflow dans l'onglet Actions du dépôt de déploiement. En cas de retard persistant, suivez la FAQ « Le panneau signale une nouvelle version mais rien ne se met à jour » ; sans Actions, synchronisez le dépôt puis exécutez npm run deploy.

Liste de contrôle avant commit

• L'arbre de travail ne contient que les fichiers dans le périmètre.
• Tests, formatage, lint, audit de dépendances et build de production passent.
• Les changements Worker passent un dry-run Wrangler.
• Le frontend passe les vérifications de page desktop/mobile.
• L'export public passe le scan de secrets et est généré à sens unique depuis les sources privées.
• Version, manifest, plan de tags, VERSION Agent et documentation concordent.
• Aucun journal de développement, cache, répertoire temporaire de build ou secret n'est committé.

Pour les frontends alternatifs uniquement, un fork complet du Worker est inutile ; voir Intégration API. Pour les changements purement visuels, utilisez les Thèmes.