codoc-cli 0.1.2

package/dist/services/conversion/shared/preserved-macros.js

@@ -0,0 +1,8 @@
+import { escapeXml } from "./xml-escaping.js";
+//#region src/services/conversion/shared/preserved-macros.ts
+const PRESERVED_MACRO_ATTR = "data-confluence-macro-preserved";
+function preserveAsSentinel(xml) {
+	return `<div ${PRESERVED_MACRO_ATTR}="1">${escapeXml(xml)}</div>`;
+}
+//#endregion
+export { PRESERVED_MACRO_ATTR, preserveAsSentinel };

package/dist/services/conversion/shared/read-storage-format.js

@@ -0,0 +1,29 @@
+import { memoizedRegex } from "./regex-cache.js";
+//#region src/services/conversion/shared/read-storage-format.ts
+const macroParamRegexFor = memoizedRegex((name) => new RegExp(`<ac:parameter[^>]*ac:name="${name}"[^>]*>([\\s\\S]*?)<\\/ac:parameter>`));
+const macroRegexFor = memoizedRegex((name) => new RegExp(`<ac:structured-macro[^>]*ac:name="${name}"[^>]*>[\\s\\S]*?<\\/ac:structured-macro>`, "g"));
+/** Valeur (trimée) d'un `<ac:parameter ac:name="NAME">…</ac:parameter>`, ou undefined.
+*  `name` est inséré tel quel dans la regex (les motifs comme "colou?r" sont donc supportés). */
+function macroParam(inner, name) {
+	return inner.match(macroParamRegexFor(name))?.[1]?.trim();
+}
+/** Regex globale matchant toutes les `<ac:structured-macro ac:name="NAME">…</ac:structured-macro>`. */
+function macroRegex(name) {
+	return macroRegexFor(name);
+}
+/** Position juste après le `</div>` fermant le `<div` ouvert à `start` (gère l'imbrication). */
+function findDivEnd(s, start) {
+	let depth = 0;
+	let i = start;
+	while (i < s.length) if (s.startsWith("<div", i) && /[\s>]/.test(s[i + 4] ?? "")) {
+		depth++;
+		i += 4;
+	} else if (s.startsWith("</div>", i)) {
+		depth--;
+		if (depth === 0) return i + 6;
+		i += 6;
+	} else i++;
+	return s.length;
+}
+//#endregion
+export { findDivEnd, macroParam, macroRegex };

package/dist/services/conversion/shared/regex-cache.js

@@ -0,0 +1,14 @@
+//#region src/services/conversion/shared/regex-cache.ts
+function memoizedRegex(build) {
+	const cache = /* @__PURE__ */ new Map();
+	return (key) => {
+		let re = cache.get(key);
+		if (!re) {
+			re = build(key);
+			cache.set(key, re);
+		}
+		return re;
+	};
+}
+//#endregion
+export { memoizedRegex };

package/dist/services/conversion/shared/xml-escaping.js

@@ -0,0 +1,19 @@
+//#region src/services/conversion/shared/xml-escaping.ts
+/** Échappe le contenu XML : `&` `<` `>`. */
+function escapeXml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Échappe une valeur d'attribut XML : `&` `<` `>` `"`. */
+function escapeAttr(text) {
+	return escapeXml(text).replace(/"/g, "&quot;");
+}
+/** Inverse exact d'{@link escapeXml} : `&lt;` `&gt;` `&amp;`. */
+function unescapeXml(text) {
+	return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+/** Neutralise les séquences de fin de CDATA `]]>` dans un contenu destiné à `<![CDATA[…]]>`. */
+function escapeCdata(text) {
+	return text.replace(/]]>/g, "]]]]><![CDATA[>");
+}
+//#endregion
+export { escapeAttr, escapeCdata, escapeXml, unescapeXml };

package/dist/services/ensure-env.js

