codoc-cli 0.1.2

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

@@ -0,0 +1,90 @@
+import { toPosixPath } from "../../services/files-service.js";
+import { slugify } from "../../services/slugify.js";
+import { pageUrl } from "../../clients/confluence/utils/confluence-url.js";
+import { renderRemotePageToLocal } from "./render-remote-page.js";
+import path from "path";
+//#region src/use-cases/shared/pull-folder.ts
+async function fetchFolderDescendants(ConfluenceClient, parentId, parentType) {
+	const children = parentType === "folder" ? await ConfluenceClient.folders.children(parentId) : [...(await ConfluenceClient.pages.fetchChildren(parentId)).map((c) => ({
+		...c,
+		type: "page"
+	})), ...(await ConfluenceClient.folders.childrenFolders(parentId)).map((c) => ({
+		...c,
+		type: "folder"
+	}))];
+	const nested = await Promise.all(children.map((child) => fetchFolderDescendants(ConfluenceClient, child.id, child.type === "folder" ? "folder" : "page")));
+	return [...children.map((child) => ({
+		...child,
+		parentId
+	})), ...nested.flat()];
+}
+function folderLocalPaths(descendants, rootId, localFolder) {
+	const slugById = new Map(descendants.map((d) => [d.id, slugify(d.title)]));
+	const parentById = new Map(descendants.map((d) => [d.id, d.parentId]));
+	const hasChildren = new Set(descendants.map((d) => d.parentId).filter((id) => id !== rootId));
+	const folderIds = new Set(descendants.filter((d) => d.type === "folder").map((d) => d.id));
+	const result = /* @__PURE__ */ new Map();
+	for (const d of descendants) {
+		const parts = [];
+		let cur = d.id;
+		while (cur !== rootId) {
+			const slug = slugById.get(cur);
+			if (cur === d.id) {
+				const isDir = hasChildren.has(cur) || folderIds.has(cur);
+				parts.unshift(isDir ? `${slug}/index.md` : `${slug}.md`);
+			} else parts.unshift(slug);
+			cur = parentById.get(cur);
+		}
+		result.set(d.id, `${localFolder}${parts.join("/")}`);
+	}
+	return result;
+}
+function pulledPagesToChildren(pages, baseUrl, spaceKey) {
+	return pages.map((p) => ({
+		title: p.title,
+		confluencePageId: p.id,
+		sourceFile: p.localPath,
+		confluenceUrl: pageUrl(baseUrl, spaceKey, p.id)
+	}));
+}
+async function pullFolderToLocal(params) {
+	const { confluenceClient, rootId, imagesDir, onPage, onPageError } = params;
+	const localFolder = toPosixPath(params.localDir).replace(/\/?$/, "/");
+	const descendants = await fetchFolderDescendants(confluenceClient, rootId, params.rootType ?? "folder");
+	const pages = descendants.filter((d) => d.type !== "folder");
+	const localPaths = folderLocalPaths(descendants, rootId, localFolder);
+	const prevPathById = new Map((params.prevChildren ?? []).map((c) => [c.confluencePageId, c.sourceFile]));
+	const folderBase = localFolder.replace(/\/$/, "");
+	const written = [];
+	for (let i = 0; i < pages.length; i++) {
+		const { id, title } = pages[i];
+		const localPath = prevPathById.get(id) ?? localPaths.get(id);
+		try {
+			const page = await confluenceClient.pages.fetchPage(id);
+			const pageImagesDir = imagesDir ? imagesDirForPage(imagesDir, folderBase, localPath) : void 0;
+			await renderRemotePageToLocal(confluenceClient, page, localPath, pageImagesDir);
+			const pulled = {
+				id,
+				title,
+				localPath
+			};
+			written.push(pulled);
+			onPage?.(pulled, i + 1, pages.length);
+		} catch (err) {
+			if (!onPageError) throw err;
+			onPageError({
+				id,
+				title
+			}, err, i + 1, pages.length);
+		}
+	}
+	return written;
+}
+function imagesDirForPage(imagesDir, folderBase, localPath) {
+	const pageDir = path.posix.dirname(toPosixPath(localPath));
+	const base = toPosixPath(folderBase);
+	const sub = path.posix.relative(base, pageDir);
+	return sub && sub !== "." ? `${imagesDir.replace(/\/$/, "")}/${sub}` : imagesDir;
+}
+//#endregion
+export { fetchFolderDescendants, folderLocalPaths, pullFolderToLocal, pulledPagesToChildren };

