codoc-cli 0.1.2

package/dist/services/log/logger.js

@@ -0,0 +1,131 @@
+import { checkbox } from "@inquirer/prompts";
+//#region src/services/log/logger.ts
+const raw = (text) => console.log(text);
+const warnRaw = (text) => console.warn(text);
+const ansi = {
+	dim: (s) => `\x1b[2m${s}\x1b[0m`,
+	bold: (s) => `\x1b[1m${s}\x1b[0m`,
+	green: (s) => `\x1b[32m${s}\x1b[0m`,
+	yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+	cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+	link: (text, url) => url ? `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\` : text
+};
+const INDENT = [
+	"",
+	"  ",
+	"   ",
+	"     ",
+	"        "
+];
+function info(level, text) {
+	raw(`${INDENT[level]}ℹ️  ${text}`);
+}
+function success(level, text) {
+	raw(`${INDENT[level]}✅ ${text}`);
+}
+function warning(level, text) {
+	warnRaw(`${INDENT[level]}⚠️  ${text}`);
+}
+function error(level, text) {
+	warnRaw(`${INDENT[level]}❌ ${text}`);
+}
+function step(level, text) {
+	raw(`${INDENT[level]}${text}…`);
+}
+const log = {
+	info0: (text) => info(0, text),
+	info1: (text) => info(1, text),
+	info2: (text) => info(2, text),
+	info3: (text) => info(3, text),
+	info4: (text) => info(4, text),
+	success0: (text) => success(0, text),
+	success1: (text) => success(1, text),
+	success2: (text) => success(2, text),
+	success3: (text) => success(3, text),
+	success4: (text) => success(4, text),
+	warning0: (text) => warning(0, text),
+	warning1: (text) => warning(1, text),
+	warning2: (text) => warning(2, text),
+	warning3: (text) => warning(3, text),
+	warning4: (text) => warning(4, text),
+	error0: (text) => error(0, text),
+	error1: (text) => error(1, text),
+	error2: (text) => error(2, text),
+	error3: (text) => error(3, text),
+	error4: (text) => error(4, text),
+	step0: (text) => step(0, text),
+	step1: (text) => step(1, text),
+	step2: (text) => step(2, text),
+	step3: (text) => step(3, text),
+	step4: (text) => step(4, text),
+	blank() {
+		raw("");
+	},
+	raw(text) {
+		raw(text);
+	},
+	startProcess(text) {
+		raw(`\n${text}\n`);
+	},
+	endProcess(text) {
+		raw(`\n${text}`);
+	},
+	field(label, value) {
+		raw(`${INDENT[1]}${label} : ${value}`);
+	},
+	itemPublished(p) {
+		raw(`${INDENT[2]}${p.isUpdate ? "[UPDATED]" : "[CREATED]"} [${p.env}] ${p.title}…`);
+	},
+	itemPulled(p) {
+		const tail = p.dest ? ` → ${p.dest}` : "";
+		raw(`${INDENT[2]}[PULL] [${p.env}] ${p.title}${tail}…`);
+	},
+	itemFolder(p) {
+		raw(`${INDENT[2]}[FOLDER] [${p.env}] ${p.title}…`);
+	},
+	itemDeleted(p) {
+		raw(`${INDENT[2]}[DELETED] [${p.env}] ${p.title}`);
+	},
+	itemKept(text) {
+		raw(`${INDENT[2]}[UNCHANGED] ${text}`);
+	},
+	itemCleaned(text) {
+		raw(`${INDENT[2]}[REMOVED] ${text}`);
+	},
+	progress(i, total, text) {
+		raw(`${INDENT[3]}[${i}/${total}] ${text}`);
+	},
+	async checklist(message, items, options = {}) {
+		return checkbox({
+			choices: items.map((item) => ({
+				name: item,
+				value: item,
+				checked: true
+			})),
+			loop: false,
+			message,
+			pageSize: options.pageSize ?? 30,
+			required: options.required ?? false
+		});
+	},
+	finalBanner(title, fields = {}) {
+		const INNER_WIDTH = 54;
+		const bar = "═".repeat(INNER_WIDTH);
+		const titleLine = `  ${title}`.padEnd(INNER_WIDTH, " ");
+		raw("");
+		raw(`╔${bar}╗`);
+		raw(`║${titleLine}║`);
+		raw(`╚${bar}╝`);
+		const entries = Object.entries(fields).filter(([, v]) => v !== void 0);
+		if (entries.length) {
+			raw("");
+			for (const [k, v] of entries) {
+				const indented = String(v).replace(/\n/g, `\n  ${" ".repeat(k.length + 3)}`);
+				raw(`  ${k} : ${indented}`);
+			}
+		}
+		raw("");
+	}
+};
+//#endregion
+export { ansi, log };

package/dist/services/prompt.js

@@ -0,0 +1,32 @@
+import readline from "readline/promises";
+import { stdin, stdout } from "process";
+//#region src/services/prompt.ts
+function createRl() {
+	return readline.createInterface({
+		input: stdin,
+		output: stdout
+	});
+}
+async function ask(rl, question) {
+	return (await rl.question(`  ${question} `)).trim();
+}
+async function askWithDefault(rl, question, defaultValue) {
+	return await ask(rl, `${question} [${defaultValue}]`) || defaultValue;
+}
+async function confirm(rl, question, defaultForce = false) {
+	const answer = (await ask(rl, `${question} ${defaultForce ? "[O/n]" : "[o/n]"}`)).toLowerCase();
+	return defaultForce ? answer !== "n" : answer === "o";
+}
+/** Résolution uniforme d'une valeur : flag CLI → valeur codoc.yaml → prompt (avec `promptDefault`
+* comme valeur pré-remplie affichée, ce qui ne dispense pas de la question). */
+async function resolveValue(rl, opts) {
+	if (opts.flag !== void 0) return opts.flag;
+	if (opts.config !== void 0) return opts.config;
+	return opts.promptDefault !== void 0 ? askWithDefault(rl, opts.prompt, opts.promptDefault) : ask(rl, opts.prompt);
+}
+/** Résolution uniforme d'une décision oui/non : flag CLI → prompt. */
+async function resolveConfirm(rl, opts) {
+	return opts.flag ?? await confirm(rl, opts.question, opts.default);
+}
+//#endregion
+export { ask, askWithDefault, confirm, createRl, resolveConfirm, resolveValue };

package/dist/services/slugify.js

@@ -0,0 +1,6 @@
+//#region src/services/slugify.ts
+function slugify(text) {
+	return text.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+//#endregion
+export { slugify };

package/dist/types/codoc-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,150 @@
+import { ensureDir, fileExists, readFile, removePath, writeFile } from "../../services/files-service.js";
+import { CODOC_ENV_FILE, CONFIG_PATH, PROJECT_ROOT } from "../../config/codoc-paths.js";
+import { getCodocConfig } from "../../config/codoc-config.js";
+import { generateRandomCodocId } from "../../services/codoc-id.js";
+import { agentMdContent } from "../../services/init-templates/agent-md-init.js";
+import { docguideContent } from "../../services/init-templates/doc-guide-init.js";
+import { envTemplate } from "../../services/init-templates/env-init.js";
+import { yamlTemplate } from "../../services/init-templates/yaml-init.js";
+import { askWithDefault, createRl } from "../../services/prompt.js";
+import crypto from "node:crypto";
+import path from "node:path";
+//#region src/use-cases/init/init.ts
+const AGENT_MD_PATH = path.join(PROJECT_ROOT, ".github", "agents", "codoc-agent.md");
+const AGENT_MD_LABEL = ".github/agents/codoc-agent.md";
+const LEGACY_AGENT_MD_PATH = path.join(PROJECT_ROOT, ".github", "codoc-agent.md");
+const COPILOT_INSTRUCTIONS_PATH = path.join(PROJECT_ROOT, ".github", "copilot-instructions.md");
+const COPILOT_INSTRUCTIONS_LABEL = ".github/copilot-instructions.md";
+const COPILOT_BLOCK_START = "<!-- codoc-agent:start -->";
+const COPILOT_BLOCK_END = "<!-- codoc-agent:end -->";
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function randomId() {
+	return crypto.randomBytes(3).toString("hex");
+}
+function initCodoc() {
+	const created = [];
+	const skipped = [];
+	const warnings = [];
+	const id = randomId();
+	const docDir = path.join(PROJECT_ROOT, "doc");
+	const docFilename = `codoc-guide-${id}.md`;
+	const docAbsPath = path.join(docDir, docFilename);
+	const docRelPath = `doc/${docFilename}`;
+	ensureDir(docDir);
+	writeFile(docAbsPath, docguideContent(id));
+	created.push(docRelPath);
+	writeIfAbsent(CONFIG_PATH, "codoc.yaml", () => yamlTemplate(docRelPath, generateRandomCodocId()), created, skipped);
+	writeIfAbsent(CODOC_ENV_FILE, ".env-codoc", envTemplate, created, skipped);
+	ensureGitignoreEntries([".env-codoc"], created, skipped);
+	return {
+		docRelPath,
+		created,
+		skipped,
+		warnings
+	};
+}
+/** `codoc init --agent-md` : ne génère que le guide agent IA, rien d'autre. Demande la destination si aucune n'existe déjà. */
+async function initAgentMdOnly(agentTarget) {
+	const created = [];
+	const warnings = [];
+	generateAgentMd(await resolveAgentMdTarget(agentTarget), created, warnings);
+	return {
+		created,
+		warnings
+	};
+}
+/** Flag → fichier déjà en place (fichier dédié ou bloc dans copilot-instructions.md) → prompt. */
+async function resolveAgentMdTarget(agentTarget) {
+	if (agentTarget === "copilot") return {
+		path: COPILOT_INSTRUCTIONS_PATH,
+		label: COPILOT_INSTRUCTIONS_LABEL
+	};
+	if (agentTarget === "agent") return {
+		path: AGENT_MD_PATH,
+		label: AGENT_MD_LABEL
+	};
+	if (fileExists(AGENT_MD_PATH)) return {
+		path: AGENT_MD_PATH,
+		label: AGENT_MD_LABEL
+	};
+	if (fileExists(COPILOT_INSTRUCTIONS_PATH)) return {
+		path: COPILOT_INSTRUCTIONS_PATH,
+		label: COPILOT_INSTRUCTIONS_LABEL
+	};
+	const rl = createRl();
+	try {
+		return (await askWithDefault(rl, "Générer le guide dans un fichier agent dédié ou dans le contexte Copilot ? (agent/copilot) :", "agent")).trim().toLowerCase().startsWith("copi") ? {
+			path: COPILOT_INSTRUCTIONS_PATH,
+			label: COPILOT_INSTRUCTIONS_LABEL
+		} : {
+			path: AGENT_MD_PATH,
+			label: AGENT_MD_LABEL
+		};
+	} finally {
+		rl.close();
+	}
+}
+/** Génère le guide agent IA à la destination choisie, migre l'ancien emplacement `.github/codoc-agent.md` si besoin. */
+function generateAgentMd(target, created, warnings) {
+	try {
+		const config = getCodocConfig();
+		const content = agentMdContent(config);
+		const hadLegacy = fileExists(LEGACY_AGENT_MD_PATH);
+		const status = target.path === COPILOT_INSTRUCTIONS_PATH ? writeAgentMdBlock(COPILOT_INSTRUCTIONS_PATH, content) : writeDedicatedAgentMd(AGENT_MD_PATH, content);
+		if (hadLegacy && target.path !== LEGACY_AGENT_MD_PATH) removePath(LEGACY_AGENT_MD_PATH);
+		created.push(`${target.label} (${hadLegacy ? "déplacé depuis .github/codoc-agent.md" : status})`);
+	} catch (err) {
+		warnings.push(`${target.label} : impossible de générer - ${err.message.split("\n")[0]}. Remplis codoc.yaml puis relance \`codoc init --agent-md\`.`);
+	}
+}
+/** Fichier dédié et entièrement possédé par codoc : contenu remplacé intégralement. */
+function writeDedicatedAgentMd(absPath, content) {
+	const existed = fileExists(absPath);
+	writeFile(absPath, content);
+	return existed ? "regénéré" : "créé";
+}
+/** copilot-instructions.md est partagé avec d'autres instructions : injection idempotente par bloc balisé. */
+function writeAgentMdBlock(absPath, content) {
+	const block = `${COPILOT_BLOCK_START}\n${content.trim()}\n${COPILOT_BLOCK_END}`;
+	if (!fileExists(absPath)) {
+		ensureDir(path.dirname(absPath));
+		writeFile(absPath, `${block}\n`);
+		return "créé";
+	}
+	const existing = readFile(absPath);
+	const blockRe = new RegExp(`${escapeRegex(COPILOT_BLOCK_START)}[\\s\\S]*?${escapeRegex(COPILOT_BLOCK_END)}`);
+	if (blockRe.test(existing)) {
+		writeFile(absPath, existing.replace(blockRe, block));
+		return "regénéré";
+	}
+	const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+	writeFile(absPath, `${existing}${separator}${block}\n`);
+	return "créé";
+}
+function writeIfAbsent(absPath, label, contentFn, created, skipped) {
+	if (fileExists(absPath)) skipped.push(label);
+	else {
+		writeFile(absPath, contentFn());
+		created.push(label);
+	}
+}
+/** Garantit que chaque entrée listée est présente dans `.gitignore` (idempotent, crée le fichier si absent). */
+function ensureGitignoreEntries(entries, created, skipped) {
+	const gitignorePath = path.join(PROJECT_ROOT, ".gitignore");
+	const label = ".gitignore";
+	const existingLines = fileExists(gitignorePath) ? readFile(gitignorePath).split(/\r?\n/).map((l) => l.trim()) : [];
+	const missing = entries.filter((e) => !existingLines.includes(e));
+	if (!missing.length) {
+		skipped.push(`${label} (toutes les entrées codoc déjà présentes)`);
+		return;
+	}
+	const existing = fileExists(gitignorePath) ? readFile(gitignorePath) : "";
+	const block = `${!existing || existing.endsWith("\n") ? "" : "\n"}\n# Ajouté par codoc init\n${missing.join("\n")}\n`;
+	writeFile(gitignorePath, existing + block);
+	const action = fileExists(gitignorePath) && existing ? "mis à jour" : "créé";
+	created.push(`${label} (${action}, ajouté : ${missing.join(", ")})`);
+}
+//#endregion
+export { initAgentMdOnly, initCodoc };

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