@@ -0,0 +1,59 @@
+import { fileExists, readFile, writeFile } from "./files-service.js";
+import { CODOC_ENV_FILE } from "../config/codoc-paths.js";
+import { log } from "./log/logger.js";
+import { confirm, input, password } from "@inquirer/prompts";
+//#region src/services/ensure-env.ts
+async function ensureEnvVars(requirements) {
+	for (const { name, satisfiedBy, ...opts } of requirements) {
+		if (satisfiedBy?.some((n) => process.env[n]?.trim())) continue;
+		await ensureEnvVar(name, opts);
+	}
+}
+async function ensureEnvVar(name, opts) {
+	const existing = process.env[name];
+	if (existing && existing.trim()) return existing.trim();
+	log.blank();
+	log.warning0(`${name} n'est pas défini.`);
+	log.raw(`     ${opts.hint}`);
+	if (opts.generateUrl) log.raw(`     Pour le générer : ${opts.generateUrl}`);
+	const secret = opts.secret !== false;
+	let value;
+	try {
+		value = secret ? await password({
+			message: `  Saisis ${name} (Entrée vide pour skip) :`,
+			mask: "*"
+		}) : await input({ message: `  Saisis ${name} (Entrée vide pour skip) :` });
+	} catch {
+		return;
+	}
+	value = value.trim();
+	if (!value) return void 0;
+	process.env[name] = value;
+	if (await confirm({
+		message: `  Sauvegarder ${name} dans .env-codoc pour les prochains runs ?`,
+		default: true
+	}).catch(() => false)) {
+		upsertEnvLine(name, value);
+		log.success1(`[UPDATED] ${name} sauvegardé dans .env-codoc`);
+	}
+	return value;
+}
+function upsertEnvLine(name, value) {
+	const lineRe = new RegExp(`^\\s*${escapeRegex(name)}\\s*=.*$`, "m");
+	const newLine = `${name}=${value}`;
+	if (!fileExists(CODOC_ENV_FILE)) {
+		writeFile(CODOC_ENV_FILE, `${newLine}\n`);
+		return;
+	}
+	const content = readFile(CODOC_ENV_FILE);
+	if (lineRe.test(content)) writeFile(CODOC_ENV_FILE, content.replace(lineRe, newLine));
+	else {
+		const sep = content.endsWith("\n") ? "" : "\n";
+		writeFile(CODOC_ENV_FILE, `${content}${sep}${newLine}\n`);
+	}
+}
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+export { ensureEnvVar, ensureEnvVars };

package/dist/services/files-service.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import os from "node:os";
+//#region src/services/files-service.ts
+const DEFAULT_SKIP_DIRS = [
+	"node_modules",
+	".git",
+	"target",
+	"build",
+	"generated-sources"
+];
+/** Lit le contenu texte d'un fichier (UTF-8). */
+function readFile(absolutePath) {
+	return fs.readFileSync(absolutePath, "utf8");
+}
+/** Vrai si le chemin existe (fichier ou dossier). */
+function fileExists(absolutePath) {
+	return fs.existsSync(absolutePath);
+}
+/** Convertit les séparateurs Windows (`\`) en séparateurs POSIX (`/`), sans autre normalisation. */
+function toPosixPath(p) {
+	return p.replace(/\\/g, "/");
+}
+/** Crée un dossier (et ses parents) s'il n'existe pas déjà. */
+function ensureDir(absoluteDirectoryPath) {
+	fs.mkdirSync(absoluteDirectoryPath, { recursive: true });
+}
+/** Vrai si le chemin existe et est un dossier. */
+function isDirectory(absolutePath) {
+	return fs.existsSync(absolutePath) && fs.statSync(absolutePath).isDirectory();
+}
+/**
+* Aligne les fins de ligne du contenu sur celles de la plateforme d'exécution
+* (CRLF sous Windows, LF ailleurs) - le code du projet écrit toujours en `\n`,
+* sans ça les fichiers générés diffèrent systématiquement de la convention du
+* dépôt cible sous Windows (diffs entiers dus uniquement aux fins de ligne).
+*/
+function normalizeEol(content) {
+	return content.replace(/\r\n/g, "\n").replace(/\n/g, os.EOL);
+}
+/** Écrit un fichier texte (UTF-8), en créant le dossier parent au besoin. Fins de ligne alignées sur `os.EOL`. */
+function writeFile(absolutePath, content) {
+	ensureDir(path.dirname(absolutePath));
+	fs.writeFileSync(absolutePath, normalizeEol(content), "utf8");
+}
+/** Écrit un fichier binaire (Buffer), en créant le dossier parent au besoin. */
+function writeBinaryFile(absolutePath, content) {
+	ensureDir(path.dirname(absolutePath));
+	fs.writeFileSync(absolutePath, content);
+}
+/** Supprime un fichier ou dossier (récursif), sans erreur s'il est déjà absent. */
+function removePath(absolutePath) {
+	fs.rmSync(absolutePath, {
+		recursive: true,
+		force: true
+	});
+}
+/** Liste récursivement les fichiers dont l'extension figure dans `exts` (dossiers de build ignorés). */
+async function collectFiles(dir, exts, skipDirs = DEFAULT_SKIP_DIRS) {
+	const skip = new Set(skipDirs);
+	const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (skip.has(entry.name)) continue;
+			files.push(...await collectFiles(fullPath, exts, skipDirs));
+		} else if (entry.isFile() && exts.some((e) => entry.name.endsWith(e))) files.push(fullPath);
+	}
+	return files;
+}
+//#endregion
+export { collectFiles, ensureDir, fileExists, isDirectory, readFile, removePath, toPosixPath, writeBinaryFile, writeFile };

