codoc-cli 0.1.2

package/dist/use-cases/pull/pull.js

@@ -0,0 +1,337 @@
+import { onlySingleEnv } from "../../config/codoc-config-atlassian.js";
+import { toPosixPath } from "../../services/files-service.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { getCodocConfig } from "../../config/codoc-config.js";
+import { generateRandomCodocId } from "../../services/codoc-id.js";
+import { askWithDefault, createRl, resolveConfirm, resolveValue } from "../../services/prompt.js";
+import { log } from "../../services/log/logger.js";
+import { loadPublishState, makePageState, savePublishState } from "../../services/lock/lock-file.js";
+import { slugify } from "../../services/slugify.js";
+import { pageUrl } from "../../clients/confluence/utils/confluence-url.js";
+import { EnvRegistry } from "../shared/confluence-client-registry.js";
+import { appendToDocsConfig, buildYamlEntry, removeDocsConfigEntries } from "../shared/codoc-yaml.js";
+import { selectEnvs } from "../shared/env-select.js";
+import { cleanDocPath } from "../sync/sync-entries.js";
+import { closeDrawioRenderer } from "../../services/conversion/confluenceToMarkdown/diagrams/drawio-to-image.js";
+import { renderRemotePageToLocal } from "../shared/render-remote-page.js";
+import { fetchFolderDescendants, pullFolderToLocal, pulledPagesToChildren } from "../shared/pull-folder.js";
+import { fetchPageOrUndefined } from "../shared/fetch-page.js";
+import { parsePageInput } from "./parse-page-input.js";
+import path from "path";
+//#region src/use-cases/pull/pull.ts
+/**
+* Cherche un import existant pour cette page : d'abord dans le lock (par ID Confluence puis par titre),
+* sinon dans le yaml (par titre) - couvre le cas d'une entrée déjà configurée mais jamais encore synchronisée.
+*/
+function findExistingImport(config, state, pageId, title) {
+	const entries = Object.entries(state.pages);
+	const byId = entries.find(([, p]) => p.confluencePageId === pageId);
+	const lockMatch = byId ?? entries.find(([, p]) => p.title === title);
+	const codocId = lockMatch?.[0] ?? config.docs.find((d) => d.confluence.title === title)?.codocId;
+	if (!codocId) return void 0;
+	const doc = config.docs.find((d) => d.codocId === codocId);
+	const lockPage = lockMatch?.[1];
+	return {
+		codocId,
+		sourceFile: doc ? cleanDocPath(doc.path) : lockPage.sourceFile,
+		title: doc?.confluence.title ?? lockPage?.title ?? title,
+		pageId: lockPage?.confluencePageId ?? pageId,
+		matchedBy: byId ? "id" : lockMatch ? "titre" : "config",
+		parentPageId: doc?.confluence.parentPageId,
+		maintainedIn: doc?.maintainedIn ?? lockPage?.maintainedIn,
+		imagesDir: doc?.imagesDir
+	};
+}
+/** Résout les informations d'import (chemin, titre, parent, maintien, images) : flag → config
+* (import existant si remplacement) → prompt. */
+async function collectImportAnswers(rl, page, confluence, existing, replaceExisting, flags) {
+	const kept = replaceExisting ? existing : void 0;
+	const localPath = await resolveValue(rl, {
+		flag: flags.localPath,
+		config: kept?.sourceFile,
+		prompt: "Chemin local du fichier .md :",
+		promptDefault: `doc/${slugify(page.title)}.md`
+	});
+	if (!localPath.endsWith(".md")) throw new Error("Le chemin doit se terminer par .md");
+	return {
+		localPath,
+		title: await resolveValue(rl, {
+			flag: flags.title,
+			config: kept?.title,
+			prompt: "Titre de la page Confluence :",
+			promptDefault: page.title
+		}),
+		parentPageId: await resolveValue(rl, {
+			flag: flags.parentPageId,
+			config: kept?.parentPageId,
+			prompt: "parentPageId Confluence :",
+			promptDefault: page.parentId ?? confluence.defaultParentPageId ?? ""
+		}),
+		maintainedIn: (await resolveValue(rl, {
+			flag: flags.maintainedIn,
+			config: kept?.maintainedIn,
+			prompt: "Maintenue côté code ou confluence ? (code/confluence) :",
+			promptDefault: "confluence"
+		})).trim().toLowerCase() === "code" ? "code" : "confluence",
+		imagesDir: (await resolveValue(rl, {
+			flag: flags.imagesDir,
+			config: kept?.imagesDir,
+			prompt: "Dossier local pour les images (vide pour ignorer) :",
+			promptDefault: "doc/img"
+		})).trim() || void 0
+	};
+}
+/** Détermine l'environnement où se trouve la page (flag → URL → env unique → sonde chaque env). */
+async function resolveEnvAndPage(rl, config, registry, domain, pageId, flagEnv) {
+	const envs = config.atlassian.environments;
+	const fromEnv = async (e) => {
+		const page = await fetchPageOrUndefined(registry.raw(e), pageId);
+		if (!page) throw new Error(`Page ${pageId} introuvable sur l'environnement "${e.key}" (${e.baseUrl}).`);
+		return {
+			env: e,
+			page
+		};
+	};
+	if (flagEnv) return fromEnv(selectEnvs(config, flagEnv)[0]);
+	if (domain) {
+		const match = envs.find((e) => {
+			try {
+				return new URL(e.baseUrl).hostname === domain;
+			} catch {
+				return false;
+			}
+		});
+		if (match) return fromEnv(match);
+		log.blank();
+		log.warning1(`Le domaine "${domain}" ne correspond à aucun environnement - détection automatique…`);
+	}
+	const onlyEnv = onlySingleEnv(envs);
+	if (onlyEnv) return fromEnv(onlyEnv);
+	log.info0(`Recherche de la page dans : ${envs.map((e) => e.key).join(", ")}…`);
+	const found = [];
+	for (const e of envs) {
+		const page = await fetchPageOrUndefined(registry.raw(e), pageId);
+		if (page) found.push({
+			env: e,
+			page
+		});
+	}
+	if (found.length === 0) throw new Error(`Page ${pageId} introuvable dans aucun environnement (${envs.map((e) => e.key).join(", ")}).`);
+	if (found.length === 1) {
+		log.success1(`Trouvée dans l'environnement "${found[0].env.key}".`);
+		return found[0];
+	}
+	log.warning1(`Page présente dans plusieurs environnements : ${found.map((f) => f.env.key).join(", ")}.`);
+	const key = await askWithDefault(rl, "Lequel ?", found[0].env.key);
+	return found.find((f) => f.env.key === key) ?? found[0];
+}
+/** Import d'un dossier Confluence complet : chaque descendant en .md local, une seule entrée `path: folder/*` en yaml. */
+async function pullFolder(rl, client, rootPage, rootType, flags) {
+	const rawFolder = await resolveValue(rl, {
+		flag: flags.localPath,
+		prompt: "Dossier local de destination :",
+		promptDefault: `doc/${slugify(rootPage.title)}/`
+	});
+	const localFolder = toPosixPath(rawFolder).replace(/\/?$/, "/");
+	const parentPageId = await resolveValue(rl, {
+		flag: flags.parentPageId,
+		prompt: "parentPageId Confluence (page parente du dossier) :",
+		promptDefault: rootPage.parentId ?? client.configuration.defaultParentPageId ?? ""
+	});
+	const maintainedIn = (await resolveValue(rl, {
+		flag: flags.maintainedIn,
+		prompt: "Maintenue côté code ou confluence ? (code/confluence) :",
+		promptDefault: "confluence"
+	})).trim().toLowerCase() === "code" ? "code" : "confluence";
+	const imagesDir = (await resolveValue(rl, {
+		flag: flags.imagesDir,
+		prompt: "Dossier local pour les images (vide pour ignorer) :",
+		promptDefault: "doc/img"
+	})).trim() || void 0;
+	log.blank();
+	log.step1("Récupération des sous-pages");
+	const descendants = await fetchFolderDescendants(client, rootPage.id, rootType);
+	const pages = descendants.filter((d) => d.type !== "folder");
+	log.info1(`${pages.length} page(s) trouvée(s) sous "${rootPage.title}"`);
+	if (!pages.length) {
+		log.warning1("Aucune sous-page - utilise l'import simple à la place.");
+		return;
+	}
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const written = await pullFolderToLocal({
+		confluenceClient: client,
+		rootId: rootPage.id,
+		rootType,
+		localDir: localFolder,
+		imagesDir,
+		onPage: (page, index, total) => {
+			log.blank();
+			log.progress(index, total, page.title);
+			log.success3(`[PULL] → ${page.localPath}`);
+		},
+		onPageError: ({ title }, err, index, total) => {
+			log.blank();
+			log.progress(index, total, title);
+			log.error3(`Échec "${title}" : ${err?.message ?? err}`);
+		}
+	});
+	const codocId = generateRandomCodocId();
+	const folderDir = localFolder.replace(/\/$/, "");
+	const state = loadPublishState();
+	const addToConfig = await resolveConfirm(rl, {
+		flag: flags.inConfig,
+		question: "Ajouter ce dossier à codoc.yaml (pour qu'il soit synchronisé par `codoc sync`) ?",
+		default: true
+	});
+	if (addToConfig) {
+		state.pages[codocId] = {
+			...makePageState({
+				pageId: rootPage.id,
+				environment: client.configuration.key,
+				title: rootPage.title,
+				url: pageUrl(client.configuration.baseUrl, client.configuration.spaceKey, rootPage.id),
+				sourceFile: folderDir,
+				maintainedIn,
+				publishedAt: now,
+				isFolder: true
+			}),
+			children: pulledPagesToChildren(written, client.configuration.baseUrl, client.configuration.spaceKey)
+		};
+		state.lastPublished = state.lastPublished || now;
+		savePublishState(state);
+		const yamlEntry = buildYamlEntry({
+			localPath: `${localFolder}**`,
+			title: rootPage.title,
+			parentPageId,
+			imagesDir,
+			maintainedIn,
+			env: client.configuration.key,
+			codocId
+		});
+		await appendToDocsConfig(yamlEntry);
+	} else log.warning1("[SKIPPED] codoc.yaml et codoc.lock non modifiés - import ponctuel, hors suivi (pas de comparaison future par ID).");
+	log.finalBanner("Import dossier terminé", {
+		"Dossier local": localFolder,
+		"Pages importées": `${written.length} / ${descendants.length}`,
+		"Page racine": `${rootPage.id} - "${rootPage.title}"`,
+		"Prochaine étape": addToConfig ? "codoc sync" : "(hors suivi - codoc.yaml et codoc.lock non modifiés)"
+	});
+}
+async function pull(flags = {}) {
+	const config = getCodocConfig();
+	const state = loadPublishState();
+	const registry = new EnvRegistry();
+	const rl = createRl();
+	try {
+		log.startProcess("Import Confluence → local");
+		const rawInput = await resolveValue(rl, {
+			flag: flags.page,
+			prompt: "URL ou ID de la page Confluence :"
+		});
+		if (!rawInput) throw new Error("URL ou ID requis.");
+		const parsed = parsePageInput(rawInput);
+		const pageId = parsed.pageId;
+		log.blank();
+		log.step1("Récupération de la page");
+		const { env, page } = await resolveEnvAndPage(rl, config, registry, parsed.domain, pageId, flags.env);
+		const client = await registry.connect(env);
+		log.field("Environnement", `${env.key} (${env.baseUrl})`);
+		log.blank();
+		log.field("Titre    ", page.title);
+		log.field("Parent ID", page.parentId ?? "(racine)");
+		if (page.hasImages) log.field("Images   ", "oui");
+		if (parsed.isFolder) {
+			await pullFolder(rl, client, page, "folder", flags);
+			return;
+		}
+		const [subPages, subFolders] = await Promise.all([client.pages.fetchChildren(pageId), client.folders.childrenFolders(pageId)]);
+		const childCount = subPages.length + subFolders.length;
+		if (childCount > 0) {
+			log.blank();
+			log.info1(`Cette page contient ${childCount} sous-élément(s) (${subPages.length} page(s), ${subFolders.length} dossier(s)).`);
+			if (await resolveConfirm(rl, {
+				flag: flags.asFolder,
+				question: "Importer tout le dossier (toutes les sous-pages/sous-dossiers) ?",
+				default: true
+			})) {
+				await pullFolder(rl, client, page, "page", flags);
+				return;
+			}
+		}
+		const existing = findExistingImport(config, state, pageId, page.title);
+		let replaceExisting = false;
+		if (existing) {
+			const matchLabel = existing.matchedBy === "id" ? "même ID Confluence" : existing.matchedBy === "titre" ? "même titre" : "déjà dans codoc.yaml";
+			log.blank();
+			log.warning1(`Cette page semble déjà importée (${matchLabel}) :`);
+			log.info4(`Fichier : ${existing.sourceFile}`);
+			log.info4(`Titre   : ${existing.title}`);
+			log.info4(`Page ID : ${existing.pageId}`);
+			replaceExisting = await resolveConfirm(rl, {
+				flag: flags.keepExisting,
+				question: "Garder la config existante (les valeurs ci-dessous serviront de défaut) ?",
+				default: true
+			});
+			if (!replaceExisting) log.warning1("L'existant est conservé ; un nouvel import séparé est créé.");
+		}
+		const { localPath, title, parentPageId, maintainedIn, imagesDir } = await collectImportAnswers(rl, page, env, existing, replaceExisting, flags);
+		log.blank();
+		log.step1("Conversion en Markdown");
+		await renderRemotePageToLocal(client, page, localPath, imagesDir);
+		log.success1(`[PULL] Fichier sauvegardé : ${path.resolve(PROJECT_ROOT, localPath)}`);
+		const codocId = replaceExisting && existing?.codocId || generateRandomCodocId();
+		const isReplacement = replaceExisting && Boolean(existing);
+		const question = isReplacement ? "Mettre à jour la config codoc.yaml existante pour cette doc ?" : "Ajouter cette doc à codoc.yaml (pour qu'elle soit synchronisée par `codoc sync`) ?";
+		const addToConfig = await resolveConfirm(rl, {
+			flag: flags.inConfig,
+			question,
+			default: true
+		});
+		if (addToConfig) {
+			const entry = buildYamlEntry({
+				localPath,
+				title,
+				parentPageId,
+				imagesDir,
+				maintainedIn,
+				env: env.key,
+				codocId
+			});
+			if (isReplacement && existing) {
+				await removeDocsConfigEntries([existing.sourceFile, localPath]);
+				await appendToDocsConfig(entry);
+				log.success1("[UPDATED] codoc.yaml : entrée remplacée");
+			} else {
+				await appendToDocsConfig(entry);
+				log.success1("[UPDATED] codoc.yaml mis à jour");
+			}
+			if (isReplacement && existing && existing.codocId !== codocId) delete state.pages[existing.codocId];
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			state.pages[codocId] = makePageState({
+				pageId,
+				environment: env.key,
+				title,
+				url: pageUrl(env.baseUrl, env.spaceKey, pageId),
+				sourceFile: localPath,
+				maintainedIn,
+				publishedAt: now
+			});
+			state.lastPublished = state.lastPublished || now;
+			savePublishState(state);
+			log.success1("[UPDATED] codoc.lock mis à jour");
+		} else log.warning1("[SKIPPED] codoc.yaml et codoc.lock non modifiés - import ponctuel, hors suivi (pas de comparaison future par ID).");
+		const maintainedHint = maintainedIn === "confluence" ? `${maintainedIn} (Confluence fait foi → sync régénère le .md local)` : `${maintainedIn} (le code fait foi → sync régénère la page Confluence)`;
+		const nextSteps = addToConfig ? `1. Révise le Markdown généré dans ${localPath}\n2. Lance codoc sync pour re-synchroniser` : `1. Révise le Markdown généré dans ${localPath}\n2. Import hors suivi - codoc.yaml et codoc.lock non modifiés`;
+		log.finalBanner("Import terminé", {
+			"Fichier local": localPath,
+			"Page Confluence": `${pageId} - "${title}"`,
+			Maintien: maintainedHint,
+			"Prochaines étapes": nextSteps
+		});
+	} finally {
+		rl.close();
+		await closeDrawioRenderer();
+	}
+}
+//#endregion
+export { pull };

