hdoc-tools 0.61.0 → 0.62.1

package/hdoc-db.js

@@ -1,114 +1,114 @@
-(() => {
-	const cheerio = require("cheerio");
-	const path = require("node:path");
-	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
-
-	exports.create_table = (db, table_name, columns, virtual, fts5) => {
-		const create_sql = ["CREATE"];
-		if (virtual) create_sql.push("VIRTUAL");
-		create_sql.push("TABLE");
-		create_sql.push(table_name);
-		if (fts5) create_sql.push("USING fts5(");
-		else create_sql.push("(");
-		for (let i = 0; i < columns.length; i++) {
-			if (i !== 0) create_sql.push(`,${columns[i]}`);
-			else create_sql.push(columns[i]);
-		}
-		create_sql.push(");");
-		try {
-			db.exec(create_sql.join("\n"));
-			return null;
-		} catch (e) {
-			return e;
-		}
-	};
-
-	exports.insert_record = (db, table, columns, values) => {
-		const response = {
-			success: false,
-			row_id: 0,
-			error: null,
-		};
-		const queryProps = [];
-		queryProps.push(`INSERT INTO ${table}`);
-		let cols = "(";
-		let vals = "VALUES (";
-		for (let i = 0; i < columns.length; i++) {
-			if (i === 0) {
-				cols += `${columns[i].replace("UNINDEXED", "").replace("INTEGER", "").trim()}`;
-				vals += "?";
-			} else {
-				cols += `, ${columns[i].replace("UNINDEXED", "").replace("INTEGER", "").trim()}`;
-				vals += ", ?";
-			}
-		}
-		cols += ")";
-		vals += ")";
-		queryProps.push(cols);
-		queryProps.push(vals);
-
-		try {
-			const stmt = db.prepare(queryProps.join(" "));
-			const info = stmt.run(values);
-			response.row_id = info.lastInsertRowid;
-			response.success = true;
-		} catch (e) {
-			response.error = e;
-		}
-		return response;
-	};
-
-	exports.transform_html_for_index = (html_txt) => {
-		const response = {
-			fm_props: {},
-			sections: [],
-		};
-
-		// Single parse covers frontmatter extraction, full-text, and preview —
-		// previously three separate cheerio.load() calls.
-		const $ = cheerio.load(html_txt, { decodeEntities: false });
-
-		// Extract frontmatter properties from the leading HTML comment
-		if ($._root?.children && Array.isArray($._root.children)) {
-			for (const child of $._root.children) {
-				if (child.type === "comment" && child.data?.startsWith("[[FRONTMATTER")) {
-					for (const line of child.data.split(/\r?\n/)) {
-						if (line.includes(":")) {
-							const parts = line.split(/:(.*)/s);
-							if (parts.length > 1) {
-								const key = parts[0].trim().toLowerCase();
-								let val = parts[1].trim();
-								if (/^".*"$/.test(val)) val = val.slice(1, -1);
-								if (key === "title") {
-									val = 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_props[key] = val;
-							}
-						}
-					}
-					break;
-				}
-			}
-		}
-
-		// Page chrome - the document-header block (breadcrumb bar, edit link,
-		// title, "Article / date / N minutes to read / N contributors") is
-		// rendered into every page and would otherwise pollute search index
-		// term frequencies and embedding chunks. The title is indexed
-		// separately from frontmatter, so nothing of value is lost.
-		$(".document-header").remove();
-
-		// Full-document plain text for search indexing
-		const text = $("body").text();
-
-		// Preview: first paragraph texts joined, then truncated
-		let preview = $("p").map((_i, el) => $(el).text()).get().join("\n");
-		preview = hdoc.truncate_string(preview, 200, true).replace(/(?:\r\n|\r|\n)/g, " ");
-
-		response.sections.push({ text, preview });
-		return response;
-	};
-})();
+(() => {
+	const cheerio = require("cheerio");
+	const path = require("node:path");
+	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
+
+	exports.create_table = (db, table_name, columns, virtual, fts5) => {
+		const create_sql = ["CREATE"];
+		if (virtual) create_sql.push("VIRTUAL");
+		create_sql.push("TABLE");
+		create_sql.push(table_name);
+		if (fts5) create_sql.push("USING fts5(");
+		else create_sql.push("(");
+		for (let i = 0; i < columns.length; i++) {
+			if (i !== 0) create_sql.push(`,${columns[i]}`);
+			else create_sql.push(columns[i]);
+		}
+		create_sql.push(");");
+		try {
+			db.exec(create_sql.join("\n"));
+			return null;
+		} catch (e) {
+			return e;
+		}
+	};
+
+	exports.insert_record = (db, table, columns, values) => {
+		const response = {
+			success: false,
+			row_id: 0,
+			error: null,
+		};
+		const queryProps = [];
+		queryProps.push(`INSERT INTO ${table}`);
+		let cols = "(";
+		let vals = "VALUES (";
+		for (let i = 0; i < columns.length; i++) {
+			if (i === 0) {
+				cols += `${columns[i].replace("UNINDEXED", "").replace("INTEGER", "").trim()}`;
+				vals += "?";
+			} else {
+				cols += `, ${columns[i].replace("UNINDEXED", "").replace("INTEGER", "").trim()}`;
+				vals += ", ?";
+			}
+		}
+		cols += ")";
+		vals += ")";
+		queryProps.push(cols);
+		queryProps.push(vals);
+
+		try {
+			const stmt = db.prepare(queryProps.join(" "));
+			const info = stmt.run(values);
+			response.row_id = info.lastInsertRowid;
+			response.success = true;
+		} catch (e) {
+			response.error = e;
+		}
+		return response;
+	};
+
+	exports.transform_html_for_index = (html_txt) => {
+		const response = {
+			fm_props: {},
+			sections: [],
+		};
+
+		// Single parse covers frontmatter extraction, full-text, and preview —
+		// previously three separate cheerio.load() calls.
+		const $ = cheerio.load(html_txt, { decodeEntities: false });
+
+		// Extract frontmatter properties from the leading HTML comment
+		if ($._root?.children && Array.isArray($._root.children)) {
+			for (const child of $._root.children) {
+				if (child.type === "comment" && child.data?.startsWith("[[FRONTMATTER")) {
+					for (const line of child.data.split(/\r?\n/)) {
+						if (line.includes(":")) {
+							const parts = line.split(/:(.*)/s);
+							if (parts.length > 1) {
+								const key = parts[0].trim().toLowerCase();
+								let val = parts[1].trim();
+								if (/^".*"$/.test(val)) val = val.slice(1, -1);
+								if (key === "title") {
+									val = 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_props[key] = val;
+							}
+						}
+					}
+					break;
+				}
+			}
+		}
+
+		// Page chrome - the document-header block (breadcrumb bar, edit link,
+		// title, "Article / date / N minutes to read / N contributors") is
+		// rendered into every page and would otherwise pollute search index
+		// term frequencies and embedding chunks. The title is indexed
+		// separately from frontmatter, so nothing of value is lost.
+		$(".document-header").remove();
+
+		// Full-document plain text for search indexing
+		const text = $("body").text();
+
+		// Preview: first paragraph texts joined, then truncated
+		let preview = $("p").map((_i, el) => $(el).text()).get().join("\n");
+		preview = hdoc.truncate_string(preview, 200, true).replace(/(?:\r\n|\r|\n)/g, " ");
+
+		response.sections.push({ text, preview });
+		return response;
+	};
+})();

package/hdoc-help.js

@@ -1,60 +1,60 @@
-(() => {
-	exports.run = () => {
-		// STEVE: The purpose of this function is to output information about hdoc arguments
-		const helpText = `
-Command Line Usage
-
-    hdoc <command> [switches]
-
-Commands
-
- - build
-    Performs a local build of the book, and outputs as a ZIP file. 
-     - Use the '--set-version 1.2.3' argument to set the version number of the built book. 
-     - Use the '--no-color' argument to remove any color control characters from the output.
-     - Use the '--no-links' argument to skip link output to CLI during validation.
-     - Use the '--no-embeddings' argument to skip semantic search embedding generation.
-
- - createDocs
-    Creates folder structure and markdown documents as defined in the HDocBook navigation item links
-
- - edit
-    Starts the local structure/content editor on port 3001 (bound to 127.0.0.1), serving the editor UI alongside a live preview of the content. Supports a -port N to use a different port.
-    NOTE: This feature is experimental and not really for general use yet. GS
-
- - help
-    Outputs available arguments and switches
-
- - init
-    Initializes a new HDocBook project from a template, using runtime input variables
-
- - serve
-    Starts a local web server on port 3000, serving the content. Supports a -port N to use a different port
-
- - stats
-    Returns statistics regarding the book you are working on. Supports a -v switch for verbose output.
-    The book statistics do not include counts for any externally hosted content injected into the book content using the [[INCLUDE]] tags.
-
- - validate
-    Validates the book content.
-     - Use the '--set-version 1.2.3' argument to set the version number of the built book. 
-     - Use the '--no-color' argument to remove any color control characters from the output.
-     - Use the '--no-links' argument to skip link output to CLI during validation.
-     - Use the '--quiet' argument to suppress most console output, and only output validation errors if they are found.
-
- - bump
-    Updates the semantic version number of the current book. If no options are specified, then the default of patch is applied:
-    - major - updates the major version of the book. i.e. - 1.4.5 would become 2.0.0
-    - minor - updates the minor version of the book. i.e. - 1.4.5 would become 1.5.0
-    - patch (default) - updates the patch version of the book. i.e. - 1.4.5 would become 1.4.6
-
- - ver
-    Returns the version of the current book
-
-Example
-
-    hdoc stats -v
-`;
-		console.log(helpText);
-	};
-})();
+(() => {
+	exports.run = () => {
+		// STEVE: The purpose of this function is to output information about hdoc arguments
+		const helpText = `
+Command Line Usage
+
+    hdoc <command> [switches]
+
+Commands
+
+ - build
+    Performs a local build of the book, and outputs as a ZIP file. 
+     - Use the '--set-version 1.2.3' argument to set the version number of the built book. 
+     - Use the '--no-color' argument to remove any color control characters from the output.
+     - Use the '--no-links' argument to skip link output to CLI during validation.
+     - Use the '--no-embeddings' argument to skip semantic search embedding generation.
+
+ - createDocs
+    Creates folder structure and markdown documents as defined in the HDocBook navigation item links
+
+ - edit
+    Starts the local structure/content editor on port 3001 (bound to 127.0.0.1), serving the editor UI alongside a live preview of the content. Supports a -port N to use a different port.
+    NOTE: This feature is experimental and not really for general use yet. GS
+
+ - help
+    Outputs available arguments and switches
+
+ - init
+    Initializes a new HDocBook project from a template, using runtime input variables
+
+ - serve
+    Starts a local web server on port 3000, serving the content. Supports a -port N to use a different port
+
+ - stats
+    Returns statistics regarding the book you are working on. Supports a -v switch for verbose output.
+    The book statistics do not include counts for any externally hosted content injected into the book content using the [[INCLUDE]] tags.
+
+ - validate
+    Validates the book content.
+     - Use the '--set-version 1.2.3' argument to set the version number of the built book. 
+     - Use the '--no-color' argument to remove any color control characters from the output.
+     - Use the '--no-links' argument to skip link output to CLI during validation.
+     - Use the '--quiet' argument to suppress most console output, and only output validation errors if they are found.
+
+ - bump
+    Updates the semantic version number of the current book. If no options are specified, then the default of patch is applied:
+    - major - updates the major version of the book. i.e. - 1.4.5 would become 2.0.0
+    - minor - updates the minor version of the book. i.e. - 1.4.5 would become 1.5.0
+    - patch (default) - updates the patch version of the book. i.e. - 1.4.5 would become 1.4.6
+
+ - ver
+    Returns the version of the current book
+
+Example
+
+    hdoc stats -v
+`;
+		console.log(helpText);
+	};
+})();

package/hdoc-install-browser.js

@@ -1,145 +1,145 @@
-// Resilient browser provisioning for hdoc-tools.
-//
-// Replaces the old `puppeteer browsers install ...` one-liner postinstall.
-// Puppeteer's own bundled download (install.mjs) is disabled via
-// .puppeteerrc.cjs (skipDownload), so this script is the single, controlled
-// place Chrome + chrome-headless-shell are fetched.
-//
-// Why: on some Windows Server 2019 build agents the Chrome archive extracts
-// only partially (Defender quarantining binaries mid-extract, or a truncated
-// download behind a proxy). The first failure leaves the version folder on
-// disk, after which Puppeteer refuses to re-extract and every later install
-// reports "folder exists but executable missing" — a permanent dead end.
-//
-// This script makes provisioning idempotent and self-healing:
-//   * skip when a valid executable already exists,
-//   * delete any stale/partial version folder before (re)installing,
-//   * retry the download a few times,
-//   * verify the executable exists afterwards and fail loudly with concrete
-//     remediation if it still does not.
-
-(async () => {
-	const fs = require("node:fs");
-	const path = require("node:path");
-	const {
-		install,
-		computeExecutablePath,
-		detectBrowserPlatform,
-		Browser,
-	} = require("@puppeteer/browsers");
-
-	// Build id + cache dir come from the shared .puppeteerrc.cjs so install and
-	// runtime launch can never drift apart.
-	const puppeteerConfig = require(path.join(__dirname, ".puppeteerrc.cjs"));
-	const CHROME_BUILD = puppeteerConfig.chromeBuild;
-	const MAX_ATTEMPTS = 3;
-
-	const RED = "\x1b[31m";
-	const YELLOW = "\x1b[33m";
-	const GREEN = "\x1b[32m";
-	const RESET = "\x1b[0m";
-
-	const log = (msg) => console.log(`[hdoc-tools] ${msg}`);
-
-	// Resolve the cache directory the same way Puppeteer does at runtime:
-	// PUPPETEER_CACHE_DIR wins, otherwise the fixed cacheDir declared in
-	// .puppeteerrc.cjs. Reading the shared config (rather than recomputing from
-	// os.homedir()) guarantees we install to exactly the path the browser is
-	// later launched from — critical for `sudo npm i -g`, where postinstall runs
-	// as root but `hdoc` runs as a normal user with a different home directory.
-	const cacheDir = process.env.PUPPETEER_CACHE_DIR || puppeteerConfig.cacheDir;
-
-	let platform;
-	try {
-		platform = detectBrowserPlatform();
-	} catch (err) {
-		console.error(
-			`${RED}Unable to detect browser platform: ${err.message}${RESET}`,
-		);
-		process.exit(1);
-	}
-
-	const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-	const rmrf = (target) => {
-		try {
-			fs.rmSync(target, { recursive: true, force: true });
-		} catch {
-			/* best effort */
-		}
-	};
-
-	// A usable install is one where the executable exists and is non-empty.
-	const isUsable = (exePath) => {
-		try {
-			return fs.statSync(exePath).size > 0;
-		} catch {
-			return false;
-		}
-	};
-
-	const provision = async (browser, label) => {
-		const exePath = computeExecutablePath({
-			browser,
-			buildId: CHROME_BUILD,
-			cacheDir,
-			platform,
-		});
-		// chrome.exe -> chrome-win64 -> win64-<build>; nuke the whole build folder
-		// so a partial extraction can never block a clean re-extract.
-		const versionFolder = path.dirname(path.dirname(exePath));
-
-		if (isUsable(exePath)) {
-			log(`${label} ${CHROME_BUILD} already present, skipping download.`);
-			return true;
-		}
-
-		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-			rmrf(versionFolder); // clear any stale/partial extract first
-			try {
-				log(
-					`Installing ${label} ${CHROME_BUILD} (attempt ${attempt}/${MAX_ATTEMPTS})...`,
-				);
-				await install({
-					browser,
-					buildId: CHROME_BUILD,
-					cacheDir,
-					platform,
-					unpack: true,
-				});
-			} catch (err) {
-				console.error(
-					`${YELLOW}  attempt ${attempt} failed: ${err.message}${RESET}`,
-				);
-			}
-
-			if (isUsable(exePath)) {
-				log(`${GREEN}${label} ${CHROME_BUILD} ready.${RESET}`);
-				return true;
-			}
-
-			if (attempt < MAX_ATTEMPTS) await sleep(2000);
-		}
-
-		return false;
-	};
-
-	const chromeOk = await provision(Browser.CHROME, "Chrome");
-	const shellOk = await provision(
-		Browser.CHROMEHEADLESSSHELL,
-		"chrome-headless-shell",
-	);
-
-	if (chromeOk && shellOk) process.exit(0);
-
-	console.error(
-		`\n${RED}Failed to provision a complete browser into:${RESET}\n  ${cacheDir}\n\n` +
-			"This is almost always one of:\n" +
-			"  1. Antivirus (e.g. Windows Defender) quarantining Chrome files mid-extract.\n" +
-			`     Fix: Add-MpPreference -ExclusionPath "${cacheDir}"\n` +
-			"  2. A stale/partial cache folder. Fix: delete the chrome / chrome-headless-shell\n" +
-			`     sub-folders under "${cacheDir}" and reinstall.\n` +
-			"  3. A truncated download behind a proxy / TLS inspection. Check npm/HTTPS proxy config.\n",
-	);
-	process.exit(1);
-})();
+// Resilient browser provisioning for hdoc-tools.
+//
+// Replaces the old `puppeteer browsers install ...` one-liner postinstall.
+// Puppeteer's own bundled download (install.mjs) is disabled via
+// .puppeteerrc.cjs (skipDownload), so this script is the single, controlled
+// place Chrome + chrome-headless-shell are fetched.
+//
+// Why: on some Windows Server 2019 build agents the Chrome archive extracts
+// only partially (Defender quarantining binaries mid-extract, or a truncated
+// download behind a proxy). The first failure leaves the version folder on
+// disk, after which Puppeteer refuses to re-extract and every later install
+// reports "folder exists but executable missing" — a permanent dead end.
+//
+// This script makes provisioning idempotent and self-healing:
+//   * skip when a valid executable already exists,
+//   * delete any stale/partial version folder before (re)installing,
+//   * retry the download a few times,
+//   * verify the executable exists afterwards and fail loudly with concrete
+//     remediation if it still does not.
+
+(async () => {
+	const fs = require("node:fs");
+	const path = require("node:path");
+	const {
+		install,
+		computeExecutablePath,
+		detectBrowserPlatform,
+		Browser,
+	} = require("@puppeteer/browsers");
+
+	// Build id + cache dir come from the shared .puppeteerrc.cjs so install and
+	// runtime launch can never drift apart.
+	const puppeteerConfig = require(path.join(__dirname, ".puppeteerrc.cjs"));
+	const CHROME_BUILD = puppeteerConfig.chromeBuild;
+	const MAX_ATTEMPTS = 3;
+
+	const RED = "\x1b[31m";
+	const YELLOW = "\x1b[33m";
+	const GREEN = "\x1b[32m";
+	const RESET = "\x1b[0m";
+
+	const log = (msg) => console.log(`[hdoc-tools] ${msg}`);
+
+	// Resolve the cache directory the same way Puppeteer does at runtime:
+	// PUPPETEER_CACHE_DIR wins, otherwise the fixed cacheDir declared in
+	// .puppeteerrc.cjs. Reading the shared config (rather than recomputing from
+	// os.homedir()) guarantees we install to exactly the path the browser is
+	// later launched from — critical for `sudo npm i -g`, where postinstall runs
+	// as root but `hdoc` runs as a normal user with a different home directory.
+	const cacheDir = process.env.PUPPETEER_CACHE_DIR || puppeteerConfig.cacheDir;
+
+	let platform;
+	try {
+		platform = detectBrowserPlatform();
+	} catch (err) {
+		console.error(
+			`${RED}Unable to detect browser platform: ${err.message}${RESET}`,
+		);
+		process.exit(1);
+	}
+
+	const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+	const rmrf = (target) => {
+		try {
+			fs.rmSync(target, { recursive: true, force: true });
+		} catch {
+			/* best effort */
+		}
+	};
+
+	// A usable install is one where the executable exists and is non-empty.
+	const isUsable = (exePath) => {
+		try {
+			return fs.statSync(exePath).size > 0;
+		} catch {
+			return false;
+		}
+	};
+
+	const provision = async (browser, label) => {
+		const exePath = computeExecutablePath({
+			browser,
+			buildId: CHROME_BUILD,
+			cacheDir,
+			platform,
+		});
+		// chrome.exe -> chrome-win64 -> win64-<build>; nuke the whole build folder
+		// so a partial extraction can never block a clean re-extract.
+		const versionFolder = path.dirname(path.dirname(exePath));
+
+		if (isUsable(exePath)) {
+			log(`${label} ${CHROME_BUILD} already present, skipping download.`);
+			return true;
+		}
+
+		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+			rmrf(versionFolder); // clear any stale/partial extract first
+			try {
+				log(
+					`Installing ${label} ${CHROME_BUILD} (attempt ${attempt}/${MAX_ATTEMPTS})...`,
+				);
+				await install({
+					browser,
+					buildId: CHROME_BUILD,
+					cacheDir,
+					platform,
+					unpack: true,
+				});
+			} catch (err) {
+				console.error(
+					`${YELLOW}  attempt ${attempt} failed: ${err.message}${RESET}`,
+				);
+			}
+
+			if (isUsable(exePath)) {
+				log(`${GREEN}${label} ${CHROME_BUILD} ready.${RESET}`);
+				return true;
+			}
+
+			if (attempt < MAX_ATTEMPTS) await sleep(2000);
+		}
+
+		return false;
+	};
+
+	const chromeOk = await provision(Browser.CHROME, "Chrome");
+	const shellOk = await provision(
+		Browser.CHROMEHEADLESSSHELL,
+		"chrome-headless-shell",
+	);
+
+	if (chromeOk && shellOk) process.exit(0);
+
+	console.error(
+		`\n${RED}Failed to provision a complete browser into:${RESET}\n  ${cacheDir}\n\n` +
+			"This is almost always one of:\n" +
+			"  1. Antivirus (e.g. Windows Defender) quarantining Chrome files mid-extract.\n" +
+			`     Fix: Add-MpPreference -ExclusionPath "${cacheDir}"\n` +
+			"  2. A stale/partial cache folder. Fix: delete the chrome / chrome-headless-shell\n" +
+			`     sub-folders under "${cacheDir}" and reinstall.\n` +
+			"  3. A truncated download behind a proxy / TLS inspection. Check npm/HTTPS proxy config.\n",
+	);
+	process.exit(1);
+})();