package/dist/services/git/default-branch.js

@@ -0,0 +1,33 @@
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { getGitlabConfig } from "../../config/codoc-config.js";
+import { simpleGit } from "simple-git";
+//#region src/services/git/default-branch.ts
+let cached;
+async function getDefaultBranch() {
+	if (cached) return cached;
+	const fromConfig = getGitlabConfig().defaultBranch;
+	if (fromConfig) {
+		cached = fromConfig;
+		return cached;
+	}
+	if (process.env.CI_DEFAULT_BRANCH) {
+		cached = process.env.CI_DEFAULT_BRANCH;
+		return cached;
+	}
+	try {
+		cached = (await simpleGit(PROJECT_ROOT).raw([
+			"symbolic-ref",
+			"--short",
+			"refs/remotes/origin/HEAD"
+		])).trim().replace(/^origin\//, "");
+		if (cached) return cached;
+	} catch {}
+	cached = "main";
+	return cached;
+}
+/** Utilitaire pour les tests : réinitialise le cache. */
+function resetDefaultBranchCache() {
+	cached = void 0;
+}
+//#endregion
+export { getDefaultBranch, resetDefaultBranchCache };

package/dist/services/init-templates/agent-md-init.js

@@ -0,0 +1,55 @@
+//#region src/services/init-templates/agent-md-init.ts
+function docRules(d) {
+	const overrides = (d.keywordOverrides ?? []).map((o) => ({
+		keywords: o.keywords,
+		location: o.path
+	}));
+	const baseKeywords = d.keywords?.length ? d.keywords : [d.confluence.title ?? d.path];
+	return [...overrides, {
+		keywords: baseKeywords,
+		location: d.path
+	}];
+}
+function renderRule(r) {
+	return `- when:\n    contains_any: [${r.keywords.map((k) => JSON.stringify(k)).join(", ")}]\n  use: "${r.location}"`;
+}
+function agentMdContent(config) {
+	const rules = config.docs.flatMap(docRules);
+	const routing = rules.length ? rules.map(renderRule).join("\n\n") : "# (aucune documentation indexée pour ce projet)";
+	const hasConfluenceDocs = config.docs.some((d) => d.maintainedIn === "confluence");
+	const envsLines = config.atlassian.environments.length ? config.atlassian.environments.map((e) => `- \`${e.key}\` → baseUrl \`${e.baseUrl}\`, espace \`${e.spaceKey}\``).join("\n") : "_Aucun environnement Confluence configuré._";
+	return `# Documentation du projet - index pour agents IA
+
+## RÈGLES OBLIGATOIRES
+
+1. Avant de répondre, de proposer du code, ou de décrire un comportement existant : vérifie la section ROUTAGE.
+2. Une règle \`contains_any\` correspond au sujet → base ta réponse sur le fichier \`use\`, jamais sur ta mémoire générale ni une recherche libre dans le code. Plusieurs règles correspondent → privilégie celle dont le \`use\` est le plus spécifique (chemin le plus précis).
+3. Aucune règle ne correspond → dis-le explicitement, ne présume pas d'une source, puis appuie-toi sur une lecture directe du code.
+4. N'invente jamais un fichier ou une page Confluence absent de ce document.
+5. Termine toujours ta réponse au format défini dans FORMAT DE RÉPONSE.
+
+## ROUTAGE
+
+\`\`\`yaml
+${routing}
+\`\`\`
+${hasConfluenceDocs ? `
+## CONFLUENCE
+
+${envsLines}
+
+Pour une doc \`confluence\`, la page fait foi et \`codoc.lock\` (racine du projet) donne son URL :
+1. Cherche l'entrée dont \`sourceFile\` correspond au fichier \`use\` de la règle appliquée.
+2. \`confluenceUrl\` présent → lien direct.
+3. Absent (page pas encore publiée) → reconstruit avec \`{baseUrl}/wiki/spaces/{spaceKey}/pages/{confluencePageId}\`.
+` : ""}
+## FORMAT DE RÉPONSE
+
+\`\`\`
+SOURCE: <fichier, code direct et/ou page Confluence associée dans le lock>
+RÉPONSE: <ta réponse>
+\`\`\`
+`;
+}
+//#endregion
+export { agentMdContent };

