codoc-cli 0.1.2

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

@@ -0,0 +1,94 @@
+import { getCodocConfig } from "../../config/codoc-config.js";
+import { createRl, resolveConfirm } from "../../services/prompt.js";
+import { log } from "../../services/log/logger.js";
+import { loadPublishState, savePublishState } from "../../services/lock/lock-file.js";
+import { getDefaultBranch } from "../../services/git/default-branch.js";
+import { listDocumentTargets } from "../shared/list-documents.js";
+import { EnvRegistry } from "../shared/confluence-client-registry.js";
+import { selectEnvs } from "../shared/env-select.js";
+import { buildSyncEntries } from "./sync-entries.js";
+import { closeDrawioRenderer } from "../../services/conversion/confluenceToMarkdown/diagrams/drawio-to-image.js";
+import { handleLockOrphan, syncMatched, syncNew } from "./sync-handlers.js";
+import { associateByCodocId, validateCodocIds } from "./sync-associate.js";
+//#region src/use-cases/sync/sync.ts
+async function sync(opts = {}) {
+	log.startProcess("Synchronisation de la documentation...");
+	const config = getCodocConfig();
+	const envByKey = new Map(config.atlassian.environments.map((e) => [e.key, e]));
+	const targetEnv = opts.env;
+	selectEnvs(config, targetEnv);
+	if (targetEnv) {
+		log.info0(`Environnement ciblé : ${targetEnv}`);
+		log.blank();
+	}
+	if (opts.confirm === false) {
+		log.info0("--no-confirm : les suppressions et adoptions nécessitant confirmation sont refusées (rien de risqué n'est fait).");
+		log.blank();
+	}
+	const previousState = loadPublishState();
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const entries = buildSyncEntries(config).filter((e) => !targetEnv || e.env.key === targetEnv);
+	const scopedLock = {};
+	const keptOutOfScope = {};
+	for (const [key, p] of Object.entries(previousState.pages)) (!targetEnv || p.environment === targetEnv ? scopedLock : keptOutOfScope)[key] = p;
+	validateCodocIds(entries);
+	const codeTargetsByCodocId = /* @__PURE__ */ new Map();
+	for (const t of await listDocumentTargets()) {
+		if (t.maintainedIn !== "code" || !t.codocId) continue;
+		const list = codeTargetsByCodocId.get(t.codocId);
+		if (list) list.push(t);
+		else codeTargetsByCodocId.set(t.codocId, [t]);
+	}
+	const assoc = associateByCodocId(scopedLock, entries);
+	const rl = createRl();
+	const ctx = {
+		config,
+		generatedAt: now,
+		registry: new EnvRegistry(),
+		envByKey,
+		now,
+		confirm: (question) => resolveConfirm(rl, {
+			flag: opts.confirm,
+			question,
+			default: false
+		}),
+		codeTargetsByCodocId,
+		defaultBranch: await getDefaultBranch()
+	};
+	const newPages = { ...keptOutOfScope };
+	try {
+		if (assoc.lockOrphans.length) {
+			log.info0(`${assoc.lockOrphans.length} entrée(s) de lock sans config :`);
+			log.blank();
+		}
+		for (const { codocId, lock } of assoc.lockOrphans) {
+			const kept = await handleLockOrphan(ctx, lock);
+			if (kept) newPages[codocId] = kept;
+		}
+		if (assoc.matched.length) {
+			log.blank();
+			log.info0(`${assoc.matched.length} doc(s) suivie(s) :`);
+			log.blank();
+		}
+		for (const { entry, lock } of assoc.matched) newPages[entry.codocId] = await syncMatched(ctx, entry, lock);
+		if (assoc.yamlNew.length) {
+			log.blank();
+			log.info0(`${assoc.yamlNew.length} nouvelle(s) doc(s) :`);
+			log.blank();
+		}
+		for (const entry of assoc.yamlNew) {
+			const state = await syncNew(ctx, entry);
+			if (state) newPages[entry.codocId] = state;
+		}
+	} finally {
+		rl.close();
+		await closeDrawioRenderer();
+	}
+	savePublishState({
+		lastPublished: now,
+		pages: newPages
+	});
+	log.endProcess(`codoc.lock mis à jour (${Object.keys(newPages).length} entrée(s)).`);
+}
+//#endregion
+export { sync };

