From d4b15a0752a928e4a0f0d13571633fb3b2ea2c32 Mon Sep 17 00:00:00 2001
From: Nicolas Cantu <nicolas.cantu@pm.me>
Date: Wed, 27 Aug 2025 22:56:14 +0200
Subject: [PATCH] env: add ensure_env.sh; run.sh sources ~/.4nk_template/.env;
 docs: document local env management

---
 docs/project/CONFIGURATION.md |  9 ++++++++
 docs/project/GITEA_SETUP.md   |  1 -
 scripts/agents/run.sh         |  8 +++++++
 scripts/env/ensure_env.sh     | 42 +++++++++++++++++++++++++++++++++++
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 scripts/env/ensure_env.sh

diff --git a/docs/project/CONFIGURATION.md b/docs/project/CONFIGURATION.md
index cc94cf0..af6217c 100644
--- a/docs/project/CONFIGURATION.md
+++ b/docs/project/CONFIGURATION.md
@@ -17,6 +17,15 @@
 - bash requis (job CI `bash-required`)
 - Fallback PowerShell utilisable localement
 
+## Gestion locale des secrets (~/.4nk_template/.env)
+
+- Modèle fourni: `scripts/env/.env.template` (clés sans valeurs)
+- Provisionnement automatique: `scripts/env/ensure_env.sh`
+  - crée `~/.4nk_template/` (chmod 700) et `~/.4nk_template/.env` (chmod 600) si absent
+  - copie depuis le template puis demande de compléter
+  - vérifie les variables essentielles (ex: OPENAI_API_KEY, OPENAI_MODEL)
+- Chargement automatique: `scripts/agents/run.sh` source `~/.4nk_template/.env` si présent
+
 ## Lints Markdown
 
 - Configuration: `.markdownlint.json` (MD013 à 200 colonnes, MD024 en siblings_only)
diff --git a/docs/project/GITEA_SETUP.md b/docs/project/GITEA_SETUP.md
index 24f19d3..f3d7b35 100644
--- a/docs/project/GITEA_SETUP.md
+++ b/docs/project/GITEA_SETUP.md
@@ -27,4 +27,3 @@
 - Branche dédiée, PR petite et ciblée
 - CI verte, review approuvée
 - Doc et changelog à jour
-
diff --git a/scripts/agents/run.sh b/scripts/agents/run.sh
index 0247530..38092ae 100644
--- a/scripts/agents/run.sh
+++ b/scripts/agents/run.sh
@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Chargement env utilisateur (~/.4nk_template/.env)
+"$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/env/ensure_env.sh" || true
+if [[ -f "${HOME}/.4nk_template/.env" ]]; then
+  set -a
+  . "${HOME}/.4nk_template/.env"
+  set +a
+fi
+
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${1:-.}"
 OUTPUT_DIR="${2:-tests/reports/agents}"
diff --git a/scripts/env/ensure_env.sh b/scripts/env/ensure_env.sh
new file mode 100644
index 0000000..6435819
--- /dev/null
+++ b/scripts/env/ensure_env.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TEMPLATE_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/.env.template"
+ENV_DIR="${HOME}/.4nk_template"
+ENV_FILE="${ENV_DIR}/.env"
+
+mkdir -p "${ENV_DIR}"
+chmod 700 "${ENV_DIR}" || true
+
+if [[ ! -f "${ENV_FILE}" ]]; then
+  if [[ -f "${TEMPLATE_FILE}" ]]; then
+    cp "${TEMPLATE_FILE}" "${ENV_FILE}"
+    chmod 600 "${ENV_FILE}" || true
+    echo "Fichier d'environnement créé: ${ENV_FILE}" >&2
+    echo "Veuillez renseigner les variables requises (OPENAI_API_KEY, OPENAI_MODEL, etc.)." >&2
+    exit 3
+  else
+    echo "Modèle d'environnement introuvable: ${TEMPLATE_FILE}" >&2
+    exit 2
+  fi
+fi
+
+# Charger pour validation
+set -a
+. "${ENV_FILE}"
+set +a
+
+MISSING=()
+for var in OPENAI_API_KEY OPENAI_MODEL; do
+  if [[ -z "${!var:-}" ]]; then
+    MISSING+=("$var")
+  fi
+done
+
+if (( ${#MISSING[@]} > 0 )); then
+  echo "Variables manquantes dans ${ENV_FILE}: ${MISSING[*]}" >&2
+  exit 4
+fi
+
+echo "Environnement valide: ${ENV_FILE}" >&2