package/dist/services/init-templates/doc-guide-init.js

@@ -0,0 +1,131 @@
+//#region src/services/init-templates/doc-guide-init.ts
+function docguideContent(id) {
+	return `> **Page d'exemple** - générée par \`codoc init\`. Supprime l'entrée de \`codoc.yaml\` puis relance \`codoc sync\` pour la retirer.
+
+# Guide codoc - ${id}
+
+## Rôle
+
+\`codoc\` synchronise des \`.md\` locaux avec des pages Confluence, dans les deux sens.
+
+Chaque doc déclarée dans \`codoc.yaml\` a une "source de vérité" mentionnée :
+
+| \`maintainedIn\` | Source de vérité | Action de \`sync\` |
+|---|---|---|
+| \`code\` | Le \`.md\` local | Publie / met à jour la page Confluence |
+| \`confluence\` | La page Confluence | Régénère le \`.md\` local |
+
+## Commandes
+
+Résolution des informations dans l'ordre **flag CLI** → **valeur déjà présente dans \`codoc.yaml\`** → **prompt console** (pas de mode CI détecté automatiquement - un pipeline doit fournir tout ce qu'il faut pour rester silencieux).
+
+### \`codoc init\`
+
+Génère la config initiale (codoc.yaml, .env-codoc, guide).
+
+| Flag | Rôle |
+|---|---|
+| \`--agent-md\` | Ne génère QUE le guide agent IA (basé sur \`codoc.yaml\` déjà rempli) - rien d'autre |
+| \`--agent-target <agent\\|copilot>\` | Avec \`--agent-md\` : destination du guide. Défaut : celle déjà en place, sinon demandé |
+
+### \`codoc sync\`
+
+Synchronise chaque doc dans les deux sens selon son \`maintainedIn\`.
+
+| Flag | Rôle |
+|---|---|
+| \`--env <clé>\` | Ne synchronise que cet environnement Confluence. Défaut : tous |
+| \`--confirm\` / \`--no-confirm\` | Répond automatiquement aux suppressions/adoptions en conflit de titre (accepte/refuse tout). Non fourni : demande à chaque cas |
+
+### \`codoc pull [url\\|id]\`
+
+Importe une page Confluence existante en local (interactif).
+
+| Flag | Rôle |
+|---|---|
+| \`--env <clé>\` | Environnement où chercher la page. Défaut : déduit de l'URL, sinon auto/prompt |
+| \`--as-folder\` / \`--no-as-folder\` | Sous-éléments détectés : importe tout le dossier, ou seulement la page. Non fourni : demande le cas échéant |
+| \`--keep-existing\` / \`--no-keep-existing\` | Import précédent détecté : le remplace, ou en crée un séparé. Non fourni : demande le cas échéant |
+| \`--in-config\` / \`--no-in-config\` | Ajoute/met à jour l'entrée \`codoc.yaml\`. \`--no-in-config\` : import ponctuel, hors suivi (yaml et lock non touchés). Non fourni : demande en fin de commande |
+| \`--local-path <chemin>\` | Chemin local du \`.md\` (page unique) ou dossier de destination (import dossier) |
+| \`--title <titre>\` | Titre de la page Confluence (page unique). Défaut : config existante, sinon le titre Confluence |
+| \`--parent-page-id <id>\` | parentPageId Confluence. Défaut : config existante, sinon le parent réel de la page |
+| \`--maintained-in <code\\|confluence>\` | \`code\` → le \`.md\` fait foi ; \`confluence\` → la page fait foi. Défaut : \`confluence\` |
+| \`--images-dir <chemin>\` | Dossier local pour les images (\`""\` pour désactiver). Défaut : \`doc/img\` |
+
+### \`codoc publish <chemin>\`
+
+Publie un \`.md\` local vers Confluence (interactif).
+
+| Flag | Rôle |
+|---|---|
+| \`--env <clé>\` | Environnement Confluence cible. Défaut : config existante, sinon auto/prompt |
+| \`--in-config\` / \`--no-in-config\` | Ajoute/met à jour l'entrée \`codoc.yaml\`. \`--no-in-config\` : publication ponctuelle, hors suivi (yaml et lock non touchés). Non fourni : demande en fin de commande |
+| \`--parent-page-id <id>\` | parentPageId Confluence cible. Défaut : config existante, sinon \`defaultParentPageId\` de l'env |
+| \`--title <titre>\` | Titre de la page Confluence (fichier unique). Défaut : config existante, sinon le H1 du fichier |
+
+### \`codoc tree\`
+
+Affiche l'arborescence des docs déployées.
+
+| Flag | Rôle |
+|---|---|
+| \`--env <clé>\` | N'affiche que cet environnement Confluence. Défaut : tous |
+
+\`pull\` et \`publish\` demandent en fin de commande s'il faut ajouter le document à \`codoc.yaml\` (défaut : oui) - répondre non (ou \`--no-in-config\`) permet un import/publication ponctuel, sans toucher ni à \`codoc.yaml\` ni à \`codoc.lock\`, non suivi par les prochains \`sync\`.
+
+## Configuration - \`codoc.yaml\`
+
+| Champ | Rôle |
+|---|---|
+| \`atlassian.environments.<clé>.baseUrl\` | URL Confluence |
+| \`atlassian.environments.<clé>.spaceKey\` | Clé de l'espace |
+| \`atlassian.environments.<clé>.defaultParentPageId\` | Page parente par défaut |
+| \`drawio.*\` | Réglages des diagrammes générés depuis les blocs \`\`\`mermaid (un seul jeu de valeurs, partagé par tous les environnements) |
+| \`gitlab.baseUrl\` / \`gitlab.defaultBranch\` | Réécrit les liens vers du code en URLs GitLab dans les pages publiées (optionnel) |
+| \`jira.serverId\` / \`jira.server\` | Rend les liens de tickets Jira sous forme de macro Confluence native (optionnel) |
+| \`docs[].codocId\` | Lien stable yaml ↔ lock |
+| \`docs[].path\` | Chemin du \`.md\` (ou glob \`/**\`) |
+| \`docs[].maintainedIn\` | \`code\` ou \`confluence\` |
+| \`docs[].generateSummary\` | Génère le sommaire (macro toc) en haut de page - \`maintainedIn: code\` uniquement (défaut : \`true\`) |
+| \`docs[].confluence.title\` | Titre de la page (défaut : \`# H1\` du fichier) |
+
+## Identifiants - \`.env-codoc\`
+
+Ne pas committer (ajouté à \`.gitignore\` par \`init\`).
+
+| Variable | Usage |
+|---|---|
+| \`CONFLUENCE_<CLÉ>_USERNAME\` | Email de compte Atlassian pour l'environnement \`<clé>\` |
+| \`CONFLUENCE_<CLÉ>_API_TOKEN\` | Token Atlassian pour l'environnement \`<clé>\` |
+
+Toujours préfixées par la clé de l'environnement (\`atlassian.environments.<clé>\` dans \`codoc.yaml\`) - même s'il n'y en a qu'un seul, ex. \`CONFLUENCE_DEFAULT_USERNAME\`. Pas de variable générique partagée entre environnements.
+
+## Workflow type
+
+\`\`\`
+1. codoc init          → génère yaml, env, guide
+2. Remplir codoc.yaml + .env-codoc
+3. codoc sync           → publie le guide sur Confluence
+\`\`\`
+
+## Format Markdown supporté
+
+| Markdown | Rendu Confluence |
+|---|---|
+| \`# Titre\` | Titre de section |
+| \`**gras**\` / \`*italique*\` | Gras / italique |
+| \`\`\`code\`\`\` | Code inline |
+| Bloc \`\`\`lang | Bloc de code avec coloration |
+| Bloc \`\`\`mermaid | Diagramme draw.io (converti + upload en pièce jointe) |
+| \`- [ ] tâche\` | Liste de tâches Confluence |
+| \`📅 2024-01-15\` | \`<time datetime="2024-01-15"/>\` |
+| \`<span data-confluence-status="Green">Livré</span>\` | Macro Status |
+
+## \`codoc.lock\`
+
+Généré par \`sync\` / \`pull\`. **À committer**. Trace les IDs Confluence pour les mises à jour idempotentes.
+`;
+}
+//#endregion
+export { docguideContent };

