hdoc-tools 0.60.1 → 0.62.0

package/hdoc-module.js

@@ -1,1079 +1,1102 @@
-(() => {
-	const cheerio = require("cheerio");
-	const crypto = require("node:crypto");
-	const fs = require("node:fs");
-	const os = require("node:os");
-	const path = require("node:path");
-
-	const includesCache = {};
-
-	let retried = false;
-
-	const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-	// GitHub enforces a "secondary" (burst) rate limit on top of the hourly one:
-	// too many requests in a short window are rejected with 403/429 even when the
-	// hourly budget is intact. The contributor pull fires one call per file, so a
-	// fast run trips it. Historically `hdoc validate` got away with this only
-	// because verbose console output slowed the loop down between calls; the
-	// --quiet mode removed that incidental spacing and started hitting 403s.
-	// Throttle GitHub API calls to a fixed minimum interval so behaviour no longer
-	// depends on how chatty the console is.
-	let _last_github_call_at = 0;
-	const GITHUB_HOST = "api.github.com";
-	const GITHUB_MIN_INTERVAL_MS = 800;
-	// Never block the whole build waiting on a single rate-limited call.
-	const GITHUB_MAX_BACKOFF_MS = 60000;
-
-	// For a rate-limited response, work out how long to wait before retrying.
-	// Returns null when the response is NOT a retryable rate limit (e.g. a genuine
-	// 403 auth/forbidden), in which case the caller should give up immediately.
-	const rate_limit_wait_ms = (response) => {
-		if (response.status !== 403 && response.status !== 429) return null;
-		const retry_after = response.headers.get("retry-after");
-		if (retry_after !== null) {
-			const secs = Number(retry_after);
-			if (!Number.isNaN(secs)) return Math.max(0, secs * 1000);
-		}
-		const remaining = response.headers.get("x-ratelimit-remaining");
-		const reset = response.headers.get("x-ratelimit-reset");
-		if (remaining === "0" && reset !== null) {
-			const reset_ms = Number(reset) * 1000 - Date.now();
-			if (!Number.isNaN(reset_ms)) return Math.max(0, reset_ms);
-		}
-		// 403/429 with no rate-limit signal => auth/forbidden, not worth retrying.
-		return null;
-	};
-
-	// Wraps the built-in fetch() with automatic retry for transient errors.
-	// Retries up to maxRetries times when the server returns an HTTP error status
-	// >= 400, except for 401 (Unauthorized) and non-rate-limit 403 (Forbidden)
-	// which are auth failures that won't be resolved by retrying. GitHub
-	// rate-limit responses (403/429 carrying Retry-After or X-RateLimit-Reset) ARE
-	// retried after honouring the indicated wait. Network errors (where fetch
-	// itself throws) are also retried. Sets the module-level `retried` flag so
-	// callers can detect and log a success-after-retry message.
-	//
-	// Pass `timeoutMs` inside options to apply a per-attempt timeout. A fresh
-	// AbortSignal is created for every attempt so that a timed-out first attempt
-	// does not leave an already-aborted signal in place for the retries.
-	const fetchWithRetry = async (url, options = {}, maxRetries = 5) => {
-		const { timeoutMs, ...fetchOptions } = options;
-		const is_github = typeof url === "string" && url.includes(GITHUB_HOST);
-		let retryCount = 0;
-		while (true) {
-			// Space out GitHub API calls so a fast (quiet) run does not burst past
-			// the secondary rate limit. No effect on non-GitHub requests.
-			if (is_github) {
-				const since = Date.now() - _last_github_call_at;
-				if (since < GITHUB_MIN_INTERVAL_MS) {
-					await sleep(GITHUB_MIN_INTERVAL_MS - since);
-				}
-				_last_github_call_at = Date.now();
-			}
-			// Create a fresh signal for each attempt; reusing an already-aborted
-			// signal would cause every subsequent retry to abort immediately.
-			const attemptOptions = timeoutMs
-				? { ...fetchOptions, signal: AbortSignal.timeout(timeoutMs) }
-				: fetchOptions;
-			let response;
-			try {
-				response = await fetch(url, attemptOptions);
-			} catch (err) {
-				// Network-level error (DNS failure, connection refused, timeout, etc.)
-				retryCount++;
-				if (retryCount > maxRetries) throw err;
-				retried = true;
-				continue;
-			}
-			if (response.ok || response.status === 401) {
-				return response;
-			}
-			// 403/429: retry only when it is a rate limit we can wait out.
-			if (response.status === 403 || response.status === 429) {
-				const wait_ms = rate_limit_wait_ms(response);
-				if (wait_ms === null) return response; // auth/forbidden — give up
-				retryCount++;
-				if (retryCount > maxRetries) return response;
-				retried = true;
-				const backoff_ms = Math.min(wait_ms, GITHUB_MAX_BACKOFF_MS);
-				console.log(
-					`GitHub rate limit hit (HTTP ${response.status}) — waiting ${Math.round(backoff_ms / 1000)}s before retry ${retryCount}/${maxRetries}. Provide --git-token <PAT> to raise the limit.`,
-				);
-				await sleep(backoff_ms);
-				continue;
-			}
-			retryCount++;
-			if (retryCount > maxRetries) return response;
-			retried = true;
-		}
-	};
-
-	exports.fetchWithRetry = fetchWithRetry;
-
-	exports.content_type_for_ext = (ext) => {
-		switch (ext) {
-			case ".z":
-				return "application/x-compress";
-			case ".tgz":
-				return "application/x-compressed";
-			case ".gz":
-				return "application/x-gzip";
-			case ".zip":
-				return "application/x-zip-compressed";
-			case ".xml":
-				return "application/xml";
-			case ".bmp":
-				return "image/bmp";
-			case ".gif":
-				return "image/gif";
-			case ".jpg":
-				return "image/jpeg";
-			case ".png":
-				return "image/png";
-			case ".tiff":
-				return "image/tiff";
-			case ".ico":
-				return "image/x-icon";
-			case ".svg":
-				return "image/svg+xml";
-			case ".css":
-				return "text/css";
-			case ".htm":
-			case ".html":
-				return "text/html";
-			case ".txt":
-				return "text/plain";
-			case ".md":
-				return "text/plain";
-			case ".json":
-				return "application/json";
-			case ".js":
-				return "application/javascript";
-			default:
-				return "application/octet-stream";
-		}
-	};
-
-	exports.valid_url = (url) => {
-		const stringIsAValidUrl = (s) => {
-			try {
-				const url_obj = new URL(s);
-				return url_obj;
-			} catch (err) {
-				return false;
-			}
-		};
-		return stringIsAValidUrl(url);
-	};
-
-	exports.expand_variables = (text, docId = "") => {
-		let clean_text = text;
-		if (docId !== "") {
-			clean_text = clean_text.replaceAll("{{DOC_ID}}", docId);
-		}
-		clean_text = clean_text.replaceAll("{{BUILD_NUMBER}}", "0");
-
-		let build_date = new Date().toISOString();
-		build_date = build_date.replace("T", " ");
-		build_date = build_date.substring(0, 19);
-		clean_text = clean_text.replaceAll("{{BUILD_DATE}}", build_date);
-		return clean_text;
-	};
-
-	exports.process_includes = async (file_path, body, source_path) => {
-		const response = {
-			body: body,
-			found: 0,
-			success: 0,
-			failed: 0,
-			included: [],
-			errors: [],
-		};
-
-		// Search body for INCLUDEs
-		const regexp = /\[\[INCLUDE .*]]/g;
-		const body_array = [...response.body.matchAll(regexp)];
-
-		for (let i = 0; i < body_array.length; i++) {
-			response.found++;
-
-			// Extract include data from array
-			const include_value = body_array[i][0];
-
-			let link;
-			try {
-				link = include_value.split(" ")[1];
-				link = link.substring(0, link.length - 2);
-			} catch (e) {
-				response.failed++;
-				response.errors.push(
-					`Error parsing INCLUDE [${include_value}] from [${file_path}]: ${err}`,
-				);
-				continue;
-			}
-
-			if (
-				(link.startsWith("http://") || link.startsWith("https://")) &&
-				includesCache[link] !== undefined
-			) {
-				console.log(`Serving From Cache: ${link}`);
-				response.body = response.body.replace(
-					include_value,
-					includesCache[link],
-				);
-				response.success++;
-				continue;
-			}
-
-			// Validate link in INCLUDE
-			let file_content;
-			if (link.startsWith("http://") || link.startsWith("https://")) {
-				// Remote content to include
-				try {
-					new URL(link);
-				} catch (e) {
-					response.failed++;
-					response.errors.push(
-						`Error validating INCLUDE link [${link}] from [${file_path}]: ${e}`,
-					);
-					continue;
-				}
-
-				try {
-					const file_response = await fetchWithRetry(link);
-					if (retried) {
-						retried = false;
-						console.log("API call retry success!");
-					}
-					if (file_response.status === 200) {
-						file_content = await file_response.text();
-					} else {
-						throw `Unexpected Status ${file_response.status}`;
-					}
-				} catch (e) {
-					response.failed++;
-					response.errors.push(
-						`Error getting INCLUDE link content [${link}] from [${file_path}]: ${e}`,
-					);
-					continue;
-				}
-				console.log(`Included From Remote Source: ${link}`);
-			} else {
-				// Local content to include
-				try {
-					file_content = fs.readFileSync(path.join(source_path, link), "utf8");
-				} catch (e) {
-					response.failed++;
-					response.errors.push(
-						`Error getting INCLUDE file [${link}] from [${file_path}]: ${e}`,
-					);
-					continue;
-				}
-				console.log(`Included From Local Source: ${link}`);
-			}
-			response.success++;
-			includesCache[link] = file_content;
-			response.body = response.body.replace(include_value, file_content);
-		}
-		return response;
-	};
-
-	// Takes html, returns the first heading detected in the order provided in h_to_search
-	// Looks for h1 tags first, then hX, hY, hZ in order
-	exports.getFirstHTMLHeading = (html_body, h_to_search = ["h1"]) => {
-		const $ = cheerio.load(html_body);
-		for (const tag of h_to_search) {
-			const el = $(tag).first();
-			if (el.length > 0) return el;
-		}
-		return false;
-	};
-
-	const makeAnchorIdFriendly = (str) => {
-		return `hb-doc-anchor-${str // Add prefix
-			.toLowerCase() // Convert to lowercase
-			.trim() // Trim leading and trailing spaces
-			.replace(/[^a-z0-9\s-]/g, "") // Remove all non-alphanumeric characters except spaces and hyphens
-			.replace(/\s+/g, "-") // Replace spaces with hyphens
-			.replace(/-+/g, "-")}`; // Replace multiple hyphens with a single hyphen
-	};
-
-	// Processes HTML, wraps h2 and h3 tags and their content in divs with an id matching that of the h text
-	exports.wrapHContent = (htmlContent) => {
-		const $ = cheerio.load(htmlContent, { decodeEntities: false });
-		let result = '';
-		let inH2 = false;
-		let inH3 = false;
-
-		$('body').contents().each(function() {
-			const tagName = this.type === 'tag' ? this.name?.toLowerCase() : null;
-
-			if (tagName === 'h2') {
-				// Close open h3 (nested inside h2), then close h2
-				if (inH3) { result += '</div>'; inH3 = false; }
-				if (inH2) { result += '</div>'; inH2 = false; }
-				const anchorId = makeAnchorIdFriendly($(this).text().trim());
-				result += `<div id="${anchorId}">${$.html(this)}`;
-				inH2 = true;
-			} else if (tagName === 'h3') {
-				// Close previous h3 (it stays nested inside any open h2)
-				if (inH3) { result += '</div>'; inH3 = false; }
-				const anchorId = makeAnchorIdFriendly($(this).text().trim());
-				result += `<div id="${anchorId}">${$.html(this)}`;
-				inH3 = true;
-			} else {
-				result += $.html(this);
-			}
-		});
-
-		// Flush remaining open divs — h3 is nested inside h2 so close inner first
-		if (inH3) result += '</div>';
-		if (inH2) result += '</div>';
-
-		return `<html><head></head><body>${result}</body></html>`;
-	};
-
-	// Combined single-pass version of wrapHContent + getFirstHTMLHeading + get_html_read_time.
-	// Iterates body contents once to wrap h2/h3 divs AND extract the first matching heading text,
-	// first paragraph text, and reading-time estimate — avoiding 3 extra cheerio.load() calls.
-	exports.wrapAndExtract = (htmlContent, h_tags_to_search = ["h1"]) => {
-		const $ = cheerio.load(htmlContent, { decodeEntities: false });
-		let result = '';
-		let inH2 = false;
-		let inH3 = false;
-		let firstHeadingText = null;
-		let firstParagraphText = null;
-
-		$('body').contents().each(function() {
-			const tagName = this.type === 'tag' ? this.name?.toLowerCase() : null;
-			const text = tagName ? $(this).text().trim() : null;
-
-			if (firstHeadingText === null && tagName && h_tags_to_search.includes(tagName)) {
-				firstHeadingText = text;
-			}
-			if (firstParagraphText === null && tagName === 'p') {
-				firstParagraphText = text;
-			}
-
-			if (tagName === 'h2') {
-				if (inH3) { result += '</div>'; inH3 = false; }
-				if (inH2) { result += '</div>'; inH2 = false; }
-				result += `<div id="${makeAnchorIdFriendly(text)}">${$.html(this)}`;
-				inH2 = true;
-			} else if (tagName === 'h3') {
-				if (inH3) { result += '</div>'; inH3 = false; }
-				result += `<div id="${makeAnchorIdFriendly(text)}">${$.html(this)}`;
-				inH3 = true;
-			} else {
-				result += $.html(this);
-			}
-		});
-
-		if (inH3) result += '</div>';
-		if (inH2) result += '</div>';
-
-		// Word count re-uses the already-parsed DOM — no extra cheerio.load()
-		const bodyText = $("body").text();
-		const wordCount = bodyText.trim().split(/\s+/).filter(Boolean).length;
-		const readTimeMins = wordCount === 0 ? 0 : (Math.round(wordCount / 200) || 1);
-
-		return {
-			html: `<html><head></head><body>${result}</body></html>`,
-			firstHeadingText,
-			firstParagraphText,
-			readTimeMins,
-		};
-	};
-
-	exports.getIDDivs = (html_body) => {
-		const $ = cheerio.load(html_body, {
-			decodeEntities: false,
-		});
-
-		const divs = [];
-
-		$("div").each(function (i, element) {
-			if ($(this).attr("id")?.startsWith("hb-doc-anchor-")) {
-				divs.push({
-					id: $(this).attr("id"),
-					html: $(this).html(),
-					text: $(this).text(),
-				});
-			}
-		});
-		return divs;
-	};
-
-	exports.getHTMLFrontmatterHeader = (html_body) => {
-		const response = {
-			fm_header: "",
-			fm_properties: {},
-		};
-		const $ = cheerio.load(html_body, {
-			decodeEntities: false,
-		});
-		if (
-			$._root?.children &&
-			Array.isArray($._root.children) &&
-			$._root.children.length > 0
-		) {
-			for (const child of $._root.children) {
-				if (
-					child.type === "comment" &&
-					child.data &&
-					child.data.startsWith("[[FRONTMATTER")
-				) {
-					// We have a Frontmatter header - return each property in an array
-					const fm_properties = child.data.split(/\r?\n/);
-					for (let i = 0; i < fm_properties.length; i++) {
-						if (fm_properties[i].includes(":")) {
-							const property_details = fm_properties[i].split(/:(.*)/s);
-							if (property_details.length > 1) {
-								let prop_val = property_details[1].trim();
-								if (/^".*"$/.test(prop_val)) {
-									prop_val = prop_val.substring(1, prop_val.length - 1);
-								}
-								if (property_details[0].trim().toLowerCase() === "title") {
-									// Decode HTML entities in the title value: handles named entities
-									// (&amp; &lt; &gt; &quot; &#39; &apos;), decimal numeric refs (&#123;),
-									// and hex numeric refs (&#x7B;).
-									prop_val = prop_val.replace(/&amp;|&lt;|&gt;|&quot;|&#39;|&apos;|&#(\d+);|&#x([0-9a-fA-F]+);/g,
-									(m, dec, hex) => dec ? String.fromCharCode(+dec) : hex ? String.fromCharCode(parseInt(hex, 16)) : ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'", '&apos;': "'" })[m]);
-								}
-								response.fm_properties[
-									property_details[0].trim().toLowerCase()
-								] = prop_val;
-							}
-						}
-					}
-
-					// And return the header as a whole so it can be easily replaced
-					response.fm_header = child.data;
-				}
-			}
-		}
-
-		return response;
-	};
-
-	exports.truncate_string = (str, n, useWordBoundary) => {
-		if (str.length <= n) {
-			return str;
-		}
-		const subString = str.slice(0, n - 1);
-		return `${
-			useWordBoundary
-				? subString.slice(0, subString.lastIndexOf(" "))
-				: subString
-		}…`;
-	};
-
-	exports.html_to_text = (html, { baseElement } = {}) => {
-		const $ = cheerio.load(html, { decodeEntities: false });
-		if (baseElement) {
-			return $(baseElement).map((_i, el) => $(el).text()).get().join("\n");
-		}
-		return $("body").text();
-	};
-
-	exports.get_html_read_time = (html) => {
-		// Get word count
-		const text = exports.html_to_text(html);
-		const word_count = text.trim().split(/\s+/).filter(Boolean).length;
-		if (word_count === 0) return 0;
-
-		// Calculate the read time - divide the word count by 200
-		let read_time = Math.round(word_count / 200);
-		if (read_time === 0) read_time = 1;
-		return read_time;
-	};
-
-	exports.get_github_api_path = (repo, relative_path) => {
-		if (repo) {
-			const clean_repo = repo.endsWith("/") ? repo.slice(0, -1) : repo;
-			const github_paths = {};
-			github_paths.api_path = clean_repo.replace(
-				"https://github.com/",
-				"https://api.github.com/repos/",
-			);
-			github_paths.api_path += `/commits?path=${encodeURIComponent(
-				`/${relative_path.replace("\\\\", "/").replace("\\", "/")}`,
-			)}`;
-			github_paths.edit_path = `${repo}/blob/main/${relative_path.replace("\\\\", "/").replace("\\", "/")}`;
-			return github_paths;
-		}
-		return "";
-	};
-
-	const get_github_contributors_path = (repo) => {
-		const clean_repo = repo.endsWith("/") ? repo.slice(0, -1) : repo;
-		const github_paths = {};
-		github_paths.api_path = clean_repo.replace(
-			"https://github.com/",
-			"https://api.github.com/repos/",
-		);
-		github_paths.api_path += "/contributors";
-		return github_paths;
-	};
-
-	exports.get_github_repo_details = async (
-		github_url,
-		github_api_token,
-	) => {
-		const response = {
-			success: false,
-			error: "",
-			data: {},
-			private: false
-		};
-		const request_options = {
-			headers: {
-				"User-Agent": "HornbillDocsBuild",
-				"Cache-Control": "no-cache",
-				Host: "api.github.com",
-				Accept: "application/json",
-			},
-			timeout: 5000,
-		};
-		if (github_api_token !== "") {
-			request_options.headers.authorization = `Bearer ${github_api_token}`;
-		}
-
-		let github_response;
-		let github_data;
-		try {
-			github_response = await fetchWithRetry(github_url, {
-				headers: request_options.headers,
-				timeoutMs: 5000,
-			});
-			if (retried) {
-				retried = false;
-				console.log("API call retry success!");
-			}
-			github_data = await github_response.json();
-		} catch (err) {
-			// Network-level failure (fetchWithRetry re-throws after exhausting retries)
-			response.error = `Unexpected response from GitHub for [${github_url}:\n${JSON.stringify(err)}]`;
-			return response;
-		}
-		// fetch does not throw on HTTP errors — return early for unexpected status codes
-		if (github_response.status !== 200 && github_response.status !== 401 && github_response.status !== 403) {
-			response.error = new Error(`HTTP ${github_response.status}`);
-			return response;
-		}
-		if (github_response.status === 200) {
-			response.success = true;
-			response.data = github_data;
-			response.private = github_data.private;
-		} else {
-			// Is it a 404 or 403?
-			response.error = `${github_response.status} : ${github_data.message}`;
-		}
-		return response;
-	};
-
-	exports.get_github_contributors = async (
-		github_url,
-		github_api_token,
-		repo,
-	) => {
-		const response = {
-			success: false,
-			error: "",
-			contributors: [],
-			contributor_count: 0,
-			last_commit_date: "",
-		};
-		const contributors = {};
-
-		const request_options = {
-			headers: {
-				"User-Agent": "HornbillDocsBuild",
-				"Cache-Control": "no-cache",
-				Host: "api.github.com",
-				Accept: "application/json",
-			},
-			timeout: 5000,
-		};
-		if (github_api_token !== "") {
-			request_options.headers.authorization = `Bearer ${github_api_token}`;
-		}
-		let github_response;
-		let github_data;
-		try {
-			github_response = await fetchWithRetry(github_url, {
-				headers: request_options.headers,
-				timeoutMs: 5000,
-			});
-			if (retried) {
-				retried = false;
-				console.log("API call retry success!");
-			}
-			github_data = await github_response.json();
-		} catch (err) {
-			// Network-level failure (fetchWithRetry re-throws after exhausting retries)
-			response.error = `Unexpected response from GitHub for [${github_url}:\n${JSON.stringify(err)}]`;
-			return response;
-		}
-		// fetch does not throw on HTTP errors — return early for unexpected status codes
-		if (github_response.status !== 200 && github_response.status !== 401 && github_response.status !== 403) {
-			response.error = new Error(`HTTP ${github_response.status}`);
-			return response;
-		}
-		if (github_response.status === 200) {
-			response.success = true;
-			const commits = github_data;
-			for (const commit of commits) {
-				if (
-					commit.committer?.type &&
-					commit.committer.type.toLowerCase() === "user" &&
-					commit.committer.login.toLowerCase() !== "web-flow"
-				) {
-					if (!contributors[commit.committer.id]) {
-						response.contributor_count++;
-						contributors[commit.committer.id] = {
-							login: commit.committer.login,
-							avatar_url: commit.committer.avatar_url,
-							html_url: commit.committer.html_url,
-							name: commit.commit.committer.name,
-						};
-					}
-					if (response.last_commit_date !== "") {
-						const new_commit_date = new Date(commit.commit.committer.date);
-						const exist_commit_date = new Date(response.last_commit_date);
-						if (new_commit_date > exist_commit_date)
-							response.last_commit_date = commit.commit.committer.date;
-					} else {
-						response.last_commit_date = commit.commit.committer.date;
-					}
-				} else if (commit.author?.id) {
-					if (!contributors[commit.author.id]) {
-						response.contributor_count++;
-						contributors[commit.author.id] = {
-							login: commit.author.login,
-							avatar_url: commit.author.avatar_url,
-							html_url: commit.author.html_url,
-							name: commit.commit.author.name,
-						};
-					}
-					if (response.last_commit_date !== "") {
-						const new_commit_date = new Date(commit.commit.author.date);
-						const exist_commit_date = new Date(response.last_commit_date);
-						if (new_commit_date > exist_commit_date)
-							response.last_commit_date = commit.commit.author.date;
-					} else {
-						response.last_commit_date = commit.commit.author.date;
-					}
-				}
-			}
-			for (const key in contributors) {
-				if (Object.hasOwn(contributors, key)) {
-					response.contributors.push(contributors[key]);
-				}
-			}
-		} else if (github_response.status === 403) {
-			// Private repo, fine-grained permissions don't yet support getting commits without content, get list from meta permissions
-			const contrib_url = get_github_contributors_path(repo).api_path;
-			try {
-				github_response = await fetchWithRetry(contrib_url, {
-					headers: request_options.headers,
-					timeoutMs: 5000,
-				});
-				if (retried) {
-					retried = false;
-					console.log("API call retry success!");
-				}
-				github_data = await github_response.json();
-			} catch (err) {
-				// Network-level failure (fetchWithRetry re-throws after exhausting retries)
-				response.error = `Unexpected response from GitHub for [${contrib_url}:\n${JSON.stringify(err)}]`;
-				return response;
-			}
-			// fetch does not throw on HTTP errors — return early if fallback request failed
-			if (github_response.status !== 200) {
-				response.error = new Error(`HTTP ${github_response.status}`);
-				return response;
-			}
-			if (github_response.status === 200) {
-				response.success = true;
-				const commits = github_data;
-				for (const commit of commits) {
-					if (
-						commit.type &&
-						commit.type.toLowerCase() === "user" &&
-						commit.login.toLowerCase() !== "web-flow"
-					) {
-						if (!contributors[commit.id]) {
-							response.contributor_count++;
-							contributors[commit.id] = {
-								login: commit.login,
-								avatar_url: commit.avatar_url,
-								html_url: commit.html_url,
-								name: commit.name ? commit.name : commit.login,
-							};
-						}
-						if (
-							response.last_commit_date !== "" &&
-							response.last_commit_date !== "No Commit Date Available"
-						) {
-							const new_commit_date = new Date(commit.date);
-							const exist_commit_date = new Date(response.last_commit_date);
-							if (new_commit_date > exist_commit_date)
-								response.last_commit_date = commit.date;
-						} else {
-							response.last_commit_date = commit.date
-								? commit.date
-								: "No Commit Date Available";
-						}
-					}
-				}
-				for (const key in contributors) {
-					if (Object.hasOwn(contributors, key)) {
-						response.contributors.push(contributors[key]);
-					}
-				}
-			}
-		} else {
-			response.error = `Unexpected Status: ${github_response.status}.`;
-		}
-		return response;
-	};
-
-	exports.strip_drafts = (nav_items) => {
-		const return_nav = nav_items;
-		recurse_nav(return_nav);
-		return return_nav;
-	};
-
-	const recurse_nav = (nav_items) => {
-		for (const key in nav_items) {
-			if (nav_items[key].draft) {
-				nav_items.splice(key, 1);
-				recurse_nav(nav_items);
-			} else if (nav_items[key].items) {
-				recurse_nav(nav_items[key].items);
-			}
-		}
-	};
-
-	exports.build_breadcrumbs = (nav_items) => {
-		const response = {
-			bc: {},
-			errors: [],
-		};
-		const buildBreadcrumb = (items, parentLinks) => {
-			// Process parent links
-			let parentlink = true;
-			if (parentLinks.length > 0) {
-				if (parentLinks[0].link === undefined || parentLinks[0].link === "" || parentLinks[0].draft )
-					parentlink = false;
-
-				for (let i = 1; i < 10; i++) {
-					if (
-						parentLinks[i] &&
-						parentLinks[i].link === undefined &&
-						items.length > 0 &&
-						items[0].link
-					) {
-						parentLinks[i].link = items[0].link;
-					}
-				}
-			}
-
-			// Loop through items, build breadcrumb
-			for (let i = 0; i < items.length; i++) {
-				if (!items[i].text) {
-					response.errors.push(
-						`The following Nav Item is missing its text property: ${JSON.stringify(
-							items[i],
-						)}`,
-					);
-				}
-
-				if (!items[i].link && !items[i].items) {
-					response.errors.push(
-						`The following Nav Item has no link or items property: ${JSON.stringify(
-							items[i],
-						)}`,
-					);
-				}
-				const item = items[i];
-				if (!parentlink && item.link) {
-					parentLinks[0].link = item.link;
-					parentlink = true;
-				}
-				const { text, link, items: subItems } = item;
-				const breadcrumb = [...parentLinks, { text, link }];
-
-				if (link) {
-					response.bc[link] = breadcrumb;
-				}
-
-				if (subItems) {
-					buildBreadcrumb(subItems, breadcrumb);
-				}
-			}
-		};
-
-		buildBreadcrumb(nav_items, []);
-		return response;
-	};
-
-	exports.get_draft_links = (items, parent_is_draft = false) => {
-		let draft_links = [];
-
-		for (const item of items) {
-			// Check if this item is draft or if any parent was draft
-			const is_draft = parent_is_draft || item.draft;
-
-			// If the current item has a link and is draft (or parent is draft), add the link
-			if (is_draft && item.link) {
-				draft_links.push(item.link);
-			}
-
-			// If the current item has nested items, recursively check them
-			if (item.items) {
-				draft_links = draft_links.concat(this.get_draft_links(item.items, is_draft));
-			}
-		}
-		return draft_links;
-	};
-
-	exports.load_product_families = async () => {
-		const response = {
-			success: false,
-			prod_families: {},
-			prods_supported: [],
-			errors: "",
-		};
-		const prod_families_url = "https://docs.hornbill.com/_books/products.json";
-		for (let i = 1; i < 4; i++) {
-			try {
-				const prods = await fetch(prod_families_url, {
-					signal: AbortSignal.timeout(5000),
-				});
-				if (prods.status === 200) {
-					response.prod_families = await prods.json();
-					response.prods_supported = [];
-					for (let i = 0; i < response.prod_families.products.length; i++) {
-						response.prods_supported.push(
-							response.prod_families.products[i].id,
-						);
-					}
-					response.success = true;
-					break;
-				}
-				throw `Unexpected status - ${prods.status} ${prods.statusText}`;
-			} catch (e) {
-				if (response.errors === "")
-					response.errors = `Request to ${prod_families_url} failed:`;
-				response.errors += `\nAttempt ${i} - Error returning product families: ${e}`;
-				// Wait 2 seconds and try again
-				await new Promise((r) => setTimeout(r, 2000));
-			}
-		}
-		return response;
-	};
-
-	// Recursively walks a directory tree and invokes fileCallback(element) for each file.
-	// Mirrors the dree.scan API so existing options objects and callbacks work unchanged.
-	// Supported options:
-	//   extensions            - array of extensions to include (e.g. ["md","html"]); omit for all files
-	//   hash                  - compute MD5 hash of each file's content and set element.hash
-	//   normalize             - convert backslashes to forward slashes in all paths
-	//   sorted                - sort directory entries alphabetically before recursing
-	//   sizeInBytes / size    - include file size as element.sizeInBytes
-	//   stat                  - include the fs.Stats object as element.stat
-	//   depth                 - maximum recursion depth (default: unlimited)
-	//   excludeEmptyDirectories - skip directories that contain no entries
-	//   symbolicLinks         - set false to skip symbolic links (default: include them)
-	// Each element passed to the callback has: name, path (absolute), relativePath, and any
-	// optional fields enabled above.
-	exports.scan_dir = (dirPath, opts = {}, fileCallback) => {
-		const extensions = opts.extensions ? new Set(opts.extensions.map((e) => e.toLowerCase())) : null;
-		const maxDepth = opts.depth !== undefined ? opts.depth : Infinity;
-
-		const walk = (currentPath, depth) => {
-			if (depth > maxDepth) return;
-			let entries;
-			try {
-				entries = fs.readdirSync(currentPath, { withFileTypes: true });
-			} catch (_) { return; }
-
-			if (opts.sorted) entries = entries.slice().sort((a, b) => a.name.localeCompare(b.name));
-
-			for (const entry of entries) {
-				if (opts.symbolicLinks === false && entry.isSymbolicLink()) continue;
-				const fullPath = path.join(currentPath, entry.name);
-
-				if (entry.isDirectory()) {
-					if (opts.excludeEmptyDirectories) {
-						try { if (fs.readdirSync(fullPath).length === 0) continue; } catch (_) { continue; }
-					}
-					walk(fullPath, depth + 1);
-				} else if (entry.isFile()) {
-					const ext = path.extname(entry.name).slice(1).toLowerCase();
-					if (extensions && !extensions.has(ext)) continue;
-
-					const absPath = opts.normalize ? fullPath.replaceAll("\\", "/") : fullPath;
-					const relPath = opts.normalize
-						? path.relative(dirPath, fullPath).replaceAll("\\", "/")
-						: path.relative(dirPath, fullPath);
-
-					const element = { name: entry.name, path: absPath, relativePath: relPath, extension: ext };
-
-					if (opts.sizeInBytes || opts.size || opts.stat) {
-						const stat = fs.statSync(fullPath);
-						if (opts.sizeInBytes || opts.size) element.sizeInBytes = stat.size;
-						if (opts.stat) element.stat = stat;
-					}
-
-					if (opts.hash) {
-						element.hash = crypto.createHash("md5").update(fs.readFileSync(fullPath)).digest("hex");
-					}
-
-					fileCallback(element);
-				}
-			}
-		};
-
-		walk(dirPath, 1);
-	};
-
-	// Resolves the true on-disk casing of a file path by walking each path segment
-	// and doing a case-insensitive match against the actual directory listing.
-	// This is important on case-sensitive filesystems (Linux) to catch casing mismatches
-	// that would silently pass on macOS/Windows but break in CI or production.
-	// On Windows, the drive letter is normalised to uppercase and backslash delimiters are used.
-	exports.true_case_path_sync = (filePath) => {
-		const isWin = process.platform === "win32";
-		const delim = isWin ? "\\" : "/";
-		filePath = path.normalize(filePath);
-		const segments = filePath.split(delim).filter((s) => s !== "");
-		let base = path.isAbsolute(filePath) ? (isWin ? segments.shift().toUpperCase() : "") : process.cwd();
-		return segments.reduce((realPath, seg) => {
-			const entries = fs.readdirSync(realPath + delim);
-			// Escape any regex special chars in the segment name before building the pattern
-			const re = new RegExp(`^${seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "i");
-			const match = entries.find((e) => re.test(e));
-			if (!match) throw new Error(`true_case_path_sync: no match for "${seg}" in "${realPath}"`);
-			return realPath + delim + match;
-		}, base);
-	};
-
-	// Creates an empty temporary file with a random name and optional file extension suffix
-	// (e.g. { postfix: ".mmd" }). Returns an object with:
-	//   name           - the absolute path to the temp file
-	//   removeCallback - call this to delete the file when done; errors are silently ignored
-	//                    so it is safe to call even if the file was already cleaned up.
-	exports.tmp_file_sync = (opts = {}) => {
-		const name = path.join(os.tmpdir(), `hdoc-${crypto.randomBytes(8).toString("hex")}${opts.postfix || ""}`);
-		fs.closeSync(fs.openSync(name, "w"));
-		return { name, removeCallback: () => { try { fs.unlinkSync(name); } catch (_) {} } };
-	};
-
-	// Parses a YAML string into a plain JS object. Designed for markdown frontmatter,
-	// which is always simple: scalar key/value pairs, block arrays (- item), and inline
-	// arrays ([a, b, c]). Does not support anchors, multi-line strings, or nested objects.
-	// parseVal handles type coercion: booleans, null, integers, floats, quoted strings,
-	// inline arrays, and plain strings (returned as-is).
-	exports.parse_yaml = (str) => {
-		const parseVal = (v) => {
-			if (v === "true") return true;
-			if (v === "false") return false;
-			if (v === "null" || v === "~") return null;
-			if (/^-?\d+$/.test(v)) return parseInt(v, 10);
-			if (/^-?\d*\.\d+$/.test(v)) return parseFloat(v);
-			if (/^['"].*['"]$/.test(v)) return v.slice(1, -1); // strip surrounding quotes
-			if (v.startsWith("[") && v.endsWith("]")) return v.slice(1, -1).split(",").map(i => parseVal(i.trim()));
-			return v;
-		};
-		const result = {};
-		let currentKey = null;
-		for (const line of str.split("\n")) {
-			if (!line.trim() || /^\s*#/.test(line)) continue;
-			// Block array item (indented dash): append to the current key's array
-			const arrMatch = line.match(/^\s+-\s+(.+)$/);
-			if (arrMatch && currentKey) {
-				if (!Array.isArray(result[currentKey])) result[currentKey] = [];
-				result[currentKey].push(parseVal(arrMatch[1].trim()));
-				continue;
-			}
-			// key: value pair — value may be empty (e.g. start of a block array)
-			const kvMatch = line.match(/^([^:]+):\s*(.*)$/);
-			if (kvMatch) {
-				currentKey = kvMatch[1].trim();
-				result[currentKey] = kvMatch[2].trim() ? parseVal(kvMatch[2].trim()) : null;
-			}
-		}
-		return result;
-	};
-
-	// Pretty-prints an XML string with configurable indentation and line endings.
-	// Tokenises the input using a regex that preserves CDATA sections, comments, and
-	// processing instructions as atomic units so their content is never re-indented.
-	// Options:
-	//   indentation   - string to use per indent level (default: two spaces)
-	//   lineSeparator - line ending to use (default: "\n")
-	//   collapseContent - when true (default), elements that contain only a single text
-	//                     node are kept on one line: <tag>text</tag> rather than split
-	//                     across three lines. Uses one-token lookahead to detect this.
-	exports.xml_format = (xml, opts = {}) => {
-		const ind = opts.indentation || "  ";
-		const sep = opts.lineSeparator || "\n";
-		const collapse = opts.collapseContent !== false;
-		// Match CDATA, comments, PIs, tags, and text nodes as individual tokens
-		const tokens = xml.trim().match(/(<!\[CDATA\[[\s\S]*?\]\]>|<!--[\s\S]*?-->|<[^>]+>|[^<]+)/g) || [];
-		let depth = 0;
-		let out = "";
-		for (let i = 0; i < tokens.length; i++) {
-			const t = tokens[i].trim();
-			if (!t) continue;
-			const isClose = t.startsWith("</");
-			const isSelf = t.startsWith("<") && t.endsWith("/>") && !t.startsWith("<?");
-			const isSpecial = t.startsWith("<?") || t.startsWith("<!--") || t.startsWith("<![");
-			const isOpen = t.startsWith("<") && !isClose && !isSelf && !isSpecial;
-			if (isClose) {
-				depth = Math.max(0, depth - 1);
-				out += ind.repeat(depth) + t + sep;
-			} else if (isSelf || isSpecial) {
-				out += ind.repeat(depth) + t + sep;
-			} else if (isOpen) {
-				// Collapse: if the very next token is text and the one after is the closing tag,
-				// emit all three on one line and skip those two tokens.
-				if (collapse && i + 2 < tokens.length) {
-					const nextTxt = tokens[i + 1] ? tokens[i + 1].trim() : "";
-					const nextClose = tokens[i + 2] ? tokens[i + 2].trim() : "";
-					if (nextTxt && !nextTxt.startsWith("<") && nextClose.startsWith("</")) {
-						out += ind.repeat(depth) + t + nextTxt + nextClose + sep;
-						i += 2;
-						continue;
-					}
-				}
-				out += ind.repeat(depth) + t + sep;
-				depth++;
-			} else {
-				// Plain text node
-				out += ind.repeat(depth) + t + sep;
-			}
-		}
-		return out.trimEnd();
-	};
-
-	exports.find_string_in_string = (fileContent, searchString) => {
-		const lines = fileContent.split('\n');
-	  
-		for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
-		  const columnNumber = lines[lineNumber].indexOf(searchString);
-	  
-		  if (columnNumber !== -1) {
-			// Return 1-based line and column numbers
-			return { line: lineNumber + 1, column: columnNumber + 1 };
-		  }
-		}
-	  
-		// If not found, return null
-		return null;
-	  }
-})();
+(() => {
+	const cheerio = require("cheerio");
+	const crypto = require("node:crypto");
+	const fs = require("node:fs");
+	const os = require("node:os");
+	const path = require("node:path");
+
+	const includesCache = {};
+
+	let retried = false;
+
+	const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+	// GitHub enforces a "secondary" (burst) rate limit on top of the hourly one:
+	// too many requests in a short window are rejected with 403/429 even when the
+	// hourly budget is intact. The contributor pull fires one call per file, so a
+	// fast run trips it. Historically `hdoc validate` got away with this only
+	// because verbose console output slowed the loop down between calls; the
+	// --quiet mode removed that incidental spacing and started hitting 403s.
+	// Throttle GitHub API calls to a fixed minimum interval so behaviour no longer
+	// depends on how chatty the console is.
+	let _last_github_call_at = 0;
+	const GITHUB_HOST = "api.github.com";
+	const GITHUB_MIN_INTERVAL_MS = 800;
+	// Never block the whole build waiting on a single rate-limited call.
+	const GITHUB_MAX_BACKOFF_MS = 60000;
+
+	// For a rate-limited response, work out how long to wait before retrying.
+	// Returns null when the response is NOT a retryable rate limit (e.g. a genuine
+	// 403 auth/forbidden), in which case the caller should give up immediately.
+	const rate_limit_wait_ms = (response) => {
+		if (response.status !== 403 && response.status !== 429) return null;
+		const retry_after = response.headers.get("retry-after");
+		if (retry_after !== null) {
+			const secs = Number(retry_after);
+			if (!Number.isNaN(secs)) return Math.max(0, secs * 1000);
+		}
+		const remaining = response.headers.get("x-ratelimit-remaining");
+		const reset = response.headers.get("x-ratelimit-reset");
+		if (remaining === "0" && reset !== null) {
+			const reset_ms = Number(reset) * 1000 - Date.now();
+			if (!Number.isNaN(reset_ms)) return Math.max(0, reset_ms);
+		}
+		// 403/429 with no rate-limit signal => auth/forbidden, not worth retrying.
+		return null;
+	};
+
+	// Wraps the built-in fetch() with automatic retry for transient errors.
+	// Retries up to maxRetries times when the server returns an HTTP error status
+	// >= 400, except for 401 (Unauthorized) and non-rate-limit 403 (Forbidden)
+	// which are auth failures that won't be resolved by retrying. GitHub
+	// rate-limit responses (403/429 carrying Retry-After or X-RateLimit-Reset) ARE
+	// retried after honouring the indicated wait. Network errors (where fetch
+	// itself throws) are also retried. Sets the module-level `retried` flag so
+	// callers can detect and log a success-after-retry message.
+	//
+	// Pass `timeoutMs` inside options to apply a per-attempt timeout. A fresh
+	// AbortSignal is created for every attempt so that a timed-out first attempt
+	// does not leave an already-aborted signal in place for the retries.
+	const fetchWithRetry = async (url, options = {}, maxRetries = 5) => {
+		const { timeoutMs, ...fetchOptions } = options;
+		const is_github = typeof url === "string" && url.includes(GITHUB_HOST);
+		let retryCount = 0;
+		while (true) {
+			// Space out GitHub API calls so a fast (quiet) run does not burst past
+			// the secondary rate limit. No effect on non-GitHub requests.
+			if (is_github) {
+				const since = Date.now() - _last_github_call_at;
+				if (since < GITHUB_MIN_INTERVAL_MS) {
+					await sleep(GITHUB_MIN_INTERVAL_MS - since);
+				}
+				_last_github_call_at = Date.now();
+			}
+			// Create a fresh signal for each attempt; reusing an already-aborted
+			// signal would cause every subsequent retry to abort immediately.
+			const attemptOptions = timeoutMs
+				? { ...fetchOptions, signal: AbortSignal.timeout(timeoutMs) }
+				: fetchOptions;
+			let response;
+			try {
+				response = await fetch(url, attemptOptions);
+			} catch (err) {
+				// Network-level error (DNS failure, connection refused, timeout, etc.)
+				retryCount++;
+				if (retryCount > maxRetries) throw err;
+				retried = true;
+				continue;
+			}
+			if (response.ok || response.status === 401) {
+				return response;
+			}
+			// 403/429: retry only when it is a rate limit we can wait out.
+			if (response.status === 403 || response.status === 429) {
+				const wait_ms = rate_limit_wait_ms(response);
+				if (wait_ms === null) return response; // auth/forbidden — give up
+				retryCount++;
+				if (retryCount > maxRetries) return response;
+				retried = true;
+				const backoff_ms = Math.min(wait_ms, GITHUB_MAX_BACKOFF_MS);
+				console.log(
+					`GitHub rate limit hit (HTTP ${response.status}) — waiting ${Math.round(backoff_ms / 1000)}s before retry ${retryCount}/${maxRetries}. Provide --git-token <PAT> to raise the limit.`,
+				);
+				await sleep(backoff_ms);
+				continue;
+			}
+			retryCount++;
+			if (retryCount > maxRetries) return response;
+			retried = true;
+		}
+	};
+
+	exports.fetchWithRetry = fetchWithRetry;
+
+	exports.content_type_for_ext = (ext) => {
+		switch (ext) {
+			case ".z":
+				return "application/x-compress";
+			case ".tgz":
+				return "application/x-compressed";
+			case ".gz":
+				return "application/x-gzip";
+			case ".zip":
+				return "application/x-zip-compressed";
+			case ".xml":
+				return "application/xml";
+			case ".bmp":
+				return "image/bmp";
+			case ".gif":
+				return "image/gif";
+			case ".jpg":
+				return "image/jpeg";
+			case ".png":
+				return "image/png";
+			case ".tiff":
+				return "image/tiff";
+			case ".ico":
+				return "image/x-icon";
+			case ".svg":
+				return "image/svg+xml";
+			case ".css":
+				return "text/css";
+			case ".htm":
+			case ".html":
+				return "text/html";
+			case ".txt":
+				return "text/plain";
+			case ".md":
+				return "text/plain";
+			case ".json":
+				return "application/json";
+			case ".js":
+				return "application/javascript";
+			default:
+				return "application/octet-stream";
+		}
+	};
+
+	exports.valid_url = (url) => {
+		const stringIsAValidUrl = (s) => {
+			try {
+				const url_obj = new URL(s);
+				return url_obj;
+			} catch (err) {
+				return false;
+			}
+		};
+		return stringIsAValidUrl(url);
+	};
+
+	exports.expand_variables = (text, docId = "") => {
+		let clean_text = text;
+		if (docId !== "") {
+			clean_text = clean_text.replaceAll("{{DOC_ID}}", docId);
+		}
+		clean_text = clean_text.replaceAll("{{BUILD_NUMBER}}", "0");
+
+		let build_date = new Date().toISOString();
+		build_date = build_date.replace("T", " ");
+		build_date = build_date.substring(0, 19);
+		clean_text = clean_text.replaceAll("{{BUILD_DATE}}", build_date);
+		return clean_text;
+	};
+
+	exports.process_includes = async (file_path, body, source_path) => {
+		const response = {
+			body: body,
+			found: 0,
+			success: 0,
+			failed: 0,
+			included: [],
+			errors: [],
+		};
+
+		// Search body for INCLUDEs
+		const regexp = /\[\[INCLUDE .*]]/g;
+		const body_array = [...response.body.matchAll(regexp)];
+
+		for (let i = 0; i < body_array.length; i++) {
+			response.found++;
+
+			// Extract include data from array
+			const include_value = body_array[i][0];
+
+			let link;
+			try {
+				link = include_value.split(" ")[1];
+				link = link.substring(0, link.length - 2);
+			} catch (e) {
+				response.failed++;
+				response.errors.push(
+					`Error parsing INCLUDE [${include_value}] from [${file_path}]: ${err}`,
+				);
+				continue;
+			}
+
+			if (
+				(link.startsWith("http://") || link.startsWith("https://")) &&
+				includesCache[link] !== undefined
+			) {
+				console.log(`Serving From Cache: ${link}`);
+				response.body = response.body.replace(
+					include_value,
+					includesCache[link],
+				);
+				response.success++;
+				continue;
+			}
+
+			// Validate link in INCLUDE
+			let file_content;
+			if (link.startsWith("http://") || link.startsWith("https://")) {
+				// Remote content to include
+				try {
+					new URL(link);
+				} catch (e) {
+					response.failed++;
+					response.errors.push(
+						`Error validating INCLUDE link [${link}] from [${file_path}]: ${e}`,
+					);
+					continue;
+				}
+
+				try {
+					const file_response = await fetchWithRetry(link);
+					if (retried) {
+						retried = false;
+						console.log("API call retry success!");
+					}
+					if (file_response.status === 200) {
+						file_content = await file_response.text();
+					} else {
+						throw `Unexpected Status ${file_response.status}`;
+					}
+				} catch (e) {
+					response.failed++;
+					response.errors.push(
+						`Error getting INCLUDE link content [${link}] from [${file_path}]: ${e}`,
+					);
+					continue;
+				}
+				console.log(`Included From Remote Source: ${link}`);
+			} else {
+				// Local content to include
+				try {
+					file_content = fs.readFileSync(path.join(source_path, link), "utf8");
+				} catch (e) {
+					response.failed++;
+					response.errors.push(
+						`Error getting INCLUDE file [${link}] from [${file_path}]: ${e}`,
+					);
+					continue;
+				}
+				console.log(`Included From Local Source: ${link}`);
+			}
+			response.success++;
+			includesCache[link] = file_content;
+			response.body = response.body.replace(include_value, file_content);
+		}
+		return response;
+	};
+
+	// Takes html, returns the first heading detected in the order provided in h_to_search
+	// Looks for h1 tags first, then hX, hY, hZ in order
+	exports.getFirstHTMLHeading = (html_body, h_to_search = ["h1"]) => {
+		const $ = cheerio.load(html_body);
+		for (const tag of h_to_search) {
+			const el = $(tag).first();
+			if (el.length > 0) return el;
+		}
+		return false;
+	};
+
+	// Exported for inter-book anchor validation — the anchor id derivation MUST
+	// stay identical between build-time wrapping and cross-book link checks.
+	exports.makeAnchorIdFriendly = (str) => makeAnchorIdFriendly(str);
+
+	const makeAnchorIdFriendly = (str) => {
+		return `hb-doc-anchor-${str // Add prefix
+			.toLowerCase() // Convert to lowercase
+			.trim() // Trim leading and trailing spaces
+			.replace(/[^a-z0-9\s-]/g, "") // Remove all non-alphanumeric characters except spaces and hyphens
+			.replace(/\s+/g, "-") // Replace spaces with hyphens
+			.replace(/-+/g, "-")}`; // Replace multiple hyphens with a single hyphen
+	};
+
+	// Processes HTML, wraps h2 and h3 tags and their content in divs with an id matching that of the h text
+	exports.wrapHContent = (htmlContent) => {
+		const $ = cheerio.load(htmlContent, { decodeEntities: false });
+		let result = '';
+		let inH2 = false;
+		let inH3 = false;
+
+		$('body').contents().each(function() {
+			const tagName = this.type === 'tag' ? this.name?.toLowerCase() : null;
+
+			if (tagName === 'h2') {
+				// Close open h3 (nested inside h2), then close h2
+				if (inH3) { result += '</div>'; inH3 = false; }
+				if (inH2) { result += '</div>'; inH2 = false; }
+				const anchorId = makeAnchorIdFriendly($(this).text().trim());
+				result += `<div id="${anchorId}">${$.html(this)}`;
+				inH2 = true;
+			} else if (tagName === 'h3') {
+				// Close previous h3 (it stays nested inside any open h2)
+				if (inH3) { result += '</div>'; inH3 = false; }
+				const anchorId = makeAnchorIdFriendly($(this).text().trim());
+				result += `<div id="${anchorId}">${$.html(this)}`;
+				inH3 = true;
+			} else {
+				result += $.html(this);
+			}
+		});
+
+		// Flush remaining open divs — h3 is nested inside h2 so close inner first
+		if (inH3) result += '</div>';
+		if (inH2) result += '</div>';
+
+		return `<html><head></head><body>${result}</body></html>`;
+	};
+
+	// Combined single-pass version of wrapHContent + getFirstHTMLHeading + get_html_read_time.
+	// Iterates body contents once to wrap h2/h3 divs AND extract the first matching heading text,
+	// first paragraph text, and reading-time estimate — avoiding 3 extra cheerio.load() calls.
+	exports.wrapAndExtract = (htmlContent, h_tags_to_search = ["h1"]) => {
+		const $ = cheerio.load(htmlContent, { decodeEntities: false });
+		let result = '';
+		let inH2 = false;
+		let inH3 = false;
+		let firstHeadingText = null;
+		let firstParagraphText = null;
+
+		$('body').contents().each(function() {
+			const tagName = this.type === 'tag' ? this.name?.toLowerCase() : null;
+			const text = tagName ? $(this).text().trim() : null;
+
+			if (firstHeadingText === null && tagName && h_tags_to_search.includes(tagName)) {
+				firstHeadingText = text;
+			}
+			if (firstParagraphText === null && tagName === 'p') {
+				firstParagraphText = text;
+			}
+
+			if (tagName === 'h2') {
+				if (inH3) { result += '</div>'; inH3 = false; }
+				if (inH2) { result += '</div>'; inH2 = false; }
+				result += `<div id="${makeAnchorIdFriendly(text)}">${$.html(this)}`;
+				inH2 = true;
+			} else if (tagName === 'h3') {
+				if (inH3) { result += '</div>'; inH3 = false; }
+				result += `<div id="${makeAnchorIdFriendly(text)}">${$.html(this)}`;
+				inH3 = true;
+			} else {
+				result += $.html(this);
+			}
+		});
+
+		if (inH3) result += '</div>';
+		if (inH2) result += '</div>';
+
+		// Word count re-uses the already-parsed DOM — no extra cheerio.load()
+		const bodyText = $("body").text();
+		const wordCount = bodyText.trim().split(/\s+/).filter(Boolean).length;
+		const readTimeMins = wordCount === 0 ? 0 : (Math.round(wordCount / 200) || 1);
+
+		return {
+			html: `<html><head></head><body>${result}</body></html>`,
+			firstHeadingText,
+			firstParagraphText,
+			readTimeMins,
+		};
+	};
+
+	exports.getIDDivs = (html_body) => {
+		const $ = cheerio.load(html_body, {
+			decodeEntities: false,
+		});
+
+		const divs = [];
+
+		$("div").each(function (i, element) {
+			if ($(this).attr("id")?.startsWith("hb-doc-anchor-")) {
+				divs.push({
+					id: $(this).attr("id"),
+					html: $(this).html(),
+					text: $(this).text(),
+				});
+			}
+		});
+		return divs;
+	};
+
+	exports.getHTMLFrontmatterHeader = (html_body) => {
+		const response = {
+			fm_header: "",
+			fm_properties: {},
+		};
+		const $ = cheerio.load(html_body, {
+			decodeEntities: false,
+		});
+		if (
+			$._root?.children &&
+			Array.isArray($._root.children) &&
+			$._root.children.length > 0
+		) {
+			for (const child of $._root.children) {
+				if (
+					child.type === "comment" &&
+					child.data &&
+					child.data.startsWith("[[FRONTMATTER")
+				) {
+					// We have a Frontmatter header - return each property in an array
+					const fm_properties = child.data.split(/\r?\n/);
+					for (let i = 0; i < fm_properties.length; i++) {
+						if (fm_properties[i].includes(":")) {
+							const property_details = fm_properties[i].split(/:(.*)/s);
+							if (property_details.length > 1) {
+								let prop_val = property_details[1].trim();
+								if (/^".*"$/.test(prop_val)) {
+									prop_val = prop_val.substring(1, prop_val.length - 1);
+								}
+								if (property_details[0].trim().toLowerCase() === "title") {
+									// Decode HTML entities in the title value: handles named entities
+									// (&amp; &lt; &gt; &quot; &#39; &apos;), decimal numeric refs (&#123;),
+									// and hex numeric refs (&#x7B;).
+									prop_val = prop_val.replace(/&amp;|&lt;|&gt;|&quot;|&#39;|&apos;|&#(\d+);|&#x([0-9a-fA-F]+);/g,
+									(m, dec, hex) => dec ? String.fromCharCode(+dec) : hex ? String.fromCharCode(parseInt(hex, 16)) : ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'", '&apos;': "'" })[m]);
+								}
+								response.fm_properties[
+									property_details[0].trim().toLowerCase()
+								] = prop_val;
+							}
+						}
+					}
+
+					// And return the header as a whole so it can be easily replaced
+					response.fm_header = child.data;
+				}
+			}
+		}
+
+		return response;
+	};
+
+	exports.truncate_string = (str, n, useWordBoundary) => {
+		if (str.length <= n) {
+			return str;
+		}
+		const subString = str.slice(0, n - 1);
+		return `${
+			useWordBoundary
+				? subString.slice(0, subString.lastIndexOf(" "))
+				: subString
+		}…`;
+	};
+
+	exports.html_to_text = (html, { baseElement } = {}) => {
+		const $ = cheerio.load(html, { decodeEntities: false });
+		if (baseElement) {
+			return $(baseElement).map((_i, el) => $(el).text()).get().join("\n");
+		}
+		return $("body").text();
+	};
+
+	exports.get_html_read_time = (html) => {
+		// Get word count
+		const text = exports.html_to_text(html);
+		const word_count = text.trim().split(/\s+/).filter(Boolean).length;
+		if (word_count === 0) return 0;
+
+		// Calculate the read time - divide the word count by 200
+		let read_time = Math.round(word_count / 200);
+		if (read_time === 0) read_time = 1;
+		return read_time;
+	};
+
+	exports.get_github_api_path = (repo, relative_path) => {
+		if (repo) {
+			const clean_repo = repo.endsWith("/") ? repo.slice(0, -1) : repo;
+			const github_paths = {};
+			github_paths.api_path = clean_repo.replace(
+				"https://github.com/",
+				"https://api.github.com/repos/",
+			);
+			github_paths.api_path += `/commits?path=${encodeURIComponent(
+				`/${relative_path.replace("\\\\", "/").replace("\\", "/")}`,
+			)}`;
+			github_paths.edit_path = `${repo}/blob/main/${relative_path.replace("\\\\", "/").replace("\\", "/")}`;
+			return github_paths;
+		}
+		return "";
+	};
+
+	const get_github_contributors_path = (repo) => {
+		const clean_repo = repo.endsWith("/") ? repo.slice(0, -1) : repo;
+		const github_paths = {};
+		github_paths.api_path = clean_repo.replace(
+			"https://github.com/",
+			"https://api.github.com/repos/",
+		);
+		github_paths.api_path += "/contributors";
+		return github_paths;
+	};
+
+	exports.get_github_repo_details = async (
+		github_url,
+		github_api_token,
+	) => {
+		const response = {
+			success: false,
+			error: "",
+			data: {},
+			private: false
+		};
+		const request_options = {
+			headers: {
+				"User-Agent": "HornbillDocsBuild",
+				"Cache-Control": "no-cache",
+				Host: "api.github.com",
+				Accept: "application/json",
+			},
+			timeout: 5000,
+		};
+		if (github_api_token !== "") {
+			request_options.headers.authorization = `Bearer ${github_api_token}`;
+		}
+
+		let github_response;
+		let github_data;
+		try {
+			github_response = await fetchWithRetry(github_url, {
+				headers: request_options.headers,
+				timeoutMs: 5000,
+			});
+			if (retried) {
+				retried = false;
+				console.log("API call retry success!");
+			}
+			github_data = await github_response.json();
+		} catch (err) {
+			// Network-level failure (fetchWithRetry re-throws after exhausting retries)
+			response.error = `Unexpected response from GitHub for [${github_url}:\n${JSON.stringify(err)}]`;
+			return response;
+		}
+		// fetch does not throw on HTTP errors — return early for unexpected status codes
+		if (github_response.status !== 200 && github_response.status !== 401 && github_response.status !== 403) {
+			response.error = new Error(`HTTP ${github_response.status}`);
+			return response;
+		}
+		if (github_response.status === 200) {
+			response.success = true;
+			response.data = github_data;
+			response.private = github_data.private;
+		} else {
+			// Is it a 404 or 403?
+			response.error = `${github_response.status} : ${github_data.message}`;
+		}
+		return response;
+	};
+
+	exports.get_github_contributors = async (
+		github_url,
+		github_api_token,
+		repo,
+	) => {
+		const response = {
+			success: false,
+			error: "",
+			contributors: [],
+			contributor_count: 0,
+			last_commit_date: "",
+		};
+		const contributors = {};
+
+		const request_options = {
+			headers: {
+				"User-Agent": "HornbillDocsBuild",
+				"Cache-Control": "no-cache",
+				Host: "api.github.com",
+				Accept: "application/json",
+			},
+			timeout: 5000,
+		};
+		if (github_api_token !== "") {
+			request_options.headers.authorization = `Bearer ${github_api_token}`;
+		}
+		let github_response;
+		let github_data;
+		try {
+			github_response = await fetchWithRetry(github_url, {
+				headers: request_options.headers,
+				timeoutMs: 5000,
+			});
+			if (retried) {
+				retried = false;
+				console.log("API call retry success!");
+			}
+			github_data = await github_response.json();
+		} catch (err) {
+			// Network-level failure (fetchWithRetry re-throws after exhausting retries)
+			response.error = `Unexpected response from GitHub for [${github_url}:\n${JSON.stringify(err)}]`;
+			return response;
+		}
+		// fetch does not throw on HTTP errors — return early for unexpected status codes
+		if (github_response.status !== 200 && github_response.status !== 401 && github_response.status !== 403) {
+			response.error = new Error(`HTTP ${github_response.status}`);
+			return response;
+		}
+		if (github_response.status === 200) {
+			response.success = true;
+			const commits = github_data;
+			for (const commit of commits) {
+				if (
+					commit.committer?.type &&
+					commit.committer.type.toLowerCase() === "user" &&
+					commit.committer.login.toLowerCase() !== "web-flow"
+				) {
+					if (!contributors[commit.committer.id]) {
+						response.contributor_count++;
+						contributors[commit.committer.id] = {
+							login: commit.committer.login,
+							avatar_url: commit.committer.avatar_url,
+							html_url: commit.committer.html_url,
+							name: commit.commit.committer.name,
+						};
+					}
+					if (response.last_commit_date !== "") {
+						const new_commit_date = new Date(commit.commit.committer.date);
+						const exist_commit_date = new Date(response.last_commit_date);
+						if (new_commit_date > exist_commit_date)
+							response.last_commit_date = commit.commit.committer.date;
+					} else {
+						response.last_commit_date = commit.commit.committer.date;
+					}
+				} else if (commit.author?.id) {
+					if (!contributors[commit.author.id]) {
+						response.contributor_count++;
+						contributors[commit.author.id] = {
+							login: commit.author.login,
+							avatar_url: commit.author.avatar_url,
+							html_url: commit.author.html_url,
+							name: commit.commit.author.name,
+						};
+					}
+					if (response.last_commit_date !== "") {
+						const new_commit_date = new Date(commit.commit.author.date);
+						const exist_commit_date = new Date(response.last_commit_date);
+						if (new_commit_date > exist_commit_date)
+							response.last_commit_date = commit.commit.author.date;
+					} else {
+						response.last_commit_date = commit.commit.author.date;
+					}
+				}
+			}
+			for (const key in contributors) {
+				if (Object.hasOwn(contributors, key)) {
+					response.contributors.push(contributors[key]);
+				}
+			}
+		} else if (github_response.status === 403) {
+			// Private repo, fine-grained permissions don't yet support getting commits without content, get list from meta permissions
+			const contrib_url = get_github_contributors_path(repo).api_path;
+			try {
+				github_response = await fetchWithRetry(contrib_url, {
+					headers: request_options.headers,
+					timeoutMs: 5000,
+				});
+				if (retried) {
+					retried = false;
+					console.log("API call retry success!");
+				}
+				github_data = await github_response.json();
+			} catch (err) {
+				// Network-level failure (fetchWithRetry re-throws after exhausting retries)
+				response.error = `Unexpected response from GitHub for [${contrib_url}:\n${JSON.stringify(err)}]`;
+				return response;
+			}
+			// fetch does not throw on HTTP errors — return early if fallback request failed
+			if (github_response.status !== 200) {
+				response.error = new Error(`HTTP ${github_response.status}`);
+				return response;
+			}
+			if (github_response.status === 200) {
+				response.success = true;
+				const commits = github_data;
+				for (const commit of commits) {
+					if (
+						commit.type &&
+						commit.type.toLowerCase() === "user" &&
+						commit.login.toLowerCase() !== "web-flow"
+					) {
+						if (!contributors[commit.id]) {
+							response.contributor_count++;
+							contributors[commit.id] = {
+								login: commit.login,
+								avatar_url: commit.avatar_url,
+								html_url: commit.html_url,
+								name: commit.name ? commit.name : commit.login,
+							};
+						}
+						if (
+							response.last_commit_date !== "" &&
+							response.last_commit_date !== "No Commit Date Available"
+						) {
+							const new_commit_date = new Date(commit.date);
+							const exist_commit_date = new Date(response.last_commit_date);
+							if (new_commit_date > exist_commit_date)
+								response.last_commit_date = commit.date;
+						} else {
+							response.last_commit_date = commit.date
+								? commit.date
+								: "No Commit Date Available";
+						}
+					}
+				}
+				for (const key in contributors) {
+					if (Object.hasOwn(contributors, key)) {
+						response.contributors.push(contributors[key]);
+					}
+				}
+			}
+		} else {
+			response.error = `Unexpected Status: ${github_response.status}.`;
+		}
+		return response;
+	};
+
+	exports.strip_drafts = (nav_items) => {
+		const return_nav = nav_items;
+		recurse_nav(return_nav);
+		return return_nav;
+	};
+
+	const recurse_nav = (nav_items) => {
+		for (const key in nav_items) {
+			if (nav_items[key].draft) {
+				nav_items.splice(key, 1);
+				recurse_nav(nav_items);
+			} else if (nav_items[key].items) {
+				recurse_nav(nav_items[key].items);
+			}
+		}
+	};
+
+	exports.build_breadcrumbs = (nav_items) => {
+		const response = {
+			bc: {},
+			errors: [],
+		};
+		const buildBreadcrumb = (items, parentLinks) => {
+			// Process parent links
+			let parentlink = true;
+			if (parentLinks.length > 0) {
+				if (parentLinks[0].link === undefined || parentLinks[0].link === "" || parentLinks[0].draft )
+					parentlink = false;
+
+				for (let i = 1; i < 10; i++) {
+					if (
+						parentLinks[i] &&
+						parentLinks[i].link === undefined &&
+						items.length > 0 &&
+						items[0].link
+					) {
+						parentLinks[i].link = items[0].link;
+					}
+				}
+			}
+
+			// Loop through items, build breadcrumb
+			for (let i = 0; i < items.length; i++) {
+				if (!items[i].text) {
+					response.errors.push(
+						`The following Nav Item is missing its text property: ${JSON.stringify(
+							items[i],
+						)}`,
+					);
+				}
+
+				if (!items[i].link && !items[i].items) {
+					response.errors.push(
+						`The following Nav Item has no link or items property: ${JSON.stringify(
+							items[i],
+						)}`,
+					);
+				}
+				const item = items[i];
+				if (!parentlink && item.link) {
+					parentLinks[0].link = item.link;
+					parentlink = true;
+				}
+				const { text, link, items: subItems } = item;
+				const breadcrumb = [...parentLinks, { text, link }];
+
+				if (link) {
+					response.bc[link] = breadcrumb;
+				}
+
+				if (subItems) {
+					buildBreadcrumb(subItems, breadcrumb);
+				}
+			}
+		};
+
+		buildBreadcrumb(nav_items, []);
+		return response;
+	};
+
+	exports.get_draft_links = (items, parent_is_draft = false) => {
+		let draft_links = [];
+
+		for (const item of items) {
+			// Check if this item is draft or if any parent was draft
+			const is_draft = parent_is_draft || item.draft;
+
+			// If the current item has a link and is draft (or parent is draft), add the link
+			if (is_draft && item.link) {
+				draft_links.push(item.link);
+			}
+
+			// If the current item has nested items, recursively check them
+			if (item.items) {
+				draft_links = draft_links.concat(this.get_draft_links(item.items, is_draft));
+			}
+		}
+		return draft_links;
+	};
+
+	exports.load_product_families = async () => {
+		const response = {
+			success: false,
+			prod_families: {},
+			prods_supported: [],
+			errors: "",
+		};
+		const prod_families_url = "https://docs.hornbill.com/_books/products.json";
+		for (let i = 1; i < 4; i++) {
+			try {
+				const prods = await fetch(prod_families_url, {
+					signal: AbortSignal.timeout(5000),
+				});
+				if (prods.status === 200) {
+					response.prod_families = await prods.json();
+					response.prods_supported = [];
+					for (let i = 0; i < response.prod_families.products.length; i++) {
+						response.prods_supported.push(
+							response.prod_families.products[i].id,
+						);
+					}
+					response.success = true;
+					break;
+				}
+				throw `Unexpected status - ${prods.status} ${prods.statusText}`;
+			} catch (e) {
+				if (response.errors === "")
+					response.errors = `Request to ${prod_families_url} failed:`;
+				response.errors += `\nAttempt ${i} - Error returning product families: ${e}`;
+				// Wait 2 seconds and try again
+				await new Promise((r) => setTimeout(r, 2000));
+			}
+		}
+		return response;
+	};
+
+	// Recursively walks a directory tree and invokes fileCallback(element) for each file.
+	// Mirrors the dree.scan API so existing options objects and callbacks work unchanged.
+	// Supported options:
+	//   extensions            - array of extensions to include (e.g. ["md","html"]); omit for all files
+	//   hash                  - compute MD5 hash of each file's content and set element.hash
+	//   normalize             - convert backslashes to forward slashes in all paths
+	//   sorted                - sort directory entries alphabetically before recursing
+	//   sizeInBytes / size    - include file size as element.sizeInBytes
+	//   stat                  - include the fs.Stats object as element.stat
+	//   depth                 - maximum recursion depth (default: unlimited)
+	//   excludeEmptyDirectories - skip directories that contain no entries
+	//   symbolicLinks         - set false to skip symbolic links (default: include them)
+	// Each element passed to the callback has: name, path (absolute), relativePath, and any
+	// optional fields enabled above.
+	exports.scan_dir = (dirPath, opts = {}, fileCallback) => {
+		const extensions = opts.extensions ? new Set(opts.extensions.map((e) => e.toLowerCase())) : null;
+		const maxDepth = opts.depth !== undefined ? opts.depth : Infinity;
+
+		const walk = (currentPath, depth) => {
+			if (depth > maxDepth) return;
+			let entries;
+			try {
+				entries = fs.readdirSync(currentPath, { withFileTypes: true });
+			} catch (_) { return; }
+
+			if (opts.sorted) entries = entries.slice().sort((a, b) => a.name.localeCompare(b.name));
+
+			for (const entry of entries) {
+				if (opts.symbolicLinks === false && entry.isSymbolicLink()) continue;
+				const fullPath = path.join(currentPath, entry.name);
+
+				if (entry.isDirectory()) {
+					if (opts.excludeEmptyDirectories) {
+						try { if (fs.readdirSync(fullPath).length === 0) continue; } catch (_) { continue; }
+					}
+					walk(fullPath, depth + 1);
+				} else if (entry.isFile()) {
+					const ext = path.extname(entry.name).slice(1).toLowerCase();
+					if (extensions && !extensions.has(ext)) continue;
+
+					const absPath = opts.normalize ? fullPath.replaceAll("\\", "/") : fullPath;
+					const relPath = opts.normalize
+						? path.relative(dirPath, fullPath).replaceAll("\\", "/")
+						: path.relative(dirPath, fullPath);
+
+					const element = { name: entry.name, path: absPath, relativePath: relPath, extension: ext };
+
+					if (opts.sizeInBytes || opts.size || opts.stat) {
+						const stat = fs.statSync(fullPath);
+						if (opts.sizeInBytes || opts.size) element.sizeInBytes = stat.size;
+						if (opts.stat) element.stat = stat;
+					}
+
+					if (opts.hash) {
+						element.hash = crypto.createHash("md5").update(fs.readFileSync(fullPath)).digest("hex");
+					}
+
+					fileCallback(element);
+				}
+			}
+		};
+
+		walk(dirPath, 1);
+	};
+
+	// Resolves the true on-disk casing of a file path by walking each path segment
+	// and doing a case-insensitive match against the actual directory listing.
+	// This is important on case-sensitive filesystems (Linux) to catch casing mismatches
+	// that would silently pass on macOS/Windows but break in CI or production.
+	// On Windows, the drive letter is normalised to uppercase and backslash delimiters are used.
+	exports.true_case_path_sync = (filePath) => {
+		const isWin = process.platform === "win32";
+		const delim = isWin ? "\\" : "/";
+		filePath = path.normalize(filePath);
+		const segments = filePath.split(delim).filter((s) => s !== "");
+		let base = path.isAbsolute(filePath) ? (isWin ? segments.shift().toUpperCase() : "") : process.cwd();
+		return segments.reduce((realPath, seg) => {
+			const entries = fs.readdirSync(realPath + delim);
+			// Escape any regex special chars in the segment name before building the pattern
+			const re = new RegExp(`^${seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "i");
+			const match = entries.find((e) => re.test(e));
+			if (!match) throw new Error(`true_case_path_sync: no match for "${seg}" in "${realPath}"`);
+			return realPath + delim + match;
+		}, base);
+	};
+
+	// Creates an empty temporary file with a random name and optional file extension suffix
+	// (e.g. { postfix: ".mmd" }). Returns an object with:
+	//   name           - the absolute path to the temp file
+	//   removeCallback - call this to delete the file when done; errors are silently ignored
+	//                    so it is safe to call even if the file was already cleaned up.
+	exports.tmp_file_sync = (opts = {}) => {
+		const name = path.join(os.tmpdir(), `hdoc-${crypto.randomBytes(8).toString("hex")}${opts.postfix || ""}`);
+		fs.closeSync(fs.openSync(name, "w"));
+		return { name, removeCallback: () => { try { fs.unlinkSync(name); } catch (_) {} } };
+	};
+
+	// Parses a YAML string into a plain JS object. Designed for markdown frontmatter,
+	// which is always simple: scalar key/value pairs, block arrays (- item), and inline
+	// arrays ([a, b, c]). Does not support anchors, multi-line strings, or nested objects.
+	// parseVal handles type coercion: booleans, null, integers, floats, quoted strings,
+	// inline arrays, and plain strings (returned as-is).
+	exports.parse_yaml = (str) => {
+		const parseVal = (v) => {
+			if (v === "true") return true;
+			if (v === "false") return false;
+			if (v === "null" || v === "~") return null;
+			if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+			if (/^-?\d*\.\d+$/.test(v)) return parseFloat(v);
+			if (/^['"].*['"]$/.test(v)) return v.slice(1, -1); // strip surrounding quotes
+			if (v.startsWith("[") && v.endsWith("]")) return v.slice(1, -1).split(",").map(i => parseVal(i.trim()));
+			return v;
+		};
+		const result = {};
+		let currentKey = null;
+		for (const line of str.split("\n")) {
+			if (!line.trim() || /^\s*#/.test(line)) continue;
+			// Block array item (indented dash): append to the current key's array
+			const arrMatch = line.match(/^\s+-\s+(.+)$/);
+			if (arrMatch && currentKey) {
+				if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+				result[currentKey].push(parseVal(arrMatch[1].trim()));
+				continue;
+			}
+			// key: value pair — value may be empty (e.g. start of a block array)
+			const kvMatch = line.match(/^([^:]+):\s*(.*)$/);
+			if (kvMatch) {
+				currentKey = kvMatch[1].trim();
+				result[currentKey] = kvMatch[2].trim() ? parseVal(kvMatch[2].trim()) : null;
+			}
+		}
+		return result;
+	};
+
+	// Pretty-prints an XML string with configurable indentation and line endings.
+	// Tokenises the input using a regex that preserves CDATA sections, comments, and
+	// processing instructions as atomic units so their content is never re-indented.
+	// Options:
+	//   indentation   - string to use per indent level (default: two spaces)
+	//   lineSeparator - line ending to use (default: "\n")
+	//   collapseContent - when true (default), elements that contain only a single text
+	//                     node are kept on one line: <tag>text</tag> rather than split
+	//                     across three lines. Uses one-token lookahead to detect this.
+	exports.xml_format = (xml, opts = {}) => {
+		const ind = opts.indentation || "  ";
+		const sep = opts.lineSeparator || "\n";
+		const collapse = opts.collapseContent !== false;
+		// Match CDATA, comments, PIs, tags, and text nodes as individual tokens
+		const tokens = xml.trim().match(/(<!\[CDATA\[[\s\S]*?\]\]>|<!--[\s\S]*?-->|<[^>]+>|[^<]+)/g) || [];
+		let depth = 0;
+		let out = "";
+		for (let i = 0; i < tokens.length; i++) {
+			const t = tokens[i].trim();
+			if (!t) continue;
+			const isClose = t.startsWith("</");
+			const isSelf = t.startsWith("<") && t.endsWith("/>") && !t.startsWith("<?");
+			const isSpecial = t.startsWith("<?") || t.startsWith("<!--") || t.startsWith("<![");
+			const isOpen = t.startsWith("<") && !isClose && !isSelf && !isSpecial;
+			if (isClose) {
+				depth = Math.max(0, depth - 1);
+				out += ind.repeat(depth) + t + sep;
+			} else if (isSelf || isSpecial) {
+				out += ind.repeat(depth) + t + sep;
+			} else if (isOpen) {
+				// Collapse: if the very next token is text and the one after is the closing tag,
+				// emit all three on one line and skip those two tokens.
+				if (collapse && i + 2 < tokens.length) {
+					const nextTxt = tokens[i + 1] ? tokens[i + 1].trim() : "";
+					const nextClose = tokens[i + 2] ? tokens[i + 2].trim() : "";
+					if (nextTxt && !nextTxt.startsWith("<") && nextClose.startsWith("</")) {
+						out += ind.repeat(depth) + t + nextTxt + nextClose + sep;
+						i += 2;
+						continue;
+					}
+				}
+				out += ind.repeat(depth) + t + sep;
+				depth++;
+			} else {
+				// Plain text node
+				out += ind.repeat(depth) + t + sep;
+			}
+		}
+		return out.trimEnd();
+	};
+
+	// Locates searchString in fileContent, returning 1-based {line, column}.
+	// With whole_link=true, occurrences that are substrings of a longer
+	// URL/path are skipped (e.g. searching for /book/page#anchor must not match
+	// inside /book/page#anchor-more on an earlier line) — the match must not be
+	// immediately preceded or followed by a link-continuation character.
+	exports.find_string_in_string = (fileContent, searchString, whole_link = false) => {
+		const lines = fileContent.split('\n');
+		const link_char = /[a-zA-Z0-9\-_/#?&=.%~]/;
+		let loose_match = null; // first substring hit — fallback when no exact-boundary match exists (e.g. bare URL followed by punctuation)
+
+		for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
+			let from = 0;
+			while (true) {
+				const columnNumber = lines[lineNumber].indexOf(searchString, from);
+				if (columnNumber === -1) break;
+				if (whole_link) {
+					const prev = lines[lineNumber][columnNumber - 1];
+					const next = lines[lineNumber][columnNumber + searchString.length];
+					if ((prev !== undefined && link_char.test(prev)) ||
+						(next !== undefined && link_char.test(next))) {
+						if (loose_match === null)
+							loose_match = { line: lineNumber + 1, column: columnNumber + 1 };
+						from = columnNumber + 1;
+						continue;
+					}
+				}
+				// Return 1-based line and column numbers
+				return { line: lineNumber + 1, column: columnNumber + 1 };
+			}
+		}
+
+		// No exact-boundary match — fall back to the first substring hit, or null
+		return loose_match;
+	}
+})();