4NK_template/docs/project/USAGE.md

Installation des dépendances hôte (Debian/Ubuntu)

Exécuter en root:

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

# 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é)

# 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

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

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)

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:

#!/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:

#!/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 scripts/local/install_hooks.sh

• Agents utiles en premier passage: documentation, quality-technique, open-source, securite, deploiement

Script de merge local (main/develop)

# 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