package/dist/services/init-templates/env-init.js

@@ -0,0 +1,12 @@
+//#region src/services/init-templates/env-init.ts
+function envTemplate() {
+	return `# Identifiants - NE PAS COMMITTER
+# Toujours préfixés par la clé de l'environnement Confluence (atlassian.environments.<clé> dans
+# codoc.yaml) - même s'il n'y en a qu'un seul, jamais de variable générique partagée.
+
+CONFLUENCE_DEFAULT_USERNAME=prenom.nom@entreprise.com
+CONFLUENCE_DEFAULT_API_TOKEN=votre_token_api_confluence
+`;
+}
+//#endregion
+export { envTemplate };

package/dist/services/init-templates/yaml-init.js

@@ -0,0 +1,56 @@
+//#region src/services/init-templates/yaml-init.ts
+function yamlTemplate(docRelPath, codocId) {
+	return `# Configuration codoc - généré par codoc init
+# Remplissez les champs marqués TODO puis lancez : codoc sync
+
+# Environnements Atlassian (Confluence/Jira) cibles. Au moins un. Une seule clé = la
+# référence par défaut côté docs. Identifiants toujours préfixés par la clé de l'env,
+# CONFLUENCE_<KEY>_USERNAME / CONFLUENCE_<KEY>_API_TOKEN dans .env-codoc.
+atlassian:
+  environments:
+    default:
+      baseUrl: https://TODO.atlassian.net       # URL de l'instance Confluence Cloud
+      spaceKey: TODO                            # Clé de l'espace Confluence cible (ex. DA)
+      defaultParentPageId: "TODO"               # ID de la page parente par défaut (optionnel)
+
+# Configuration draw.io (optionnel - blocs \`\`\`mermaid convertis en diagrammes). Un seul jeu de
+# réglages, partagé par tous les environnements Atlassian ci-dessus.
+# drawio:
+#   macroName: drawio
+#   width: 900
+#   edgeStyle: curved    # tracé : curved | orthogonal | straight
+#   edgeAnchor: side     # ancrage des flèches : side | auto (flottant)
+
+# Configuration GitLab (optionnel - réécrit les liens vers du code en URLs GitLab dans les pages publiées)
+# gitlab:
+#   baseUrl: https://TODO/mon-groupe/mon-repo
+#   defaultBranch: main         # branche cible des liens
+
+# Identifiants Jira (optionnel - liens tickets cliquables dans les pages Confluence publiées, sous
+# forme de macro Jira native).
+# jira:
+#   serverId: ec6d1637-f9d6-3ae4-9d5e-9dce283383ea
+#   server: System Jira
+
+docs:
+  - codocId: ${codocId}        # identifiant stable (lien yaml ↔ codoc.lock) - unique, ne pas réutiliser
+    path: ${docRelPath}
+    maintainedIn: code          # code → .md publie sur Confluence | confluence → Confluence publie en local
+    # generateSummary: false    # désactive le sommaire (macro toc) en haut de page - défaut : true (maintainedIn: code uniquement)
+    keywords: ["codoc", "comment fonctionne la synchro Confluence"]  # mots-clés de routage - alimentent codoc-agent.md
+    # Pour une entrée dossier/glob (path se terminant par /* ou /**), affine le routage par
+    # sous-chemin - les keywords ci-dessus restent le repli pour tout le reste du dossier :
+    # keywordOverrides:
+    #   - path: doc/model/endpoints/clients
+    #     keywords: ["clients", "endpoint clients", "API clients"]
+    #   - path: doc/model/diagrammes/admin/compte
+    #     keywords: ["compte", "diagramme compte"]
+    confluence:
+      title: Guide codoc
+      # parentPageId: "TODO"   # surcharge defaultParentPageId pour cette page uniquement
+      # titlePrefix: "[DRAFT] "
+      # titleSuffix: " (auto)"
+`;
+}
+//#endregion
+export { yamlTemplate };