package/dist/use-cases/shared/render-remote-page.js

@@ -0,0 +1,71 @@
+import { fileExists, toPosixPath, writeBinaryFile, writeFile } from "../../services/files-service.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { log } from "../../services/log/logger.js";
+import { isAttachmentDownload } from "../../clients/confluence/utils/confluence-util.js";
+import { fetchAttachmentBinary, fetchAttachmentText } from "../../services/confluence/attachments.js";
+import { embeddedAttachmentFilenames, sanitizeAttachmentFilename } from "../../services/conversion/shared/image-attachments.js";
+import { renderMarkdown } from "../../services/conversion/confluenceToMarkdown/index.js";
+import path from "path";
+//#region src/use-cases/shared/render-remote-page.ts
+function imgRelPathFor(localPath, imagesDir) {
+	return imagesDir ? path.posix.relative(path.posix.dirname(toPosixPath(localPath)), toPosixPath(imagesDir)) : void 0;
+}
+/** Format lisible d'une taille en octets (KiB / MiB). */
+function humanBytes(n) {
+	if (n < 1024) return `${n} o`;
+	if (n < 1048576) return `${(n / 1024).toFixed(1)} Kio`;
+	return `${(n / 1048576).toFixed(1)} Mio`;
+}
+async function downloadPageImages(client, page, absImagesDir) {
+	const files = embeddedAttachmentFilenames(page.storageXml);
+	if (!files.length) return {
+		ok: 0,
+		failed: 0
+	};
+	log.info4(`${files.length} pièce(s) jointe(s) à télécharger vers ${absImagesDir}`);
+	let ok = 0;
+	let skipped = 0;
+	let failed = 0;
+	for (const filename of files) {
+		const localFilename = sanitizeAttachmentFilename(filename);
+		const absPath = path.resolve(absImagesDir, localFilename);
+		if (fileExists(absPath)) {
+			log.info4(`${localFilename}  (déjà présente)`);
+			skipped++;
+			continue;
+		}
+		const result = await fetchAttachmentBinary(client.attachments, page.id, filename);
+		if (isAttachmentDownload(result)) {
+			writeBinaryFile(absPath, result.data);
+			log.success4(`[PULL] ${localFilename}  (${humanBytes(result.bytes)} via ${result.via})`);
+			ok++;
+		} else if (result.notFound) {
+			log.warning4(`${localFilename}  → pièce jointe introuvable sur la page`);
+			failed++;
+		} else {
+			log.error4(`${localFilename}  → v1: ${result.v1Error ?? "-"}  |  v2: ${result.v2Error ?? "-"}`);
+			failed++;
+		}
+	}
+	const parts = [`${ok} téléchargée(s)`];
+	if (skipped) parts.push(`${skipped} déjà présente(s)`);
+	if (failed) parts.push(`${failed} échec(s)`);
+	log.info4(`Total : ${parts.join(", ")}`);
+	return {
+		ok,
+		failed
+	};
+}
+async function renderRemotePageToLocal(client, page, localPath, imagesDir) {
+	const absImagesDir = imagesDir ? path.resolve(PROJECT_ROOT, imagesDir) : void 0;
+	const markdown = await renderMarkdown(page.storageXml, {
+		fetchAttachment: (filename) => fetchAttachmentText(client.attachments, page.id, filename),
+		imagesDir: absImagesDir,
+		imgRelPath: imgRelPathFor(localPath, imagesDir),
+		baseUrl: client.configuration.baseUrl
+	});
+	writeFile(path.resolve(PROJECT_ROOT, localPath), markdown);
+	if (absImagesDir) await downloadPageImages(client, page, absImagesDir);
+}
+//#endregion
+export { renderRemotePageToLocal };

package/dist/use-cases/sync/attachment-upload.js

