codoc-cli 0.1.2

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import {enableCompileCache} from 'node:module'
+enableCompileCache()
+
+const {execute} = await import('@oclif/core')
+await execute({dir: import.meta.url})

package/dist/clients/confluence/clients/attachments-client.js

@@ -0,0 +1,74 @@
+import { wikiLink } from "../utils/confluence-url.js";
+import ky from "ky";
+//#region src/clients/confluence/clients/attachments-client.ts
+var ConfluenceAttachmentsClient = class {
+	http;
+	constructor(http) {
+		this.http = http;
+	}
+	/**
+	* Recherche une pièce jointe par son nom.
+	*/
+	async find(pageId, filename) {
+		const hit = (await this.http.v1.get(`content/${pageId}/child/attachment`, { searchParams: {
+			filename,
+			expand: "version"
+		} }).json()).results?.[0];
+		if (!hit) return;
+		if (!hit._links?.download) return;
+		return {
+			id: String(hit.id),
+			filename,
+			downloadPath: hit._links.download
+		};
+	}
+	/**
+	* Télécharge directement via _links.download (API v1).
+	*/
+	async downloadV1(downloadPath) {
+		return this.http.v1.get(wikiLink(this.http.baseUrl, downloadPath), {
+			prefixUrl: "",
+			headers: { Accept: "*/*" }
+		}).arrayBuffer();
+	}
+	/**
+	* Retourne le downloadLink signé (API v2).
+	*/
+	async getDownloadLink(attachmentId) {
+		return (await this.http.v2.get(`attachments/${attachmentId}`).json()).downloadLink;
+	}
+	/**
+	* Télécharge un attachment via un downloadLink v2 (absolu OU relatif au wiki).
+	* Le lien étant déjà pré-signé, on n'envoie pas d'en-tête d'authentification.
+	*/
+	async downloadV2(signedUrl) {
+		const url = signedUrl.startsWith("http") ? signedUrl : wikiLink(this.http.baseUrl, signedUrl);
+		return ky.get(url, { headers: { Accept: "*/*" } }).arrayBuffer();
+	}
+	/**
+	* Upload ou remplace
+	* une pièce jointe.
+	*/
+	async upload(pageId, filename, blob) {
+		const existing = await this.find(pageId, filename);
+		const form = new FormData();
+		form.append("file", blob, filename);
+		const endpoint = existing ? `content/${pageId}/child/attachment/${existing.id}/data` : `content/${pageId}/child/attachment`;
+		await this.http.v1.post(endpoint, {
+			body: form,
+			headers: { "X-Atlassian-Token": "no-check" }
+		});
+	}
+	/**
+	* Télécharge directement
+	* le texte d'un attachment.
+	*/
+	async downloadTextV1(downloadPath) {
+		return this.http.v1.get(wikiLink(this.http.baseUrl, downloadPath), {
+			prefixUrl: "",
+			headers: { Accept: "*/*" }
+		}).text();
+	}
+};
+//#endregion
+export { ConfluenceAttachmentsClient };

package/dist/clients/confluence/clients/folders-client.js