package/dist/services/lock/lock-file.js

@@ -0,0 +1,61 @@
+import { fileExists, readFile, writeFile } from "../files-service.js";
+import { STATE_FILE } from "../../config/codoc-paths.js";
+import { log } from "../log/logger.js";
+//#region src/services/lock/lock-file.ts
+let cache;
+function loadPublishState() {
+	if (cache) return cache;
+	if (!fileExists(STATE_FILE)) {
+		cache = {
+			lastPublished: "",
+			pages: {}
+		};
+		return cache;
+	}
+	try {
+		const raw = readFile(STATE_FILE);
+		cache = JSON.parse(raw);
+		return cache;
+	} catch {
+		log.warning0("codoc.lock illisible - état précédent ignoré.");
+		cache = {
+			lastPublished: "",
+			pages: {}
+		};
+		return cache;
+	}
+}
+function savePublishState(state) {
+	cache = state;
+	writeFile(STATE_FILE, JSON.stringify(state, null, 2) + "\n");
+}
+function findLockedRef(lock, envKey, sourceFile) {
+	for (const p of Object.values(lock.pages)) {
+		if (p.environment !== envKey) continue;
+		if (p.sourceFile === sourceFile) return {
+			confluencePageId: p.confluencePageId,
+			confluenceUrl: p.confluenceUrl,
+			title: p.title
+		};
+		const child = p.children?.find((c) => c.sourceFile === sourceFile);
+		if (child) return {
+			confluencePageId: child.confluencePageId,
+			confluenceUrl: child.confluenceUrl,
+			title: child.title
+		};
+	}
+}
+function makePageState(p) {
+	return {
+		confluencePageId: p.pageId,
+		environment: p.environment,
+		title: p.title,
+		confluenceUrl: p.url,
+		sourceFile: p.sourceFile,
+		publishedAt: p.publishedAt,
+		maintainedIn: p.maintainedIn,
+		...p.isFolder ? { isFolder: true } : {}
+	};
+}
+//#endregion
+export { findLockedRef, loadPublishState, makePageState, savePublishState };