@@ -0,0 +1,166 @@
+import { fileExists, isDirectory, readFile, 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 { ask, createRl, resolveConfirm, resolveValue } 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 { expandDocEntry, extractH1 } from "../shared/list-documents.js";
+import { EnvRegistry } from "../shared/confluence-client-registry.js";
+import { appendToDocsConfig, buildYamlEntry, removeDocsConfigEntries } from "../shared/codoc-yaml.js";
+import { pickEnvInteractive, selectEnvs } from "../shared/env-select.js";
+import { cleanDocPath } from "../sync/sync-entries.js";
+import { syncMatched, syncNew } from "../sync/sync-handlers.js";
+import { parsePageInput } from "../pull/parse-page-input.js";
+import path from "path";
+//#region src/use-cases/publish/publish.ts
+/** Environnement cible : flag → env de la config existante (si remplacement) → auto/prompt. */
+async function resolveEnv(rl, config, flagEnv, existingDoc) {
+	const key = flagEnv || existingDoc?.env;
+	return key ? selectEnvs(config, key)[0] : pickEnvInteractive(rl, config);
+}
+/** Lit la cible (fichier ou dossier), valide, et résout chaque information (flag → config → prompt). */
+async function collectPublishInput(rl, config, inputPath, flags) {
+	const raw = (inputPath || await ask(rl, "Chemin local de la doc (.md) ou du dossier :")).trim();
+	if (!raw) throw new Error("Chemin local requis.");
+	const relPath = toPosixPath(raw).replace(/^\.\//, "").replace(/\/+$/, "");
+	const abs = path.resolve(PROJECT_ROOT, relPath);
+	if (!fileExists(abs)) throw new Error(`Introuvable : ${relPath}`);
+	const isDir = isDirectory(abs);
+	if (!isDir && !relPath.endsWith(".md")) throw new Error("Le fichier doit être un .md (ou indique un dossier).");
+	const kind = isDir ? "folder" : "page";
+	const yamlPath = isDir ? `${relPath}/**` : relPath;
+	const existingDoc = config.docs.find((d) => cleanDocPath(d.path) === relPath);
+	if (existingDoc) log.warning1(`Une entrée codoc.yaml existe déjà pour "${existingDoc.path}".`);
+	const codocId = existingDoc?.codocId ?? generateRandomCodocId();
+	const env = await resolveEnv(rl, config, flags.env, existingDoc);
+	const rawParentPageId = await resolveValue(rl, {
+		flag: flags.parentPageId,
+		config: existingDoc?.confluence.parentPageId,
+		prompt: "URL ou ID de la page Confluence parente :",
+		promptDefault: env.defaultParentPageId ?? ""
+	});
+	const parentPageId = rawParentPageId ? parsePageInput(rawParentPageId).pageId : rawParentPageId;
+	let title;
+	if (!isDir) {
+		const h1 = extractH1(readFile(abs));
+		title = await resolveValue(rl, {
+			flag: flags.title,
+			config: existingDoc?.confluence.title,
+			prompt: "Titre de la page Confluence :",
+			promptDefault: h1 ?? path.basename(abs, ".md")
+		});
+	}
+	const syntheticDoc = {
+		codocId,
+		path: yamlPath,
+		maintainedIn: "code",
+		env: env.key,
+		generateSummary: existingDoc?.generateSummary ?? true,
+		confluence: {
+			title,
+			parentPageId: parentPageId || void 0
+		}
+	};
+	return {
+		env,
+		codocId,
+		existingDoc,
+		relPath,
+		yamlPath,
+		abs,
+		isDir,
+		parentPageId,
+		title,
+		entry: {
+			codocId,
+			kind,
+			path: yamlPath,
+			localPath: abs,
+			relPath,
+			maintainedIn: "code",
+			env,
+			parentPageId: parentPageId || void 0,
+			title
+		},
+		syntheticDoc
+	};
+}
+/** Écrit/met à jour l'entrée yaml correspondant à la publication. */
+async function persistYamlEntry(input) {
+	const yamlEntry = buildYamlEntry({
+		localPath: input.yamlPath,
+		title: input.title,
+		parentPageId: input.parentPageId,
+		maintainedIn: "code",
+		env: input.env.key,
+		codocId: input.codocId
+	});
+	if (input.existingDoc) {
+		await removeDocsConfigEntries([input.existingDoc.path]);
+		await appendToDocsConfig(yamlEntry);
+		log.success1("[UPDATED] codoc.yaml : entrée mise à jour");
+	} else {
+		await appendToDocsConfig(yamlEntry);
+		log.success1("[CREATED] codoc.yaml : entrée ajoutée");
+	}
+}
+/** Intégration dans codoc.yaml : flag `--in-config` → prompt unique en fin de commande, que la doc
+* soit déjà suivie (mise à jour) ou nouvelle (ajout). Sur refus, la publication a quand même eu lieu -
+* ni l'entrée yaml ni le lock ne sont touchés (publication ponctuelle et "utilitaire", volontairement
+* hors suivi : aucune trace ne subsiste pour comparer un futur republish par ID). Retourne la décision
+* pour que l'appelant sache s'il doit aussi persister le lock. */
+async function maybePersistYamlEntry(rl, input, inConfigFlag) {
+	const question = input.existingDoc ? "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: inConfigFlag,
+		question,
+		default: true
+	});
+	if (addToConfig) await persistYamlEntry(input);
+	else log.warning1("[SKIPPED] codoc.yaml et codoc.lock non modifiés - publication ponctuelle, hors suivi (pas de comparaison future par ID).");
+	return addToConfig;
+}
+async function publish(inputPath, flags = {}) {
+	const config = getCodocConfig();
+	const rl = createRl();
+	try {
+		log.startProcess("Publication local → Confluence");
+		const input = await collectPublishInput(rl, config, inputPath, flags);
+		const targets = await expandDocEntry(input.syntheticDoc, input.env);
+		if (!targets.length) throw new Error(`Aucun fichier .md à publier sous "${input.relPath}".`);
+		const state = loadPublishState();
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const ctx = {
+			config,
+			generatedAt: now,
+			registry: new EnvRegistry(),
+			envByKey: new Map(config.atlassian.environments.map((e) => [e.key, e])),
+			now,
+			confirm: () => Promise.resolve(true),
+			codeTargetsByCodocId: /* @__PURE__ */ new Map([[input.codocId, targets]]),
+			defaultBranch: await getDefaultBranch()
+		};
+		log.blank();
+		log.step1("Publication");
+		const lockHit = state.pages[input.codocId];
+		const published = lockHit ? await syncMatched(ctx, input.entry, lockHit) : await syncNew(ctx, input.entry);
+		if (!published) throw new Error(`Aucun fichier .md à publier sous "${input.relPath}".`);
+		if (await maybePersistYamlEntry(rl, input, flags.inConfig)) {
+			state.pages[input.codocId] = published;
+			state.lastPublished = state.lastPublished || now;
+			savePublishState(state);
+			log.success1("[UPDATED] codoc.lock mis à jour");
+		}
+		log.finalBanner("Publication terminée", {
+			"Doc locale": input.yamlPath,
+			Environnement: input.env.key,
+			...input.isDir ? { "Pages publiées": String(targets.filter((t) => !t.isFolder).length) } : { Page: input.title }
+		});
+	} finally {
+		rl.close();
+	}
+}
+//#endregion
+export { publish };

package/dist/use-cases/pull/parse-page-input.js

@@ -0,0 +1,22 @@
+//#region src/use-cases/pull/parse-page-input.ts
+function parsePageInput(rawInput) {
+	rawInput = rawInput.trim();
+	try {
+		const url = new URL(rawInput);
+		const match = url.pathname.match(/\/(pages|folder)\/(\d+)/);
+		if (!match) throw new Error("Aucun ID de page trouvé dans l'URL.");
+		return match[1] === "folder" ? {
+			pageId: match[2],
+			domain: url.hostname,
+			isFolder: true
+		} : {
+			pageId: match[2],
+			domain: url.hostname
+		};
+	} catch {
+		if (/^\d+$/.test(rawInput)) return { pageId: rawInput };
+		throw new Error(`Entrée invalide : "${rawInput}"\n  Attendu : un ID numérique ou une URL Confluence complète.`);
+	}
+}
+//#endregion
+export { parsePageInput };