diff --git a/CHANGELOG.md b/CHANGELOG.md index 53094b3..bb3d396 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - CI: job `markdownlint` pour contrôler les lints Markdown (MD013/MD024/MD036) - CI: job `release-create` pour publier une release via l’API Gitea (secret `RELEASE_TOKEN`) - Script de déploiement: `scripts/deploy/setup.sh` (provisionnement `~/.4nk_template/.env` sécurisé) + - Déploiement: copie étendue (.cursor, AGENTS.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, TEMPLATE_VERSION, .markdownlint.json, .cursorignore, .gitignore, security/, scripts/) ### Changed - Documentation projet réécrite à partir des modèles `docs/templates/**` (générique, non applicative) diff --git a/docs/project/AGENTS_RUNTIME.md b/docs/project/AGENTS_RUNTIME.md index c0b9e91..015f204 100644 --- a/docs/project/AGENTS_RUNTIME.md +++ b/docs/project/AGENTS_RUNTIME.md @@ -3,15 +3,18 @@ Ce guide décrit comment utiliser et intégrer les agents de conformité (qualité, documentation, sécurité, déploiement, etc.) fournis par le template. ## 1. Présentation + - Agents bash (recommandé) avec rapports Markdown - Fallback PowerShell (Windows) produisant des contrôles simplifiés - Intégration CI (agents-smoke, openia-agents) et garde `bash-required` ## 2. Prérequis + - bash disponible (Git Bash/WSL/Linux/macOS) pour les contrôles complets - (Optionnel) `OPENAI_API_KEY` pour activer l’analyse IA ## 3. Commandes + - Bash (recommandé): - `scripts/agents/run.sh [target_dir] [output_dir] [agent]` - Par défaut: `target_dir=.` `output_dir=tests/reports/agents` `agent=all` @@ -19,6 +22,7 @@ Ce guide décrit comment utiliser et intégrer les agents de conformité (qualit - `scripts/agents/run.ps1 -TargetDir . -OutputDir tests/reports/agents -Agent ` ## 4. Agents disponibles + - Documentation (`documentation`): fichiers essentiels et index - Qualité technique (`quality-technique`): fichiers de base, lint/type-check si outillage présent - Open source (`open-source`): LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, checklists @@ -37,20 +41,23 @@ Ce guide décrit comment utiliser et intégrer les agents de conformité (qualit - Dérogations locales (`derogations-locales`): fichier de dérogations ## 5. Sorties + - Rapports Markdown: `tests/reports/agents/*.md` - À relire avant PR; corriger les écarts signalés ## 6. Intégration CI + - `agents-smoke`: agents en mode sans IA (rapports artefacts) - `openia-agents`: agents avec IA si `OPENAI_API_KEY` fourni - `bash-required`: bloque si bash/runner absent - `release-guard`: dépend des checks en amont ## 7. Paramètres IA (optionnels) + - `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_API_BASE`, `OPENAI_TEMPERATURE` ## 8. Bonnes pratiques + - Exécuter les agents avant chaque PR - Archiver les rapports significatifs - Documenter les décisions dans le changelog et la doc - diff --git a/docs/project/ARCHITECTURE.md b/docs/project/ARCHITECTURE.md index 2c5a5bb..cb167b9 100644 --- a/docs/project/ARCHITECTURE.md +++ b/docs/project/ARCHITECTURE.md @@ -1,6 +1,7 @@ # Architecture — 4NK_template ## Arborescence de référence + - `.gitea/**` — Workflows CI et templates Gitea - `docs/project/**` — Doc du template - `docs/templates/**` — Modèles à copier @@ -8,13 +9,14 @@ - `tests/**` — Structure de tests, logs, rapports ## Découpage + - Documentation (templates vs project) - Qualité et CI (jobs, garde de release) - Sécurité (audit, secrets) - Agents (contrôles automatiques) ## Invariants + - Pas d’exemples applicatifs dans le template - Documentation et changelog à jour à chaque changement - CI bloquante si prérequis manquants (bash-required) - diff --git a/docs/project/DEPLOYMENT.md b/docs/project/DEPLOYMENT.md index f112591..90b7008 100644 --- a/docs/project/DEPLOYMENT.md +++ b/docs/project/DEPLOYMENT.md @@ -18,11 +18,21 @@ - Crée `~/.4nk_template/` (chmod 700) et `~/.4nk_template/.env` (chmod 600) - Copie depuis `scripts/env/.env.template` si présent, sinon génère un modèle - À compléter: `OPENAI_API_KEY`, `OPENAI_MODEL`, `RELEASE_TOKEN`, `GITEA_BASE_URL` (si custom) + - Applique la structure 4NK_template au projet cible (sans écraser par défaut): + - `.gitea/**`, `.cursor/**`, `.cursorignore`, `.gitignore`, `.markdownlint.json` + - `AGENTS.md`, `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `TEMPLATE_VERSION` + - `scripts/**` (dont `agents/`, `env/ensure_env.sh`, `deploy/setup.sh`), `security/` (si présent) + - `docs/templates/**` et génération `docs/INDEX.md` Exécution: ```bash -bash scripts/deploy/setup.sh +# Provisionner l'environnement local (~/.4nk_template/.env) + cloner + appliquer le template +bash scripts/deploy/setup.sh [--dest DIR] [--force] + +# Exemples +bash scripts/deploy/setup.sh https://git.example.com/org/mon-projet.git +bash scripts/deploy/setup.sh git@host:org/mon-projet.git --dest ~/work --force ``` ## Rollback @@ -32,4 +42,3 @@ bash scripts/deploy/setup.sh ## Post‑déploiement - Vérification santé/logs/dashboards - Suivi des erreurs et retours - diff --git a/scripts/deploy/setup.sh b/scripts/deploy/setup.sh index 48507e6..2749d49 100644 --- a/scripts/deploy/setup.sh +++ b/scripts/deploy/setup.sh @@ -3,20 +3,59 @@ set -euo pipefail ENV_DIR="${HOME}/.4nk_template" ENV_FILE="${ENV_DIR}/.env" -TEMPLATE_IN_REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/env/.env.template" +TEMPLATE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +TEMPLATE_IN_REPO="${TEMPLATE_ROOT}/scripts/env/.env.template" + +usage() { + cat < [--dest DIR] [--force] + +Actions: + 1) Provisionne ~/.4nk_template/.env (si absent) + 2) Clone le dépôt cible si le dossier n'existe pas + 3) Copie la structure normative 4NK_template dans le projet cible: + - .gitea/** (workflows, templates issues/PR) + - AGENTS.md + - .cursor/rules/** (si présent) + - scripts/agents/**, scripts/env/ensure_env.sh, scripts/deploy/setup.sh + - docs/templates/** et docs/INDEX.md (table des matières) + 4) Ne remplace pas les fichiers existants sauf si --force + +Exemples: + $0 https://git.example.com/org/projet.git + $0 git@host:org/projet.git --dest ~/work --force +USAGE +} + +GIT_URL="${1:-}" +DEST_PARENT="$(pwd)" +FORCE_COPY=0 +shift || true +while [[ $# -gt 0 ]]; do + case "$1" in + --dest) + DEST_PARENT="${2:-}"; shift 2 ;; + --force) + FORCE_COPY=1; shift ;; + -h|--help) + usage; exit 0 ;; + *) + echo "Option inconnue: $1" >&2; usage; exit 2 ;; + esac +done + +if [[ -z "${GIT_URL}" ]]; then + usage; exit 2 +fi mkdir -p "${ENV_DIR}" chmod 700 "${ENV_DIR}" || true -if [[ -f "${ENV_FILE}" ]]; then - echo "Env déjà présent: ${ENV_FILE}" >&2 - exit 0 -fi - -if [[ -f "${TEMPLATE_IN_REPO}" ]]; then - cp "${TEMPLATE_IN_REPO}" "${ENV_FILE}" -else - cat >"${ENV_FILE}" <<'EOF' +if [[ ! -f "${ENV_FILE}" ]]; then + if [[ -f "${TEMPLATE_IN_REPO}" ]]; then + cp "${TEMPLATE_IN_REPO}" "${ENV_FILE}" + else + cat >"${ENV_FILE}" <<'EOF' # Fichier d'exemple d'environnement pour 4NK_template # Copiez ce fichier vers ~/.4nk_template/.env puis complétez les valeurs. # Ne committez jamais de fichier contenant des secrets. @@ -31,10 +70,76 @@ OPENAI_TEMPERATURE=0.2 GITEA_BASE_URL=https://git.4nkweb.com RELEASE_TOKEN= EOF + fi + chmod 600 "${ENV_FILE}" || true + echo "Fichier créé: ${ENV_FILE}. Complétez les valeurs requises (ex: OPENAI_API_KEY, OPENAI_MODEL, RELEASE_TOKEN)." >&2 fi -chmod 600 "${ENV_FILE}" || true -echo "Fichier créé: ${ENV_FILE}. Complétez les valeurs requises (ex: OPENAI_API_KEY, OPENAI_MODEL, RELEASE_TOKEN)." >&2 +# 2) Clonage du dépôt si nécessaire +repo_name="$(basename -s .git "${GIT_URL}")" +target_dir="${DEST_PARENT%/}/${repo_name}" +if [[ ! -d "${target_dir}" ]]; then + echo "Clonage: ${GIT_URL} → ${target_dir}" >&2 + git clone --depth 1 "${GIT_URL}" "${target_dir}" +else + echo "Dossier existant, pas de clone: ${target_dir}" >&2 +fi + +copy_item() { + local src="$1" dst="$2" + if [[ ! -e "$src" ]]; then return 0; fi + if [[ -d "$src" ]]; then + mkdir -p "$dst" + if (( FORCE_COPY )); then + cp -a "$src/." "$dst/" + else + (cd "$src" && find . -type f -print0) | while IFS= read -r -d '' f; do + if [[ ! -e "$dst/$f" ]]; then + mkdir -p "$(dirname "$dst/$f")" + cp -a "$src/$f" "$dst/$f" + fi + done + fi + else + if [[ -e "$dst" && $FORCE_COPY -eq 0 ]]; then return 0; fi + mkdir -p "$(dirname "$dst")" && cp -a "$src" "$dst" + fi +} + +# 3) Copie de la structure normative +copy_item "${TEMPLATE_ROOT}/.gitea" "${target_dir}/.gitea" +copy_item "${TEMPLATE_ROOT}/AGENTS.md" "${target_dir}/AGENTS.md" +copy_item "${TEMPLATE_ROOT}/.cursor" "${target_dir}/.cursor" +copy_item "${TEMPLATE_ROOT}/.cursorignore" "${target_dir}/.cursorignore" +copy_item "${TEMPLATE_ROOT}/.gitignore" "${target_dir}/.gitignore" +copy_item "${TEMPLATE_ROOT}/.markdownlint.json" "${target_dir}/.markdownlint.json" +copy_item "${TEMPLATE_ROOT}/LICENSE" "${target_dir}/LICENSE" +copy_item "${TEMPLATE_ROOT}/CONTRIBUTING.md" "${target_dir}/CONTRIBUTING.md" +copy_item "${TEMPLATE_ROOT}/CODE_OF_CONDUCT.md" "${target_dir}/CODE_OF_CONDUCT.md" +copy_item "${TEMPLATE_ROOT}/SECURITY.md" "${target_dir}/SECURITY.md" +copy_item "${TEMPLATE_ROOT}/TEMPLATE_VERSION" "${target_dir}/TEMPLATE_VERSION" +copy_item "${TEMPLATE_ROOT}/security" "${target_dir}/security" +copy_item "${TEMPLATE_ROOT}/scripts" "${target_dir}/scripts" +copy_item "${TEMPLATE_ROOT}/docs/templates" "${target_dir}/docs/templates" + +# Génération docs/INDEX.md dans le projet cible (si absent ou --force) +INDEX_DST="${target_dir}/docs/INDEX.md" +if [[ ! -f "${INDEX_DST}" || $FORCE_COPY -eq 1 ]]; then + mkdir -p "$(dirname "${INDEX_DST}")" + cat >"${INDEX_DST}" <<'IDX' +# Documentation du projet + +Cette table des matières oriente vers: +- Documentation spécifique au projet: `docs/project/` +- Modèles génériques à adapter: `docs/templates/` + +## Sommaire +- À personnaliser: `docs/project/README.md`, `docs/project/INDEX.md`, `docs/project/ARCHITECTURE.md`, `docs/project/USAGE.md`, etc. + +## Modèles génériques +- Voir: `docs/templates/` +IDX +fi + +echo "Template 4NK appliqué à: ${target_dir}" >&2 exit 0 - -