package/dist/use-cases/shared/codoc-yaml.js

@@ -0,0 +1,45 @@
+import { readFile, writeFile } from "../../services/files-service.js";
+import { CONFIG_PATH } from "../../config/codoc-paths.js";
+//#region src/use-cases/shared/codoc-yaml.ts
+function buildYamlEntry(params) {
+	const lines = [];
+	if (params.codocId) {
+		lines.push(`\n  - codocId: ${params.codocId}`);
+		lines.push(`    path: ${params.localPath}`);
+	} else lines.push(`\n  - path: ${params.localPath}`);
+	lines.push(`    maintainedIn: ${params.maintainedIn}`);
+	if (params.env) lines.push(`    env: ${params.env}`);
+	if (params.imagesDir) lines.push(`    imagesDir: ${params.imagesDir}`);
+	if (params.title || params.parentPageId) {
+		lines.push(`    confluence:`);
+		if (params.title) lines.push(`      title: "${params.title.replace(/"/g, "\\\"")}"`);
+		if (params.parentPageId) lines.push(`      parentPageId: "${params.parentPageId}"`);
+	}
+	return lines.join("\n");
+}
+function removeEntriesFromYaml(content, paths) {
+	const targets = new Set(paths);
+	const lines = content.split("\n");
+	const result = [];
+	let i = 0;
+	while (i < lines.length) {
+		const pathValue = lines[i].match(/^\s*-\s+path:\s*(.+?)\s*$/)?.[1]?.replace(/^["']|["']$/g, "");
+		if (pathValue && targets.has(pathValue)) {
+			i++;
+			while (i < lines.length && lines[i].trim() !== "" && !/^\s*-\s+path:/.test(lines[i]) && !/^\S/.test(lines[i])) i++;
+			continue;
+		}
+		result.push(lines[i]);
+		i++;
+	}
+	return result.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+async function appendToDocsConfig(entry) {
+	const existing = readFile(CONFIG_PATH);
+	writeFile(CONFIG_PATH, existing.trimEnd() + entry + "\n");
+}
+async function removeDocsConfigEntries(paths) {
+	writeFile(CONFIG_PATH, removeEntriesFromYaml(readFile(CONFIG_PATH), paths));
+}
+//#endregion
+export { appendToDocsConfig, buildYamlEntry, removeDocsConfigEntries, removeEntriesFromYaml };

package/dist/use-cases/shared/confluence-client-registry.js

@@ -0,0 +1,27 @@
+import { log } from "../../services/log/logger.js";
+import { createConfluenceClient } from "../../clients/confluence/confluence-client.js";
+//#region src/use-cases/shared/confluence-client-registry.ts
+/** Cache des clients Confluence par environnement. */
+var EnvRegistry = class {
+	clients = /* @__PURE__ */ new Map();
+	connected = /* @__PURE__ */ new Set();
+	raw(env) {
+		let c = this.clients.get(env.key);
+		if (!c) {
+			c = createConfluenceClient(env);
+			this.clients.set(env.key, c);
+		}
+		return c;
+	}
+	async connect(env) {
+		const c = this.raw(env);
+		if (!this.connected.has(env.key)) {
+			if (!await c.pages.testConnection()) throw new Error(`Connexion impossible à l'environnement "${env.key}" (${env.baseUrl}).`);
+			log.success0(`Connecté à Confluence [${env.key}] - ${env.baseUrl}`);
+			this.connected.add(env.key);
+		}
+		return c;
+	}
+};
+//#endregion
+export { EnvRegistry };

package/dist/use-cases/shared/env-select.js

@@ -0,0 +1,23 @@
+import { onlySingleEnv } from "../../config/codoc-config-atlassian.js";
+import "../../config/codoc-config.js";
+import { askWithDefault } from "../../services/prompt.js";
+//#region src/use-cases/shared/env-select.ts
+/** Filtre `config.atlassian.environments` par clé ; lève si la clé est fournie mais inconnue. */
+function selectEnvs(config, envKey) {
+	const envs = config.atlassian.environments;
+	if (!envKey) return envs;
+	const matched = envs.filter((e) => e.key === envKey);
+	if (!matched.length) throw new Error(`Environnement Confluence "${envKey}" inconnu. Définis : ${envs.map((e) => e.key).join(", ")}.`);
+	return matched;
+}
+/** Choisit l'environnement Confluence cible (l'unique, sinon demande). */
+async function pickEnvInteractive(rl, config) {
+	const envs = config.atlassian.environments;
+	const onlyEnv = onlySingleEnv(envs);
+	if (onlyEnv) return onlyEnv;
+	const keys = envs.map((e) => e.key);
+	const answer = await askWithDefault(rl, `Environnement Confluence cible (${keys.join(", ")}) :`, keys[0]);
+	return envs.find((e) => e.key === answer.trim()) ?? envs[0];
+}
+//#endregion
+export { pickEnvInteractive, selectEnvs };

package/dist/use-cases/shared/fetch-page.js

@@ -0,0 +1,11 @@
+//#region src/use-cases/shared/fetch-page.ts
+/** Récupère une page sur un environnement, ou undefined si absente/inaccessible. */
+async function fetchPageOrUndefined(client, pageId) {
+	try {
+		return await client.pages.fetchPage(pageId);
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { fetchPageOrUndefined };

package/dist/use-cases/shared/list-documents.js

@@ -0,0 +1,172 @@
+import { resolveDocEnvironmentByKey } from "../../config/codoc-config-atlassian.js";
+import { collectFiles, readFile, toPosixPath } from "../../services/files-service.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { getCodocConfig } from "../../config/codoc-config.js";
+import { log } from "../../services/log/logger.js";
+import { findLockedRef, loadPublishState } from "../../services/lock/lock-file.js";
+import { slugify } from "../../services/slugify.js";
+import path from "path";
+import fs from "fs/promises";
+//#region src/use-cases/shared/list-documents.ts
+function extractH1(markdown) {
+	return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim();
+}
+function capitalizeFirst(name) {
+	return name.charAt(0).toUpperCase() + name.slice(1);
+}
+/** Vrai si le chemin yaml désigne un dossier/glob (`/**`, `/*` ou `/` final). */
+function isFolderPath(docPath) {
+	return /\/\*\*?$/.test(docPath) || docPath.endsWith("/");
+}
+function normalizeDocPath(docPath) {
+	return {
+		cleanPath: docPath.replace(/\/\*\*?$/, "").replace(/\/$/, ""),
+		isFolder: isFolderPath(docPath)
+	};
+}
+async function collectMarkdownFiles(docPath) {
+	const { cleanPath, isFolder } = normalizeDocPath(docPath);
+	const absPath = path.resolve(PROJECT_ROOT, cleanPath);
+	let stat;
+	try {
+		stat = await fs.stat(absPath);
+	} catch {
+		log.warning0(`Chemin introuvable : ${absPath}`);
+		return [];
+	}
+	return isFolder || stat.isDirectory() ? collectFiles(absPath, [".md"]) : [absPath];
+}
+function matchesOverridePath(sourceFile, overridePath) {
+	const file = sourceFile.replace(/\.md$/, "");
+	const override = overridePath.replace(/^\.\//, "").replace(/\.md$/, "").replace(/\/$/, "");
+	return file === override || file.startsWith(`${override}/`);
+}
+function resolveKeywords(doc, sourceFile) {
+	const matches = (doc.keywordOverrides ?? []).filter((o) => matchesOverridePath(sourceFile, o.path));
+	if (!matches.length) return doc.keywords;
+	return matches.reduce((best, cur) => cur.path.length > best.path.length ? cur : best).keywords;
+}
+/** Dérive les métadonnées (titre, id) d'une page à partir d'un fichier + son entrée de config. */
+function deriveTarget(filePath, markdown, doc, isSingleFile, env, lock) {
+	const filenameWithoutExt = path.basename(filePath, ".md");
+	const conf = doc.confluence;
+	const sourceFile = toPosixPath(path.relative(PROJECT_ROOT, filePath));
+	const lockedTitle = doc.maintainedIn === "confluence" ? findLockedRef(lock, env.key, sourceFile)?.title : void 0;
+	const baseTitle = (isSingleFile ? conf.title : void 0) ?? lockedTitle ?? extractH1(markdown) ?? capitalizeFirst(filenameWithoutExt);
+	const title = `${conf.titlePrefix ?? ""}${baseTitle}${conf.titleSuffix ?? ""}`;
+	const id = slugify(filenameWithoutExt);
+	return {
+		codocId: doc.codocId,
+		sourceFile,
+		markdown,
+		id,
+		title,
+		parentPageId: conf.parentPageId ?? env.defaultParentPageId,
+		imagesDir: doc.imagesDir,
+		maintainedIn: doc.maintainedIn,
+		env,
+		keywords: resolveKeywords(doc, sourceFile),
+		generateSummary: doc.generateSummary
+	};
+}
+/** Génère les DocTarget "dossier" pour chaque sous-dossier intermédiaire (parents avant enfants) et mappe filePath → lockKey du parent. */
+function buildFolderHierarchy(baseDirAbs, baseDirRel, files, doc, env) {
+	const subdirs = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		const rel = toPosixPath(path.relative(baseDirAbs, path.dirname(file)));
+		if (!rel || rel === ".") continue;
+		const parts = rel.split("/");
+		for (let i = 1; i <= parts.length; i++) subdirs.add(parts.slice(0, i).join("/"));
+	}
+	const sorted = [...subdirs].sort((a, b) => {
+		const d = a.split("/").length - b.split("/").length;
+		return d !== 0 ? d : a.localeCompare(b);
+	});
+	const folderTargets = [];
+	const relDirToKey = /* @__PURE__ */ new Map();
+	for (const relDir of sorted) {
+		const dirRelFromProject = path.posix.join(baseDirRel, relDir);
+		const folderName = relDir.split("/").pop();
+		const id = `folder:${slugify(dirRelFromProject)}`;
+		const fKey = `${env.key}:${id}`;
+		relDirToKey.set(relDir, fKey);
+		const parentRelDir = relDir.includes("/") ? relDir.slice(0, relDir.lastIndexOf("/")) : void 0;
+		const parentFolderKey = parentRelDir ? relDirToKey.get(parentRelDir) : void 0;
+		const baseFolderTitle = capitalizeFirst(folderName);
+		const folderTitle = `${doc.confluence.titlePrefix ?? ""}${baseFolderTitle}${doc.confluence.titleSuffix ?? ""}`;
+		folderTargets.push({
+			codocId: doc.codocId,
+			sourceFile: dirRelFromProject,
+			markdown: "",
+			id,
+			title: folderTitle,
+			parentPageId: doc.confluence.parentPageId ?? env.defaultParentPageId,
+			imagesDir: void 0,
+			maintainedIn: doc.maintainedIn,
+			env,
+			isFolder: true,
+			parentFolderKey,
+			keywords: resolveKeywords(doc, dirRelFromProject),
+			generateSummary: doc.generateSummary
+		});
+	}
+	const fileParentKey = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const relToBase = toPosixPath(path.relative(baseDirAbs, file));
+		const relDir = relToBase.includes("/") ? relToBase.slice(0, relToBase.lastIndexOf("/")) : ".";
+		fileParentKey.set(file, relDir === "." ? void 0 : relDirToKey.get(relDir));
+	}
+	return {
+		folderTargets,
+		fileParentKey
+	};
+}
+/** Énumère toutes les pages de codoc.yaml avec leurs métadonnées dérivées (sert au sync et à docsTree). */
+async function listDocumentTargets() {
+	const config = getCodocConfig();
+	const lock = loadPublishState();
+	const targets = [];
+	for (const doc of config.docs) targets.push(...await expandDocEntry(doc, resolveDocEnvironmentByKey(config, doc), lock));
+	return targets;
+}
+/** Étend UNE entrée `docs:` en ses cibles Confluence (1 pour un fichier ; dossiers + fichiers pour un glob). */
+async function expandDocEntry(doc, env, lock = loadPublishState()) {
+	const targets = [];
+	if (doc.maintainedIn === "confluence") {
+		if (isFolderPath(doc.path)) {
+			const files = await collectMarkdownFiles(doc.path);
+			targets.push(...await expandFolderGlobTargets(doc, env, files, lock));
+		} else {
+			const filePath = path.resolve(PROJECT_ROOT, normalizeDocPath(doc.path).cleanPath);
+			let markdown = "";
+			try {
+				markdown = readFile(filePath);
+			} catch {}
+			targets.push(deriveTarget(filePath, markdown, doc, true, env, lock));
+		}
+		return targets;
+	}
+	const files = await collectMarkdownFiles(doc.path);
+	if (!files.length) return targets;
+	const isFolderGlob = isFolderPath(doc.path);
+	const isSingleFile = !isFolderGlob && files.length === 1;
+	if (isFolderGlob) targets.push(...await expandFolderGlobTargets(doc, env, files, lock));
+	else for (const filePath of files) targets.push(deriveTarget(filePath, readFile(filePath), doc, isSingleFile, env, lock));
+	return targets;
+}
+/** Étend un dossier (glob) en DocTarget "dossier" puis "fichier", chacun rattaché à son dossier local via `parentFolderKey`. */
+async function expandFolderGlobTargets(doc, env, files, lock) {
+	const { cleanPath: baseDirRel } = normalizeDocPath(doc.path);
+	const { folderTargets, fileParentKey } = buildFolderHierarchy(path.resolve(PROJECT_ROOT, baseDirRel), baseDirRel, files, doc, env);
+	const targets = [...folderTargets];
+	for (const filePath of files) {
+		const t = deriveTarget(filePath, readFile(filePath), doc, false, env, lock);
+		targets.push({
+			...t,
+			parentFolderKey: fileParentKey.get(filePath)
+		});
+	}
+	return targets;
+}
+//#endregion
+export { expandDocEntry, extractH1, listDocumentTargets };