165 lines
6.4 KiB
Markdown
165 lines
6.4 KiB
Markdown
### Installation des dépendances hôte (Debian/Ubuntu)
|
||
|
||
Exécuter en root:
|
||
|
||
```bash
|
||
sudo ./scripts/local/install_host_deps.sh
|
||
```
|
||
|
||
Ce script installe: `dos2unix`, `rsync`, `direnv`, `git`, `curl`, `vim`, `tree`, `sed`, `net-tools`, `iproute2`, `procps`, `lsof`, `psmisc`, `htop`, `dstat`, `iotop`, `strace`, `ltrace`, `tcpdump`, `nmap`, `wget`, `jq`, `gawk`, `grep`, `coreutils`, `dnsutils`, `traceroute`, `whois`, `sysstat`, `iputils-ping`, `iputils-tracepath`, ainsi que Docker (`docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-buildx-plugin`, `docker-compose-plugin`).
|
||
|
||
# Guide d’usage — 4NK_template (projet)
|
||
|
||
Ce document explique comment utiliser le template pour initier, documenter, contrôler et publier des projets dérivés, en respectant les standards qualité, sécurité et open source.
|
||
|
||
## 1. Pré‑requis
|
||
|
||
- Git opérationnel et accès à votre forge (Gitea recommandé)
|
||
- CI activée sur le repository
|
||
- bash disponible pour les agents (recommandé). À défaut, fallback PowerShell local
|
||
|
||
## 2. Démarrer un projet dérivé
|
||
|
||
1) Créer un repository à partir de 4NK_template
|
||
2) Copier/adapter la documentation depuis `docs/templates/**` vers votre `docs/**`
|
||
3) Tenir `docs/INDEX.md` et `CHANGELOG.md` à jour
|
||
4) Activer les workflows CI et vérifier `release-guard`/`security-audit`
|
||
|
||
## 2.1 Intégrer 4NK_template dans un projet existant
|
||
|
||
```bash
|
||
# Depuis le dépôt 4NK_template
|
||
bash scripts/deploy/setup.sh <git_url_du_projet> [--dest DIR] [--force]
|
||
# Compléter ensuite ~/.4nk_template/.env si nécessaire (OPENAI_*, BASE_URL, RELEASE_TOKEN)
|
||
```
|
||
|
||
### Intégration via Docker (recommandé)
|
||
|
||
```bash
|
||
# Build l’image unifiée
|
||
docker compose -f docker-compose.ci.yml build
|
||
|
||
# Appliquer le template depuis le conteneur (monter le repo projet sur /host)
|
||
docker run --rm -v "$PWD":/work -v "/chemin/vers/projet":/host 4nk-template-ci:latest \
|
||
bash -lc "/work/scripts/deploy/setup.sh file:///host/.git --dest /host"
|
||
```
|
||
|
||
## 3. Documentation
|
||
|
||
- Utiliser les squelettes de `docs/templates/**` comme base
|
||
- Documenter uniquement votre domaine applicatif (le template reste générique)
|
||
- À chaque changement de code/dépendance/CI, synchroniser la doc correspondante
|
||
|
||
## 4. Agents (contrôles)
|
||
|
||
- Recommandé (bash): `scripts/agents/run.sh [target_dir] [output_dir] [agent]`
|
||
- Windows fallback: `scripts/agents/run.ps1 -TargetDir . -OutputDir tests/reports/agents -Agent <nom>`
|
||
- Conteneur (option): `docker compose -f docker-compose.ci.yml up --abort-on-container-exit`
|
||
- Rapports: `tests/reports/agents/*.md`
|
||
- Variables utiles: `RUNNER_MODE`, `BASE_URL`, `REGISTRATION_TOKEN`
|
||
- Script helper: `scripts/dev/run_project_ci.sh`
|
||
- Auto‑corrections: `AUTO_FIX=1` pour créer la structure de tests et des squelettes docs
|
||
|
||
## 5. Remplacer la CI par une exécution locale (recommandé)
|
||
|
||
- CI neutre par défaut: `CI_SKIP=true` dans le workflow; réactivez en le passant à `false` côté dépôt.
|
||
- Commits: contrôles rapides avant commit
|
||
```bash
|
||
npx -y markdownlint-cli "**/*.md" --ignore "archive/**"
|
||
AUTO_FIX=1 SCOPE=changed scripts/agents/run.sh
|
||
# Ajoutez [skip ci] dans le message de commit pour éviter les runs distants
|
||
```
|
||
- Push: contrôles complets pré‑push
|
||
```bash
|
||
AUTO_FIX=1 SCOPE=all scripts/agents/run.sh
|
||
bash scripts/security/audit.sh || true
|
||
# Si outillage présent (exemples): cargo check / go vet / npx eslint / tsc --noEmit / ruff…
|
||
bash scripts/release/guard.sh || true
|
||
```
|
||
- Release locale (puis push tag)
|
||
```bash
|
||
echo "vYYYY.MM.P" > TEMPLATE_VERSION
|
||
git add TEMPLATE_VERSION CHANGELOG.md
|
||
git commit -m "[skip ci] chore(release): vYYYY.MM.P"
|
||
git tag -a vYYYY.MM.P -m "release: vYYYY.MM.P (latest)"
|
||
git push && git push origin vYYYY.MM.P
|
||
```
|
||
|
||
### Hooks conseillés (agents centralisés via 4NK_template)
|
||
|
||
`.git/hooks/pre-commit`:
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -euo pipefail
|
||
PROJECT_DIR="$(git rev-parse --show-toplevel)"
|
||
TEMPLATE_DIR="$(cd "${PROJECT_DIR}/../4NK_template" && pwd)"
|
||
mkdir -p "${PROJECT_DIR}/tests/reports/agents"
|
||
"${TEMPLATE_DIR}/scripts/local/run_agents_for_project.sh" "${PROJECT_DIR}" "tests/reports/agents"
|
||
```
|
||
|
||
`.git/hooks/pre-push`:
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -euo pipefail
|
||
PROJECT_DIR="$(git rev-parse --show-toplevel)"
|
||
TEMPLATE_DIR="$(cd "${PROJECT_DIR}/../4NK_template" && pwd)"
|
||
mkdir -p "${PROJECT_DIR}/tests/reports/agents"
|
||
"${TEMPLATE_DIR}/scripts/local/run_agents_for_project.sh" "${PROJECT_DIR}" "tests/reports/agents"
|
||
if [ -f "${PROJECT_DIR}/scripts/security/audit.sh" ]; then (cd "${PROJECT_DIR}" && bash scripts/security/audit.sh) || true; fi
|
||
if [ -f "${PROJECT_DIR}/scripts/release/guard.sh" ]; then (cd "${PROJECT_DIR}" && bash scripts/release/guard.sh) || true; fi
|
||
```
|
||
|
||
Ou installez-les automatiquement (les hooks fournis appellent déjà le runner centralisé):
|
||
|
||
```bash
|
||
bash scripts/local/install_hooks.sh
|
||
```
|
||
|
||
- Agents utiles en premier passage: `documentation`, `quality-technique`, `open-source`, `securite`, `deploiement`
|
||
|
||
### Script de merge local (main/develop)
|
||
|
||
```bash
|
||
# Merge de la branche courante vers main (valide localement avant)
|
||
bash scripts/local/merge_branch.sh main
|
||
|
||
# Merge vers develop
|
||
bash scripts/local/merge_branch.sh develop
|
||
```
|
||
|
||
## 5. Qualité et CI
|
||
|
||
- Jobs attendus: qualité, tests (catégories pertinentes), documentation, security‑audit, bash‑required, release‑guard
|
||
- `bash-required` garantit la présence de bash et du runner des agents
|
||
- `release-guard` bloque les publications si tests/doc/build/sécurité/version/changelog/tag ne sont pas cohérents
|
||
|
||
## 6. Sécurité
|
||
|
||
- Secrets uniquement via la CI (variables d’environnement), jamais en clair dans le dépôt
|
||
- Audit sécurité automatisé (job `security-audit`) et remédiations tracées dans `CHANGELOG.md`
|
||
|
||
## 7. Workflow quotidien
|
||
|
||
- Éditer: code et documentation (toujours en parallèle)
|
||
- Exécuter: tests locaux, agents (diagnostics)
|
||
- Vérifier: sorties CI, rapports `tests/reports/`
|
||
- Commiter: messages clairs, PR petites et ciblées
|
||
|
||
## 8. Publication
|
||
|
||
- Choisir `latest` (tag `vX.Y.Z`) ou `wip` (ex: `vX.Y.Z-wip.N`)
|
||
- Aligner: fichier de version, `CHANGELOG.md`, tag git
|
||
- Déployer si pipeline défini; sinon documenter la procédure
|
||
|
||
## 9. Dépannage
|
||
|
||
- Agents fallback PowerShell si bash indisponible localement
|
||
- Consulter `tests/reports/agents/*.md` pour les écarts à corriger
|
||
- Vérifier les logs de la CI et le job `release-guard`
|
||
|
||
## 10. Bonnes pratiques
|
||
|
||
- Pas d’exemples applicatifs dans le template
|
||
- Toujours mettre à jour la documentation et le changelog
|
||
- Réduire la dérive: synchroniser régulièrement vos projets avec les squelettes et standards
|