package/dist/use-cases/tree/docs-tree.js

@@ -0,0 +1,141 @@
+import { getCodocConfig } from "../../config/codoc-config.js";
+import { ansi, log } from "../../services/log/logger.js";
+import { findLockedRef, loadPublishState } from "../../services/lock/lock-file.js";
+import { listDocumentTargets } from "../shared/list-documents.js";
+import { pageUrl, wikiBase } from "../../clients/confluence/utils/confluence-url.js";
+import { EnvRegistry } from "../shared/confluence-client-registry.js";
+import { selectEnvs } from "../shared/env-select.js";
+//#region src/use-cases/tree/docs-tree.ts
+const ROOT_KEY = "(racine)";
+const isPageId = (id) => /^\d+$/.test(id);
+function printPage(node, prefix, isLast) {
+	const connector = isLast ? "└─ " : "├─ ";
+	const badge = node.isFolder ? "[FOLDER]" : node.deployed ? ansi.green("✅") : ansi.yellow("⚠️");
+	const label = node.isFolder ? ansi.bold(node.title) : node.title;
+	const hint = node.isFolder ? "" : `  ${ansi.dim(node.sourceFile)}`;
+	log.raw(`${prefix}${connector}${badge} ${ansi.link(label, node.url)}${hint}`);
+	const childPrefix = prefix + (isLast ? "   " : "│  ");
+	const kids = [...node.children].sort((a, b) => a.title.localeCompare(b.title, "fr"));
+	kids.forEach((k, i) => printPage(k, childPrefix, i === kids.length - 1));
+}
+function printFolder(folder, prefix, isLast) {
+	const connector = isLast ? "└─ " : "├─ ";
+	const idHint = isPageId(folder.id) ? ansi.dim(` (${folder.id})`) : "";
+	log.raw(`${prefix}${connector}[FOLDER] ${ansi.link(ansi.bold(folder.title), folder.url)}${idHint}`);
+	const childPrefix = prefix + (isLast ? "   " : "│  ");
+	const subs = [...folder.subFolders.values()].sort((a, b) => a.title.localeCompare(b.title, "fr"));
+	const pages = [...folder.pages].sort((a, b) => a.title.localeCompare(b.title, "fr"));
+	const total = subs.length + pages.length;
+	let i = 0;
+	for (const sf of subs) printFolder(sf, childPrefix, ++i === total);
+	for (const p of pages) printPage(p, childPrefix, ++i === total);
+}
+/** Place chaque groupe de pages sous son dossier, imbriqué selon `chains` si fourni. */
+function buildFolderForest(pagesByFolder, chains, baseUrl, spaceKey) {
+	const roots = /* @__PURE__ */ new Map();
+	const getOrCreate = (level, id, title) => {
+		let f = level.get(id);
+		if (!f) {
+			f = {
+				id,
+				title,
+				url: isPageId(id) ? pageUrl(baseUrl, spaceKey, id) : void 0,
+				subFolders: /* @__PURE__ */ new Map(),
+				pages: []
+			};
+			level.set(id, f);
+		}
+		return f;
+	};
+	for (const [folderId, pages] of pagesByFolder) {
+		const chain = chains.get(folderId) ?? [{
+			id: folderId,
+			title: folderId === ROOT_KEY ? "Racine de l'espace" : `Dossier`
+		}];
+		let level = roots;
+		let node;
+		for (const { id, title } of chain) {
+			node = getOrCreate(level, id, title);
+			level = node.subFolders;
+		}
+		node.pages.push(...pages);
+	}
+	return [...roots.values()];
+}
+async function printEnvTree(env, registry, targets, lock) {
+	const locked = (t) => findLockedRef(lock, env.key, t.sourceFile);
+	const nodes = targets.map((t) => {
+		const l = locked(t);
+		return {
+			title: t.title,
+			sourceFile: t.sourceFile,
+			deployed: !!l,
+			pageId: l?.confluencePageId,
+			url: l?.confluenceUrl,
+			parentPageId: t.parentPageId,
+			children: [],
+			isFolder: t.isFolder
+		};
+	});
+	const nodeByLocalFolderKey = /* @__PURE__ */ new Map();
+	targets.forEach((t, i) => {
+		if (t.isFolder) nodeByLocalFolderKey.set(`${env.key}:${t.id}`, nodes[i]);
+	});
+	const byPageId = /* @__PURE__ */ new Map();
+	for (const n of nodes) if (n.pageId) byPageId.set(n.pageId, n);
+	const pagesByFolder = /* @__PURE__ */ new Map();
+	targets.forEach((t, i) => {
+		const n = nodes[i];
+		const localFolder = t.parentFolderKey ? nodeByLocalFolderKey.get(t.parentFolderKey) : void 0;
+		if (localFolder) {
+			localFolder.children.push(n);
+			return;
+		}
+		const parent = n.parentPageId ? byPageId.get(n.parentPageId) : void 0;
+		if (parent) {
+			parent.children.push(n);
+			return;
+		}
+		const key = n.parentPageId ?? ROOT_KEY;
+		(pagesByFolder.get(key) ?? pagesByFolder.set(key, []).get(key)).push(n);
+	});
+	const chains = /* @__PURE__ */ new Map();
+	try {
+		const client = registry.raw(env);
+		for (const id of pagesByFolder.keys()) {
+			if (!isPageId(id)) continue;
+			try {
+				chains.set(id, await client.pages.fetchAncestors(id));
+			} catch {
+				log.warning2("dossier inaccessible → reste à plat avec son id");
+			}
+		}
+	} catch {
+		log.warning2("impossible d'initialiser le client (creds absentes) → tout reste à plat");
+	}
+	const forest = buildFolderForest(pagesByFolder, chains, env.baseUrl, env.spaceKey);
+	const deployedCount = nodes.filter((n) => n.deployed).length;
+	const spaceUrl = `${wikiBase(env.baseUrl)}/spaces/${env.spaceKey}`;
+	log.blank();
+	log.raw(`${ansi.bold(`Documentation Confluence [${env.key}]`)} - espace ${ansi.link(ansi.cyan(env.spaceKey), spaceUrl)}  ${ansi.dim(env.baseUrl)}`);
+	log.blank();
+	const sorted = forest.sort((a, b) => a.title.localeCompare(b.title, "fr"));
+	sorted.forEach((f, i) => printFolder(f, "", i === sorted.length - 1));
+	log.raw(ansi.dim(`${nodes.length} page(s) · ${deployedCount} déployée(s)`));
+}
+async function printDocsTree(opts = {}) {
+	const config = getCodocConfig();
+	const environments = selectEnvs(config, opts.env);
+	const allTargets = await listDocumentTargets();
+	const lock = loadPublishState();
+	const registry = new EnvRegistry();
+	for (const env of environments) {
+		const targets = allTargets.filter((t) => t.env.key === env.key);
+		if (!targets.length) continue;
+		await printEnvTree(env, registry, targets, lock);
+	}
+	log.blank();
+	log.raw(`${ansi.dim("Légende :")} ${ansi.green("✅")} déployé   ${ansi.yellow("⚠️")} défini mais pas encore publié`);
+}
+//#endregion
+export { printDocsTree };