@@ -0,0 +1,31 @@
+import { fileExists } from "../../services/files-service.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { log } from "../../services/log/logger.js";
+import { uploadAttachmentFile } from "../../services/confluence/attachments.js";
+import path from "node:path";
+//#region src/use-cases/sync/attachment-upload.ts
+/** Filenames `<ri:filename="…"/>` référencés dans un XML Confluence Storage Format. */
+function extractAttachmentFilenames(xml) {
+	return [...new Set([...xml.matchAll(/ri:filename="([^"]+)"/g)].map((m) => m[1]))];
+}
+/** Upload chaque image référencée dans `xml` depuis `<imagesDir>/` ; warn si le fichier local est absent. */
+async function uploadImagesFromXml(client, pageId, xml, imagesDir) {
+	const absDir = path.resolve(PROJECT_ROOT, imagesDir);
+	for (const filename of extractAttachmentFilenames(xml)) {
+		const filePath = path.join(absDir, filename);
+		if (fileExists(filePath)) {
+			await uploadAttachmentFile(client.attachments, pageId, filePath);
+			log.success4(`[CREATED] Pièce jointe : ${filename}`);
+		} else log.warning4(`Image introuvable : ${filePath}`);
+	}
+}
+/** Téléverse en une passe les images du XML (si imagesDir) et les diagrammes en mémoire (attachments). */
+async function uploadPageAttachments(client, pageId, xml, imagesDir, attachments) {
+	if (imagesDir) await uploadImagesFromXml(client, pageId, xml, imagesDir);
+	for (const { filename, content } of attachments) {
+		await client.attachments.upload(pageId, filename, new Blob([content]));
+		log.success4(`[CREATED] Pièce jointe : ${filename}`);
+	}
+}
+//#endregion
+export { uploadPageAttachments };

package/dist/use-cases/sync/sync-actions.js

@@ -0,0 +1,170 @@
+import { log } from "../../services/log/logger.js";
+import { makePageState } from "../../services/lock/lock-file.js";
+import { pageUrl } from "../../clients/confluence/utils/confluence-url.js";
+import { createOrUpdatePage } from "../../services/confluence/pages.js";
+import { createOrEnsureFolder } from "../../services/confluence/folders.js";
+import { renderRemotePageToLocal } from "../shared/render-remote-page.js";
+import { renderConfluencePage } from "../../services/conversion/markdownToConfluence/index.js";
+import { fetchPageOrUndefined } from "../shared/fetch-page.js";
+import { uploadPageAttachments } from "./attachment-upload.js";
+import { parentNum, urlOf } from "./sync-helpers.js";
+import { pushKeywordLabels } from "../../services/confluence/labels.js";
+import path from "path";
+//#region src/use-cases/sync/sync-actions.ts
+async function pageMeta(client, pageId) {
+	const p = await fetchPageOrUndefined(client, pageId);
+	return p ? {
+		title: p.title,
+		parentId: p.parentId
+	} : void 0;
+}
+function renderTarget(ctx, t) {
+	const { jira, drawio } = t.env;
+	return renderConfluencePage(t.markdown, {
+		diagramBaseName: path.basename(t.sourceFile, ".md"),
+		drawio,
+		sourceFile: t.sourceFile,
+		jira: jira.serverId || jira.server ? jira : void 0,
+		gitlab: {
+			baseUrl: ctx.config.gitlab.baseUrl,
+			branch: ctx.defaultBranch
+		},
+		generatedAt: ctx.generatedAt,
+		generateSummary: t.generateSummary
+	});
+}
+async function publishPage(confirm, client, t, xml, attachments, parentId, existingId) {
+	const onTitleConflict = (_existingPageId, existingUrl) => confirm(`⚠️  Une page "${t.title}" existe déjà (hors de l'arborescence suivie dans codoc.lock) : ${existingUrl}\n   L'adopter et écraser son contenu par celui généré localement ?`);
+	const published = await createOrUpdatePage(client, t.title, xml, parentId, existingId, onTitleConflict);
+	await uploadPageAttachments(client, published.id, xml, t.imagesDir, attachments);
+	await pushKeywordLabels(client, published.id, t.keywords);
+	return published;
+}
+async function assertParentExists(client, entry) {
+	const pid = entry.parentPageId;
+	if (!pid) return;
+	if (await pageMeta(client, pid) != void 0) return;
+	if (await client.folders.exists(pid)) return;
+	throw new Error(`"${entry.path}" : parentPageId ${pid} introuvable sur l'environnement "${entry.env.key}". Revois la config.`);
+}
+function confluenceState(entry, env, pageId, title, now) {
+	return makePageState({
+		pageId,
+		environment: env.key,
+		title,
+		url: pageUrl(env.baseUrl, env.spaceKey, pageId),
+		sourceFile: entry.relPath,
+		maintainedIn: "confluence",
+		publishedAt: now
+	});
+}
+async function deleteConfluenceItem(client, id, isFolder) {
+	try {
+		if (isFolder) await client.folders.delete(id);
+		else await client.pages.delete(id);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function deleteRemote(client, lock) {
+	for (const c of lock.children ?? []) await deleteConfluenceItem(client, c.confluencePageId, c.isFolder);
+	if (lock.confluencePageId) await deleteConfluenceItem(client, lock.confluencePageId, lock.isFolder);
+}
+async function publishMulti(ctx, env, entry, targets, prevChildren) {
+	const client = await ctx.registry.connect(env);
+	const prevBySource = new Map((prevChildren ?? []).map((c) => [c.sourceFile, c]));
+	const resolvedFolderIds = /* @__PURE__ */ new Map();
+	const children = [];
+	for (const folder of targets.filter((t) => t.isFolder)) {
+		const parentId = folder.parentFolderKey ? Number(resolvedFolderIds.get(folder.parentFolderKey) ?? folder.parentPageId) : parentNum(folder.parentPageId);
+		const existingId = prevBySource.get(folder.sourceFile)?.confluencePageId;
+		log.itemFolder({
+			env: env.key,
+			title: folder.title
+		});
+		const { id } = await createOrEnsureFolder(client, folder.title, parentId, existingId);
+		resolvedFolderIds.set(`${env.key}:${folder.id}`, id);
+		children.push({
+			title: folder.title,
+			confluencePageId: id,
+			sourceFile: folder.sourceFile,
+			isFolder: true,
+			confluenceUrl: pageUrl(env.baseUrl, env.spaceKey, id)
+		});
+	}
+	for (const file of targets.filter((t) => !t.isFolder)) {
+		const parentId = file.parentFolderKey ? Number(resolvedFolderIds.get(file.parentFolderKey) ?? file.parentPageId) : parentNum(file.parentPageId);
+		const { xml, attachments } = renderTarget(ctx, file);
+		const existingId = prevBySource.get(file.sourceFile)?.confluencePageId;
+		log.itemPublished({
+			env: env.key,
+			isUpdate: Boolean(existingId),
+			title: file.title
+		});
+		const published = await publishPage(ctx.confirm, client, file, xml, attachments, parentId, existingId);
+		children.push({
+			title: file.title,
+			confluencePageId: published.id,
+			sourceFile: file.sourceFile,
+			confluenceUrl: pageUrl(env.baseUrl, env.spaceKey, published.id)
+		});
+	}
+	const currentSources = new Set(targets.map((t) => t.sourceFile));
+	for (const c of prevChildren ?? []) {
+		if (currentSources.has(c.sourceFile)) continue;
+		if (await deleteConfluenceItem(client, c.confluencePageId, c.isFolder)) log.itemDeleted({
+			env: env.key,
+			title: `retirée : ${c.title}`
+		});
+	}
+	const rootFolder = targets.find((t) => t.isFolder && !t.parentFolderKey);
+	return {
+		confluencePageId: rootFolder ? resolvedFolderIds.get(`${env.key}:${rootFolder.id}`) : "",
+		environment: env.key,
+		title: entry.title ?? entry.path,
+		sourceFile: entry.relPath,
+		publishedAt: ctx.now,
+		maintainedIn: "code",
+		...targets.some((t) => t.isFolder) ? { isFolder: true } : {},
+		children
+	};
+}
+async function publishCode(ctx, entry, existingId, prevChildren) {
+	const env = entry.env;
+	const client = await ctx.registry.connect(env);
+	const targets = ctx.codeTargetsByCodocId.get(entry.codocId) ?? [];
+	if (!targets.length) {
+		log.warning1(`[SKIPPED] "${entry.path}" (codocId ${entry.codocId}) : dossier/fichier local vide ou introuvable - rien à publier, ignorée.`);
+		return;
+	}
+	if (entry.kind !== "page") {
+		await assertParentExists(client, entry);
+		return publishMulti(ctx, env, entry, targets, prevChildren);
+	}
+	const t = targets[0];
+	const { xml, attachments } = renderTarget(ctx, t);
+	const remote = existingId ? await pageMeta(client, existingId) != void 0 : false;
+	log.itemPublished({
+		env: env.key,
+		isUpdate: remote,
+		title: t.title
+	});
+	const published = await publishPage(ctx.confirm, client, t, xml, attachments, parentNum(t.parentPageId), existingId);
+	return makePageState({
+		pageId: published.id,
+		environment: env.key,
+		title: t.title,
+		url: urlOf(env, published),
+		sourceFile: t.sourceFile,
+		maintainedIn: "code",
+		publishedAt: ctx.now
+	});
+}
+async function pullPageToLocal(ctx, entry, client, id) {
+	const page = await client.pages.fetchPage(id);
+	await renderRemotePageToLocal(client, page, entry.relPath, entry.imagesDir);
+	return confluenceState(entry, entry.env, id, page.title, ctx.now);
+}
+//#endregion
+export { assertParentExists, confluenceState, deleteRemote, pageMeta, publishCode, pullPageToLocal };

package/dist/use-cases/sync/sync-associate.js

@@ -0,0 +1,41 @@
+//#region src/use-cases/sync/sync-associate.ts
+/** Associe entrées yaml et entrées de lock par `codocId` (lock indexé directement par codocId). */
+function associateByCodocId(lockPages, entries) {
+	const entryIds = /* @__PURE__ */ new Set();
+	const matched = [];
+	const yamlNew = [];
+	for (const entry of entries) {
+		if (!entry.codocId) {
+			yamlNew.push(entry);
+			continue;
+		}
+		entryIds.add(entry.codocId);
+		const lock = lockPages[entry.codocId];
+		if (lock) matched.push({
+			entry,
+			codocId: entry.codocId,
+			lock
+		});
+		else yamlNew.push(entry);
+	}
+	return {
+		matched,
+		lockOrphans: Object.entries(lockPages).filter(([codocId]) => !entryIds.has(codocId)).map(([codocId, lock]) => ({
+			codocId,
+			lock
+		})),
+		yamlNew
+	};
+}
+/** Valide AVANT toute mutation que chaque entrée yaml a un codocId (évite une mauvaise association silencieuse). */
+function validateCodocIds(entries) {
+	const missing = entries.filter((e) => !e.codocId).map((e) => e.path);
+	if (missing.length) throw new Error("codocId manquant dans codoc.yaml pour :\n" + missing.map((p) => `  - ${p}`).join("\n") + "\n→ Ajoute un codocId unique à chaque entrée `docs:`.");
+	const seen = /* @__PURE__ */ new Set();
+	for (const e of entries) {
+		if (seen.has(e.codocId)) throw new Error(`codocId en double dans codoc.yaml : "${e.codocId}".`);
+		seen.add(e.codocId);
+	}
+}
+//#endregion
+export { associateByCodocId, validateCodocIds };

package/dist/use-cases/sync/sync-entries.js

@@ -0,0 +1,36 @@
+import { resolveDocEnvironmentByKey } from "../../config/codoc-config-atlassian.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import "../../config/codoc-config.js";
+import path from "path";
+//#region src/use-cases/sync/sync-entries.ts
+function entryKind(docPath) {
+	if (docPath.endsWith("/**")) return "folder";
+	if (docPath.endsWith("/*")) return "glob";
+	if (docPath.endsWith("/")) return "folder";
+	return "page";
+}
+function cleanDocPath(docPath) {
+	return docPath.replace(/\/\*\*$/, "").replace(/\/\*$/, "").replace(/\/$/, "");
+}
+function buildSyncEntries(config) {
+	return config.docs.map((doc) => {
+		const env = resolveDocEnvironmentByKey(config, doc);
+		const relPath = cleanDocPath(doc.path);
+		return {
+			codocId: doc.codocId,
+			kind: entryKind(doc.path),
+			path: doc.path,
+			localPath: path.resolve(PROJECT_ROOT, relPath),
+			relPath,
+			maintainedIn: doc.maintainedIn,
+			env,
+			parentPageId: doc.confluence.parentPageId ?? env.defaultParentPageId,
+			title: doc.confluence.title,
+			titlePrefix: doc.confluence.titlePrefix,
+			titleSuffix: doc.confluence.titleSuffix,
+			imagesDir: doc.imagesDir
+		};
+	});
+}
+//#endregion
+export { buildSyncEntries, cleanDocPath, entryKind };

package/dist/use-cases/sync/sync-handlers.js

@@ -0,0 +1,140 @@
+import { fileExists, removePath } from "../../services/files-service.js";
+import { PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { log } from "../../services/log/logger.js";
+import { getFolderRef } from "../../services/confluence/folders.js";
+import { pullFolderToLocal, pulledPagesToChildren } from "../shared/pull-folder.js";
+import { assertParentExists, confluenceState, deleteRemote, pageMeta, publishCode, pullPageToLocal } from "./sync-actions.js";
+import path from "path";
+//#region src/use-cases/sync/sync-handlers.ts
+/** Passe 1 - entrée de lock sans config. Retourne l'entrée conservée, ou null si retirée. */
+async function handleLockOrphan(ctx, lock) {
+	const env = lock.environment ? ctx.envByKey.get(lock.environment) : void 0;
+	if (!env) {
+		log.warning2(`"${lock.title}" : environnement "${lock.environment ?? "?"}" inconnu - conservée dans le lock.`);
+		return lock;
+	}
+	const client = await ctx.registry.connect(env);
+	const absLocal = path.resolve(PROJECT_ROOT, lock.sourceFile);
+	if (lock.maintainedIn === "confluence") {
+		if (lock.isFolder ? Boolean(await getFolderRef(client, lock.confluencePageId)) : await pageMeta(client, lock.confluencePageId)) {
+			removePath(absLocal);
+			log.itemCleaned(`"${lock.title}" retirée de la config → doc locale supprimée (${lock.sourceFile}). Page Confluence conservée.`);
+			return null;
+		}
+		if (await ctx.confirm(`⚠️  "${lock.title}" : page Confluence introuvable ET retirée de la config. Supprimer la doc locale "${lock.sourceFile}" ? (perte définitive possible)`)) {
+			removePath(absLocal);
+			log.itemCleaned(`Doc locale supprimée : ${lock.sourceFile}`);
+			return null;
+		}
+		log.itemKept(`Conservée : ${lock.sourceFile}`);
+		return lock;
+	}
+	const warn = fileExists(absLocal) ? "" : " (doc locale absente - perte définitive possible)";
+	if (!await ctx.confirm(`[DELETE] "${lock.title}" retirée de la config. Supprimer la page Confluence distante${warn} ?`)) {
+		log.itemKept(`Conservée à distance : ${lock.title}`);
+		return lock;
+	}
+	await deleteRemote(client, lock);
+	log.itemDeleted({
+		env: env.key,
+		title: lock.title
+	});
+	return null;
+}
+/** Passe 1 - entrée appariée (codocId présent des deux côtés). On garde le confluencePageId. */
+async function syncMatched(ctx, entry, lock) {
+	const env = entry.env;
+	const client = await ctx.registry.connect(env);
+	const cpid = lock.confluencePageId;
+	if (entry.maintainedIn === "code") return await publishCode(ctx, entry, cpid, lock.children) ?? lock;
+	if (entry.kind === "page") {
+		const meta = await pageMeta(client, cpid);
+		if (!meta) throw new Error(`"${entry.title ?? entry.path}" : page Confluence ${cpid} introuvable. Revois la config (codocId).`);
+		if (entry.title && meta.title !== entry.title) throw new Error(`"${entry.path}" : titre Confluence ("${meta.title}") ≠ config ("${entry.title}"). Revois la config.`);
+		if (entry.parentPageId && meta.parentId && meta.parentId !== entry.parentPageId) throw new Error(`"${entry.path}" : parent Confluence (${meta.parentId}) ≠ config (${entry.parentPageId}). Revois la config.`);
+		log.itemPulled({
+			env: env.key,
+			title: entry.title ?? cpid,
+			dest: entry.relPath
+		});
+		return pullPageToLocal(ctx, entry, client, cpid);
+	}
+	await assertParentExists(client, entry);
+	const folderMeta = await getFolderRef(client, cpid);
+	if (!folderMeta) throw new Error(`"${entry.path}" : dossier Confluence ${cpid} introuvable. Revois la config.`);
+	log.itemPulled({
+		env: env.key,
+		title: `dossier "${folderMeta.title}"`,
+		dest: entry.relPath
+	});
+	const pulled = await pullFolderToLocal({
+		confluenceClient: client,
+		rootId: cpid,
+		rootType: folderMeta.type,
+		localDir: entry.relPath,
+		imagesDir: entry.imagesDir,
+		prevChildren: lock.children,
+		onPage: (p, i, total) => log.progress(i, total, p.title)
+	});
+	log.success4(`[PULL] ${pulled.length} page(s) importée(s)`);
+	return {
+		...confluenceState(entry, env, cpid, folderMeta.title, ctx.now),
+		isFolder: true,
+		children: pulledPagesToChildren(pulled, env.baseUrl, env.spaceKey)
+	};
+}
+/** Passe 2 - entrée yaml sans équivalent dans le lock (création / premier pull). Retourne `undefined` si rien à faire (voir `publishCode`). */
+async function syncNew(ctx, entry) {
+	const env = entry.env;
+	const client = await ctx.registry.connect(env);
+	if (entry.maintainedIn === "code") return publishCode(ctx, entry);
+	if (entry.kind === "page") {
+		if (!entry.title) throw new Error(`"${entry.path}" : titre Confluence requis dans la config pour retrouver la page.`);
+		log.itemPulled({
+			env: env.key,
+			title: entry.title,
+			dest: entry.relPath
+		});
+		const found = await client.pages.findByTitle(entry.title);
+		if (!found) throw new Error(`"${entry.title}" : page Confluence introuvable (env ${env.key}). Revois la config ou fais 'codoc pull'.`);
+		const id = String(found.id);
+		const meta = await pageMeta(client, id);
+		if (entry.parentPageId && meta?.parentId && meta.parentId !== entry.parentPageId) throw new Error(`"${entry.title}" : parent Confluence (${meta.parentId}) ≠ config (${entry.parentPageId}). Revois la config.`);
+		return pullPageToLocal(ctx, entry, client, id);
+	}
+	if (!entry.title) throw new Error(`"${entry.path}" : titre Confluence requis dans la config pour retrouver le dossier.`);
+	const page = await client.pages.findByTitle(entry.title);
+	const found = page ? {
+		id: String(page.id),
+		type: "page"
+	} : entry.parentPageId ? await client.folders.findByTitleUnderParent(entry.parentPageId, entry.title).then((f) => f ? {
+		...f,
+		type: "folder"
+	} : void 0) : void 0;
+	if (!found) throw new Error(`"${entry.title}" : dossier Confluence introuvable (env ${env.key}). Revois la config ou fais 'codoc pull'.`);
+	if (entry.parentPageId) {
+		const parentId = found.type === "page" ? (await pageMeta(client, found.id))?.parentId : (await client.folders.get(found.id))?.parentId;
+		if (parentId && parentId !== entry.parentPageId) throw new Error(`"${entry.title}" : parent Confluence (${parentId}) ≠ config (${entry.parentPageId}). Revois la config.`);
+	}
+	log.itemPulled({
+		env: env.key,
+		title: `dossier "${entry.title}" (premier import)`,
+		dest: entry.relPath
+	});
+	const pulled = await pullFolderToLocal({
+		confluenceClient: client,
+		rootId: found.id,
+		rootType: found.type,
+		localDir: entry.relPath,
+		imagesDir: entry.imagesDir,
+		onPage: (p, i, total) => log.progress(i, total, p.title)
+	});
+	log.success4(`[PULL] ${pulled.length} page(s) importée(s) - dossier local créé`);
+	return {
+		...confluenceState(entry, env, found.id, entry.title, ctx.now),
+		isFolder: true,
+		children: pulledPagesToChildren(pulled, env.baseUrl, env.spaceKey)
+	};
+}
+//#endregion
+export { handleLockOrphan, syncMatched, syncNew };

package/dist/use-cases/sync/sync-helpers.js

@@ -0,0 +1,8 @@
+import { wikiLink } from "../../clients/confluence/utils/confluence-url.js";
+//#region src/use-cases/sync/sync-helpers.ts
+const parentNum = (p) => p ? Number(p) : void 0;
+function urlOf(env, published) {
+	return published._links?.webui ? wikiLink(env.baseUrl, published._links.webui) : void 0;
+}
+//#endregion
+export { parentNum, urlOf };