@@ -0,0 +1,111 @@
+import { titleVariants } from "../utils/confluence-url.js";
+//#region src/clients/confluence/clients/folders-client.ts
+/** Extrait le curseur de pagination de `_links.next` (API v2, pagination par curseur). */
+function extractCursor(nextLink) {
+	if (!nextLink) return void 0;
+	const query = nextLink.split("?")[1];
+	if (!query) return void 0;
+	return new URLSearchParams(query).get("cursor") ?? void 0;
+}
+/** Échappe une valeur pour l'insérer dans une clause CQL entre guillemets doubles. */
+function escapeCql(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+var ConfluenceFoldersClient = class {
+	http;
+	constructor(http) {
+		this.http = http;
+	}
+	async findByTitleUnderParent(parentId, title) {
+		for (const variant of titleVariants(title)) {
+			const cql = `type = folder and parent = ${parentId} and title = "${escapeCql(variant)}"`;
+			const results = (await this.http.v1.get("search", { searchParams: {
+				cql,
+				limit: 2
+			} }).json()).results ?? [];
+			if (results.length === 1) return {
+				id: String(results[0].content.id),
+				title: results[0].content.title
+			};
+		}
+	}
+	async childrenFolders(parentId) {
+		const results = [];
+		const cql = `type = folder and parent = ${parentId}`;
+		const limit = 100;
+		let start = 0;
+		for (let page = 0; page < 1e3; page++) {
+			const batch = (await this.http.v1.get("search", { searchParams: {
+				cql,
+				start,
+				limit
+			} }).json()).results ?? [];
+			results.push(...batch.map((r) => ({
+				id: String(r.content.id),
+				title: r.content.title
+			})));
+			if (batch.length < limit) break;
+			start += limit;
+		}
+		return results;
+	}
+	async exists(id) {
+		try {
+			await this.http.v2.get(`folders/${id}`);
+			return true;
+		} catch {}
+		return false;
+	}
+	async get(folderId) {
+		try {
+			const data = await this.http.v2.get(`folders/${folderId}`).json();
+			return {
+				id: String(data.id),
+				title: data.title,
+				parentId: data.parentId ? String(data.parentId) : void 0
+			};
+		} catch {
+			return;
+		}
+	}
+	/** Suit la pagination par curseur de l'API v2 - sinon les dossiers de plus de 250 enfants étaient tronqués silencieusement. */
+	async children(folderId) {
+		const results = [];
+		let cursor;
+		for (let page = 0; page < 1e3; page++) {
+			const data = await this.http.v2.get(`folders/${folderId}/direct-children`, { searchParams: cursor ? {
+				limit: 250,
+				cursor
+			} : { limit: 250 } }).json();
+			results.push(...(data.results ?? []).map((child) => ({
+				id: String(child.id),
+				title: child.title,
+				type: child.type
+			})));
+			cursor = extractCursor(data._links?.next);
+			if (!cursor) break;
+		}
+		return results;
+	}
+	async delete(folderId) {
+		await this.http.v2.delete(`folders/${folderId}`);
+	}
+	async create(title, spaceId, parentId) {
+		const payload = {
+			title,
+			spaceId
+		};
+		if (parentId) payload.parentId = String(parentId);
+		return this.http.v2.post("folders", { json: payload }).json();
+	}
+	async getSpaceId(spaceKey) {
+		const id = (await this.http.v2.get("spaces", { searchParams: {
+			keys: spaceKey,
+			limit: 1
+		} }).json()).results?.[0]?.id;
+		if (!id) throw new Error(`Space "${spaceKey}" introuvable.`);
+		return String(id);
+	}
+};
+//#endregion
+export { ConfluenceFoldersClient };

package/dist/clients/confluence/clients/pages-client.js

@@ -0,0 +1,128 @@
+import { titleVariants } from "../utils/confluence-url.js";
+//#region src/clients/confluence/clients/pages-client.ts
+var ConfluencePagesClient = class {
+	http;
+	configuration;
+	constructor(http, configuration) {
+		this.http = http;
+		this.configuration = configuration;
+	}
+	async exists(id) {
+		try {
+			await this.http.v1.get(`content/${id}`).json();
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async testConnection() {
+		try {
+			await this.http.v1.get("content", { searchParams: { limit: 1 } });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async fetchPage(pageId) {
+		const data = await this.http.v1.get(`content/${pageId}`, { searchParams: { expand: "body.storage,ancestors" } }).json();
+		const storageXml = data.body?.storage?.value ?? "";
+		const parent = data.ancestors?.[data.ancestors.length - 1];
+		return {
+			id: String(data.id),
+			title: data.title,
+			storageXml,
+			parentId: parent?.id ? parent.id : void 0,
+			hasImages: /ri:attachment/i.test(storageXml) || /ri:url/i.test(storageXml)
+		};
+	}
+	async fetchAncestors(pageId) {
+		const data = await this.http.v1.get(`content/${pageId}`, { searchParams: { expand: "ancestors" } }).json();
+		return [...(data.ancestors ?? []).map((a) => ({
+			id: String(a.id),
+			title: a.title ?? String(a.id)
+		})), {
+			id: String(data.id),
+			title: data.title
+		}];
+	}
+	/** Suit la pagination `start`/`limit` de l'API v1 - sinon les dossiers de plus de 200 pages étaient tronqués silencieusement. */
+	async fetchChildren(pageId) {
+		const results = [];
+		const limit = 200;
+		let start = 0;
+		for (let page = 0; page < 1e3; page++) {
+			const batch = (await this.http.v1.get(`content/${pageId}/child/page`, { searchParams: {
+				start,
+				limit,
+				expand: "version"
+			} }).json()).results ?? [];
+			results.push(...batch.map((p) => ({
+				id: String(p.id),
+				title: p.title
+			})));
+			if (batch.length < limit) break;
+			start += limit;
+		}
+		return results;
+	}
+	async findByTitle(title) {
+		for (const variant of titleVariants(title)) {
+			const data = await this.http.v1.get("content", { searchParams: {
+				title: variant,
+				spaceKey: this.configuration.spaceKey,
+				expand: "version"
+			} }).json();
+			if (data.results?.[0]) return data.results[0];
+		}
+	}
+	async getVersion(pageId) {
+		return this.http.v1.get(`content/${pageId}`, { searchParams: { expand: "version" } }).json();
+	}
+	async delete(pageId) {
+		await this.http.v1.delete(`content/${pageId}`);
+	}
+	/** Ajoute des labels à une page (n'écrase ni ne retire les existants - API additive). */
+	async addLabels(pageId, labels) {
+		if (!labels.length) return;
+		await this.http.v1.post(`content/${pageId}/label`, { json: labels.map((name) => ({
+			prefix: "global",
+			name
+		})) });
+	}
+	async create(title, storageContent, parentId) {
+		const effectiveParent = parentId ?? this.configuration.defaultParentPageId;
+		const payload = {
+			type: "page",
+			title,
+			space: { key: this.configuration.spaceKey },
+			body: { storage: {
+				value: storageContent,
+				representation: "storage"
+			} }
+		};
+		if (effectiveParent) payload.ancestors = [{ id: String(effectiveParent) }];
+		return this.http.v1.post("content", { json: payload }).json();
+	}
+	async update(pageId, title, storageContent, parentId) {
+		const version = await this.getVersion(pageId);
+		const effectiveParent = parentId ?? this.configuration.defaultParentPageId;
+		const payload = {
+			id: pageId,
+			type: "page",
+			title,
+			version: { number: version.version.number + 1 },
+			body: { storage: {
+				value: storageContent,
+				representation: "storage"
+			} }
+		};
+		if (effectiveParent) payload.ancestors = [{ id: String(effectiveParent) }];
+		return this.http.v1.put(`content/${pageId}`, { json: payload }).json();
+	}
+	async updateContent(pageId, storageContent) {
+		const page = await this.getVersion(pageId);
+		return this.update(pageId, page.title, storageContent);
+	}
+};
+//#endregion
+export { ConfluencePagesClient };

package/dist/clients/confluence/confluence-client.js

@@ -0,0 +1,44 @@
+import { wikiBase } from "./utils/confluence-url.js";
+import { ConfluenceAttachmentsClient } from "./clients/attachments-client.js";
+import { ConfluenceFoldersClient } from "./clients/folders-client.js";
+import { ConfluencePagesClient } from "./clients/pages-client.js";
+import ky from "ky";
+//#region src/clients/confluence/confluence-client.ts
+function createConfluenceClient(configuration) {
+	const http = createConfluenceHttp(configuration);
+	const attachments = new ConfluenceAttachmentsClient(http);
+	return {
+		pages: new ConfluencePagesClient(http, configuration),
+		folders: new ConfluenceFoldersClient(http),
+		attachments,
+		configuration,
+		foldersV2Unavailable: false
+	};
+}
+function basicAuth(username, apiToken) {
+	return `Basic ${Buffer.from(`${username}:${apiToken}`).toString("base64")}`;
+}
+const CONFLUENCE_TIMEOUT_MS = 6e4;
+function createConfluenceHttp(conf) {
+	return {
+		baseUrl: conf.baseUrl,
+		v1: ky.create({
+			prefixUrl: `${wikiBase(conf.baseUrl)}/rest/api`,
+			timeout: CONFLUENCE_TIMEOUT_MS,
+			headers: {
+				Authorization: basicAuth(conf.username, conf.apiToken),
+				Accept: "application/json"
+			}
+		}),
+		v2: ky.create({
+			prefixUrl: `${wikiBase(conf.baseUrl)}/api/v2`,
+			timeout: CONFLUENCE_TIMEOUT_MS,
+			headers: {
+				Authorization: basicAuth(conf.username, conf.apiToken),
+				Accept: "application/json"
+			}
+		})
+	};
+}
+//#endregion
+export { createConfluenceClient, createConfluenceHttp };

package/dist/clients/confluence/utils/confluence-url.js

@@ -0,0 +1,25 @@
+//#region src/clients/confluence/utils/confluence-url.ts
+function wikiBase(baseUrl) {
+	return `${baseUrl.replace(/\/$/, "")}/wiki`;
+}
+function wikiLink(baseUrl, link) {
+	if (link.startsWith("http")) return link;
+	const base = baseUrl.replace(/\/$/, "");
+	return link.startsWith("/wiki") ? `${base}${link}` : `${base}/wiki${link}`;
+}
+function pageUrl(baseUrl, spaceKey, pageId) {
+	return `${wikiBase(baseUrl)}/spaces/${spaceKey}/pages/${pageId}`;
+}
+/**
+* Variantes d'un titre à essayer lors d'une recherche : Confluence peut stocker
+* une apostrophe droite (') ou typographique (’) selon la source.
+*/
+function titleVariants(title) {
+	return [.../* @__PURE__ */ new Set([
+		title,
+		title.replace(/'/g, "’"),
+		title.replace(/’/g, "'")
+	])];
+}
+//#endregion
+export { pageUrl, titleVariants, wikiBase, wikiLink };

package/dist/clients/confluence/utils/confluence-util.js

@@ -0,0 +1,20 @@
+//#region src/clients/confluence/utils/confluence-util.ts
+/** Extrait un libellé d'erreur lisible (statut HTTP s'il existe, sinon message). */
+async function describeError(err) {
+	const e = err;
+	if (e?.response) {
+		const status = e.response.status;
+		let body = "";
+		try {
+			body = (await e.response.text()).slice(0, 120);
+		} catch {}
+		return `HTTP ${status}${body ? ` - ${body.replace(/\s+/g, " ").trim()}` : ""}`;
+	}
+	return e?.message ?? e?.name ?? String(err);
+}
+/** Type-guard : vrai si le téléchargement a réussi. */
+function isAttachmentDownload(r) {
+	return "data" in r;
+}
+//#endregion
+export { describeError, isAttachmentDownload };

package/dist/commands/init.js

@@ -0,0 +1,29 @@
+import { initAgentMdOnly, initCodoc } from "../use-cases/init/init.js";
+import { printAgentMdSummary, printInitSummary } from "../services/log/init-printer.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/init.ts
+var Init = class Init extends Command {
+	static 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).";
+	static examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> <%= command.id %> --agent-md"];
+	static flags = {
+		"agent-md": Flags.boolean({
+			default: false,
+			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."
+		}),
+		"agent-target": Flags.string({
+			options: ["agent", "copilot"],
+			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é."
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(Init);
+		if (flags["agent-md"]) {
+			printAgentMdSummary(await initAgentMdOnly(flags["agent-target"]));
+			return;
+		}
+		const { docRelPath, created, skipped, warnings } = initCodoc();
+		printInitSummary(created, skipped, warnings, docRelPath);
+	}
+};
+//#endregion
+export { Init as default };

package/dist/commands/publish.js

@@ -0,0 +1,34 @@
+import { confluenceEnvRequirements } from "../config/codoc-config-atlassian.js";
+import { loadRawConfig } from "../config/codoc-config-raw.js";
+import { ensureEnvVars } from "../services/ensure-env.js";
+import { publish } from "../use-cases/publish/publish.js";
+import { Args, Command, Flags } from "@oclif/core";
+//#region src/commands/publish.ts
+var Publish = class Publish extends Command {
+	static 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.";
+	static args = { path: Args.string({
+		description: "Chemin local relatif de la doc .md ou du dossier à publier",
+		required: false
+	}) };
+	static flags = {
+		env: Flags.string({ description: "Environnement Confluence cible (clé). Par défaut : celui de la config existante, sinon auto/prompt." }),
+		"in-config": Flags.boolean({
+			allowNo: true,
+			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."
+		}),
+		"parent-page-id": Flags.string({ description: "parentPageId Confluence cible. Par défaut : celui de la config existante ou defaultParentPageId de l’env." }),
+		title: Flags.string({ description: "Titre de la page Confluence (fichier unique uniquement). Par défaut : celui de la config existante, sinon le H1 du fichier." })
+	};
+	async run() {
+		const { args, flags } = await this.parse(Publish);
+		await ensureEnvVars(confluenceEnvRequirements(loadRawConfig().atlassian?.environments));
+		await publish(args.path ?? "", {
+			env: flags.env,
+			inConfig: flags["in-config"],
+			parentPageId: flags["parent-page-id"],
+			title: flags.title
+		});
+	}
+};
+//#endregion
+export { Publish as default };

package/dist/commands/pull.js

@@ -0,0 +1,54 @@
+import { confluenceEnvRequirements } from "../config/codoc-config-atlassian.js";
+import { loadRawConfig } from "../config/codoc-config-raw.js";
+import { ensureEnvVars } from "../services/ensure-env.js";
+import { pull } from "../use-cases/pull/pull.js";
+import { Args, Command, Flags } from "@oclif/core";
+//#region src/commands/pull.ts
+var Pull = class Pull extends Command {
+	static 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.";
+	static args = { page: Args.string({
+		description: "URL ou ID de la page Confluence à importer",
+		required: false
+	}) };
+	static flags = {
+		env: Flags.string({ description: "Environnement Confluence où chercher la page. Par défaut : déduit de l’URL, sinon auto/prompt." }),
+		"as-folder": Flags.boolean({
+			allowNo: true,
+			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."
+		}),
+		"keep-existing": Flags.boolean({
+			allowNo: true,
+			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."
+		}),
+		"in-config": Flags.boolean({
+			allowNo: true,
+			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."
+		}),
+		"local-path": Flags.string({ description: "Chemin local du fichier .md (page unique) ou du dossier de destination (import dossier)." }),
+		title: Flags.string({ description: "Titre de la page Confluence (page unique). Par défaut : celui de la config existante, sinon le titre Confluence." }),
+		"parent-page-id": Flags.string({ description: "parentPageId Confluence. Par défaut : celui de la config existante, sinon le parent réel de la page." }),
+		"maintained-in": Flags.string({
+			options: ["code", "confluence"],
+			description: "code → le .md local fait foi ; confluence → la page Confluence fait foi. Par défaut : confluence."
+		}),
+		"images-dir": Flags.string({ description: "Dossier local pour les images (\"\" pour désactiver). Par défaut : doc/img." })
+	};
+	async run() {
+		const { args, flags } = await this.parse(Pull);
+		await ensureEnvVars(confluenceEnvRequirements(loadRawConfig().atlassian?.environments));
+		await pull({
+			page: args.page,
+			env: flags.env,
+			asFolder: flags["as-folder"],
+			keepExisting: flags["keep-existing"],
+			inConfig: flags["in-config"],
+			localPath: flags["local-path"],
+			title: flags.title,
+			parentPageId: flags["parent-page-id"],
+			maintainedIn: flags["maintained-in"],
+			imagesDir: flags["images-dir"]
+		});
+	}
+};
+//#endregion
+export { Pull as default };

package/dist/commands/sync.js

@@ -0,0 +1,27 @@
+import { confluenceEnvRequirements } from "../config/codoc-config-atlassian.js";
+import { loadRawConfig } from "../config/codoc-config-raw.js";
+import { ensureEnvVars } from "../services/ensure-env.js";
+import { sync } from "../use-cases/sync/sync.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/sync.ts
+var Sync = class Sync extends Command {
+	static description = "Synchronise chaque doc locale et Confluence";
+	static flags = {
+		env: Flags.string({ description: "Ne synchronise que cet environnement Confluence (clé). Par défaut : tous." }),
+		confirm: Flags.boolean({
+			char: "f",
+			allowNo: true,
+			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."
+		})
+	};
+	async run() {
+		const { flags } = await this.parse(Sync);
+		await ensureEnvVars(confluenceEnvRequirements(loadRawConfig().atlassian?.environments));
+		await sync({
+			env: flags.env,
+			confirm: flags.confirm
+		});
+	}
+};
+//#endregion
+export { Sync as default };

package/dist/commands/tree.js

@@ -0,0 +1,17 @@
+import { confluenceEnvRequirements } from "../config/codoc-config-atlassian.js";
+import { loadRawConfig } from "../config/codoc-config-raw.js";
+import { ensureEnvVars } from "../services/ensure-env.js";
+import { printDocsTree } from "../use-cases/tree/docs-tree.js";
+import { Command, Flags } from "@oclif/core";
+//#region src/commands/tree.ts
+var Tree = class Tree extends Command {
+	static description = "Affiche l’arborescence des documents";
+	static flags = { env: Flags.string({ description: "N’affiche que cet environnement Confluence (clé). Par défaut : tous." }) };
+	async run() {
+		const { flags } = await this.parse(Tree);
+		await ensureEnvVars(confluenceEnvRequirements(loadRawConfig().atlassian?.environments));
+		await printDocsTree({ env: flags.env });
+	}
+};
+//#endregion
+export { Tree as default };