package/oclif.manifest.json

@@ -0,0 +1,255 @@
+{
+  "commands": {
+    "init": {
+      "aliases": [],
+      "args": {},
+      "description": "Initialise la configuration codoc : codoc.yaml, .env-codoc, guide de démarrage. Avec --agent-md, ne génère que le guide agent IA (rien d'autre).",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --agent-md"
+      ],
+      "flags": {
+        "agent-md": {
+          "description": "Ne génère QUE le guide agent IA basé sur `codoc.yaml` (qui doit déjà exister et être rempli) - au choix (via --agent-target, sinon celui déjà en place, sinon demandé) dans `.github/agents/codoc-agent.md` (fichier dédié) ou injecté en bloc dans `.github/copilot-instructions.md`. N'affecte aucun autre fichier.",
+          "name": "agent-md",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "agent-target": {
+          "description": "Avec --agent-md : destination du guide (fichier dédié ou bloc copilot-instructions.md). Par défaut : celle déjà en place, sinon demandé.",
+          "name": "agent-target",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "agent",
+            "copilot"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "codoc-cli",
+      "pluginName": "codoc-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init.js"
+      ]
+    },
+    "publish": {
+      "aliases": [],
+      "args": {
+        "path": {
+          "description": "Chemin local relatif de la doc .md ou du dossier à publier",
+          "name": "path",
+          "required": false
+        }
+      },
+      "description": "Publie une doc locale (fichier ou dossier) vers Confluence, avec ajout optionnel à codoc.yaml. Toute information non fournie en flag (ni déjà présente dans codoc.yaml) est demandée en console.",
+      "flags": {
+        "env": {
+          "description": "Environnement Confluence cible (clé). Par défaut : celui de la config existante, sinon auto/prompt.",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "in-config": {
+          "description": "Ajoute (ou met à jour) l'entrée codoc.yaml de cette doc. --no-in-config publie sans toucher ni à codoc.yaml ni à codoc.lock (publication ponctuelle, non suivie par `codoc sync`). Non fourni : demande en fin de commande.",
+          "name": "in-config",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "parent-page-id": {
+          "description": "parentPageId Confluence cible. Par défaut : celui de la config existante ou defaultParentPageId de l’env.",
+          "name": "parent-page-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "title": {
+          "description": "Titre de la page Confluence (fichier unique uniquement). Par défaut : celui de la config existante, sinon le H1 du fichier.",
+          "name": "title",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "publish",
+      "pluginAlias": "codoc-cli",
+      "pluginName": "codoc-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "publish.js"
+      ]
+    },
+    "pull": {
+      "aliases": [],
+      "args": {
+        "page": {
+          "description": "URL ou ID de la page Confluence à importer",
+          "name": "page",
+          "required": false
+        }
+      },
+      "description": "Importe une page Confluence en local, avec ajout optionnel à codoc.yaml. Toute information non fournie en flag (ni déjà présente dans codoc.yaml) est demandée en console.",
+      "flags": {
+        "env": {
+          "description": "Environnement Confluence où chercher la page. Par défaut : déduit de l’URL, sinon auto/prompt.",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "as-folder": {
+          "description": "Si la page a des sous-pages/sous-dossiers, importe tout le dossier (--as-folder) ou seulement la page (--no-as-folder). Sans sous-élément, ignoré. Non fourni : demande le cas échéant.",
+          "name": "as-folder",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "keep-existing": {
+          "description": "Si un import précédent est détecté (même ID/titre/config), le remplace (--keep-existing, valeurs existantes comme défauts) ou crée un import séparé (--no-keep-existing). Non fourni : demande le cas échéant.",
+          "name": "keep-existing",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "in-config": {
+          "description": "Ajoute (ou met à jour) l'entrée codoc.yaml de cette doc. --no-in-config importe sans toucher ni à codoc.yaml ni à codoc.lock (import ponctuel, non suivi par `codoc sync`). Non fourni : demande en fin de commande.",
+          "name": "in-config",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "local-path": {
+          "description": "Chemin local du fichier .md (page unique) ou du dossier de destination (import dossier).",
+          "name": "local-path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "title": {
+          "description": "Titre de la page Confluence (page unique). Par défaut : celui de la config existante, sinon le titre Confluence.",
+          "name": "title",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "parent-page-id": {
+          "description": "parentPageId Confluence. Par défaut : celui de la config existante, sinon le parent réel de la page.",
+          "name": "parent-page-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "maintained-in": {
+          "description": "code → le .md local fait foi ; confluence → la page Confluence fait foi. Par défaut : confluence.",
+          "name": "maintained-in",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "code",
+            "confluence"
+          ],
+          "type": "option"
+        },
+        "images-dir": {
+          "description": "Dossier local pour les images (\"\" pour désactiver). Par défaut : doc/img.",
+          "name": "images-dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "pull",
+      "pluginAlias": "codoc-cli",
+      "pluginName": "codoc-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "pull.js"
+      ]
+    },
+    "sync": {
+      "aliases": [],
+      "args": {},
+      "description": "Synchronise chaque doc locale et Confluence",
+      "flags": {
+        "env": {
+          "description": "Ne synchronise que cet environnement Confluence (clé). Par défaut : tous.",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "confirm": {
+          "char": "f",
+          "description": "Répond automatiquement aux suppressions de pages et adoptions de page en conflit de titre : --confirm accepte tout (CI), --no-confirm refuse tout (rien de risqué ne se fait). Non fourni : demande à chaque cas, comme en local.",
+          "name": "confirm",
+          "allowNo": true,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sync",
+      "pluginAlias": "codoc-cli",
+      "pluginName": "codoc-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "sync.js"
+      ]
+    },
+    "tree": {
+      "aliases": [],
+      "args": {},
+      "description": "Affiche l’arborescence des documents",
+      "flags": {
+        "env": {
+          "description": "N’affiche que cet environnement Confluence (clé). Par défaut : tous.",
+          "name": "env",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "tree",
+      "pluginAlias": "codoc-cli",
+      "pluginName": "codoc-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "tree.js"
+      ]
+    }
+  },
+  "version": "0.1.2"
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "codoc-cli",
+  "displayName": "codoc-cli",
+  "description": "Synchronisation de documentation Confluence <-> code (Markdown <-> Confluence)",
+  "version": "0.1.2",
+  "author": "CDA - Klee",
+  "bin": {
+    "codoc": "bin/run.js"
+  },
+  "bugs": "https://github.com/klee-contrib/codoc/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/klee-contrib/codoc.git"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "@oclif/core": "^4",
+    "@puppeteer/browsers": "^2.13.2",
+    "@oclif/plugin-autocomplete": "^3.2.40",
+    "@oclif/plugin-help": "^6",
+    "@oclif/plugin-version": "^2.2.36",
+    "dotenv": "^17.4.2",
+    "execa": "^9.6.1",
+    "js-yaml": "^4.2.0",
+    "ky": "^1.14.2",
+    "marked": "^11.1.1",
+    "ora": "^9.0.0",
+    "puppeteer": "^24",
+    "simple-git": "^3.30.0",
+    "turndown": "^7.1.2",
+    "turndown-plugin-gfm": "^1.0.2"
+  },
+  "devDependencies": {
+    "@oclif/prettier-config": "0.2.1",
+    "@oclif/test": "^4.1.18",
+    "@types/js-yaml": "^4.0.9",
+    "@types/marked": "^6.0.0",
+    "@types/node": "^24",
+    "@types/turndown": "^5.0.2",
+    "c8": "^11.0.0",
+    "oclif": "^4.23.7",
+    "oxlint": "1.65.0",
+    "shx": "^0.4.0",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.22.0",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "./bin",
+    "./dist",
+    "./assets",
+    "./oclif.manifest.json"
+  ],
+  "homepage": "https://github.com/klee-contrib/codoc",
+  "keywords": [
+    "oclif"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "type": "module",
+  "oclif": {
+    "bin": "codoc",
+    "dirname": "codoc",
+    "commands": "./dist/commands",
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-autocomplete",
+      "@oclif/plugin-version"
+    ],
+    "topicSeparator": " ",
+    "hooks": {
+      "init": [
+        "./dist/hooks/init/load-env",
+        "./dist/hooks/init/check-for-update"
+      ],
+      "command_not_found": "./dist/hooks/command_not_found"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint-fix": "oxlint --fix",
+    "prepack": "tsdown && oclif manifest",
+    "postpack": "shx rm -f oclif.manifest.json",
+    "posttest": "npm run lint",
+    "test": "node --import ./test/register.mjs --test \"test/**/*.test.ts\"",
+    "test:update-snapshots": "node --import ./test/register.mjs --test --test-update-snapshots \"test/**/*.test.ts\"",
+    "test:junit": "shx mkdir -p test-results && node --import ./test/register.mjs --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=./test-results/junit.xml \"test/**/*.test.ts\"",
+    "test:coverage": "c8 node --import ./test/register.mjs --test \"test/**/*.test.ts\"",
+    "test:ci": "shx mkdir -p test-results && c8 node --import ./test/register.mjs --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=./test-results/junit.xml \"test/**/*.test.ts\"",
+    "coverage:report": "c8 --reporter=lcov node --import ./test/register.mjs --test \"test/**/*.test.ts\""
+  },
+  "types": "dist/index.d.ts"
+}