package/dist/services/log/init-printer.js

@@ -0,0 +1,50 @@
+import { ansi, log } from "./logger.js";
+//#region src/services/log/init-printer.ts
+function printInitSummary(created, skipped, warnings, docRelPath) {
+	log.startProcess("Initialisation de codoc");
+	if (created.length) {
+		log.info0("Fichiers générés :");
+		for (const f of created) log.success2(`[CREATED] ${f}`);
+	}
+	if (skipped.length) {
+		log.blank();
+		log.info0("Déjà présents (non modifiés) :");
+		for (const f of skipped) log.info2(`[UNCHANGED] ${f}`);
+	}
+	if (warnings.length) {
+		log.blank();
+		log.warning0("À regarder :");
+		for (const w of warnings) log.warning2(w);
+	}
+	log.blank();
+	log.info0(ansi.bold("Prochaines étapes :"));
+	log.blank();
+	log.raw(`  ${ansi.bold("1.")} Remplis ${ansi.cyan("codoc.yaml")}`);
+	log.raw("       • atlassian.environments.<key>.baseUrl + spaceKey + defaultParentPageId");
+	log.raw("       • gitlab.baseUrl / jira.serverId+server (optionnels - liens code et tickets dans les pages publiées)");
+	log.blank();
+	log.raw(`  ${ansi.bold("2.")} Renseigne tes identifiants dans ${ansi.cyan(".env-codoc")} (déjà ignoré par git si tu as un .gitignore standard)`);
+	log.raw("       • CONFLUENCE_<CLÉ>_USERNAME, CONFLUENCE_<CLÉ>_API_TOKEN (préfixées par la clé de l'env, ex. CONFLUENCE_DEFAULT_USERNAME)");
+	log.blank();
+	log.raw(`  ${ansi.bold("3.")} Publie ton premier document :`);
+	log.raw(`       ${ansi.dim("$")} codoc sync`);
+	log.raw(`       → publie ${ansi.cyan(docRelPath)} sur Confluence`);
+	log.blank();
+	log.info0(ansi.dim(`Guide complet généré dans ${docRelPath}`));
+	log.blank();
+}
+function printAgentMdSummary(result) {
+	log.startProcess("Génération de l'agent-md");
+	if (result.created.length) {
+		log.info0("Fichier généré :");
+		for (const f of result.created) log.success2(`[CREATED] ${f}`);
+	}
+	if (result.warnings.length) {
+		log.blank();
+		log.warning0("À regarder :");
+		for (const w of result.warnings) log.warning2(w);
+	}
+	log.blank();
+}
+//#endregion
+export { printAgentMdSummary, printInitSummary };