hdoc-tools 0.60.1 → 0.61.0

package/hdoc-content-routes.js

@@ -33,6 +33,34 @@ function escape_html(str) {
 		.replace(/>/g, ">");
 }
 
+// Resolve a request URL path against a root directory, refusing anything that
+// escapes the root (path traversal via ../, encoded %2e%2e%2f, backslashes on
+// Windows, or NUL bytes). Returns the absolute resolved path, or null when the
+// URL is malformed or lands outside the root. Both `hdoc serve` (which binds
+// 0.0.0.0 and is LAN-reachable) and `hdoc edit` route raw request URLs through
+// this before touching the filesystem.
+function resolve_within_root(root, url_path) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(url_path);
+	} catch {
+		return null; // malformed percent-encoding
+	}
+	// Drop any query string and reject NUL bytes outright
+	decoded = decoded.split("?")[0];
+	if (decoded.includes("\0")) return null;
+	const resolved_root = path.resolve(root);
+	const resolved = path.resolve(resolved_root, `.${path.sep}${decoded.replace(/^[/\\]+/, "")}`);
+	if (
+		resolved !== resolved_root &&
+		!resolved.startsWith(resolved_root + path.sep)
+	) {
+		return null;
+	}
+	return resolved;
+}
+exports.resolve_within_root = resolve_within_root;
+
 // Recursively walk <source_path>/<docId>/_inline building the nav fragment
 // consumed by the viewer's nav-section-component. Subfolders become
 // expandable container nodes (items, no link); files become leaf links.
@@ -94,6 +122,30 @@ exports.create_content_handler = (ctx) => {
 	// process_includes resolves include paths relative to the source root.
 	const global_source_path = source_path;
 
+	// Configs are re-read from disk per request so `hdoc serve` / `hdoc edit`
+	// pick up edits to hdocbook.json / hdocbook-project.json without a restart.
+	// Falls back to the startup copy when a mid-edit save is momentarily
+	// invalid JSON.
+	function load_json(file_path, fallback) {
+		try {
+			return JSON.parse(fs.readFileSync(file_path, "utf8"));
+		} catch {
+			return fallback;
+		}
+	}
+	function get_project_config() {
+		return load_json(
+			path.join(source_path, "hdocbook-project.json"),
+			hdocbook_project,
+		);
+	}
+	function get_book_config() {
+		return load_json(
+			path.join(source_path, docId, "hdocbook.json"),
+			hdocbook_config,
+		);
+	}
+
 	// Render markdown SOURCE to HTML through the same pipeline as published output:
 	// expand_variables -> process_includes -> markdown-it (+ mermaid, tips, frontmatter).
 	//
@@ -236,45 +288,50 @@ exports.create_content_handler = (ctx) => {
 	// we will transform to HTML and return that
 	//
 	// Anything else in this handler will return a 404 error
-	function handle_books_request(req, res) {
-		let url = req.url.replace("/_books/", "/");
-
-		console.log("URL Requested:", url);
-
-		// Process redirect
-		if (
-			hdocbook_project.redirects &&
-			Array.isArray(hdocbook_project.redirects) &&
-			hdocbook_project.redirects.length > 0
-		) {
-			const source_url = url.indexOf("/") === 0 ? url : `/${url}`;
-			for (const redir of hdocbook_project.redirects) {
-				redir.url =
-					redir.url.indexOf("/") === 0 ? redir.url : `/${redir.url}`;
-				if (
-					redir.url === source_url &&
-					redir.location &&
-					redir.location !== ""
-				) {
-					url = `${redir.location}`;
-					console.log(`Redirecting to ${url}`);
+	async function handle_books_request(req, res) {
+		try {
+			let url = req.url.replace("/_books/", "/");
+
+			console.log("URL Requested:", url);
+
+			// Process redirect (config read fresh so redirect edits apply live)
+			const project_config = get_project_config();
+			if (
+				project_config.redirects &&
+				Array.isArray(project_config.redirects) &&
+				project_config.redirects.length > 0
+			) {
+				const source_url = url.indexOf("/") === 0 ? url : `/${url}`;
+				for (const redir of project_config.redirects) {
+					redir.url =
+						redir.url.indexOf("/") === 0 ? redir.url : `/${redir.url}`;
+					if (
+						redir.url === source_url &&
+						redir.location &&
+						redir.location !== ""
+					) {
+						url = `${redir.location}`;
+						console.log(`Redirecting to ${url}`);
+					}
 				}
 			}
-		}
 
-		const file_path = path.join(source_path, url);
-
-		if (path.extname(file_path) === ".html") {
-			// 1a. check for html files, and send/transform as required
-			if (fs.existsSync(file_path)) {
-				// HTML file exists on disk, just return it verbatim
-				res.setHeader("Content-Type", "text/html");
-				send_file(req, res, file_path);
-				return true;
+			const file_path = resolve_within_root(source_path, url);
+			if (file_path === null) {
+				send_content_resource_404(req, res);
+				return;
 			}
-			if (fs.existsSync(file_path.replace(".html", ".md"))) {
+
+			if (path.extname(file_path) === ".html") {
+				// 1a. check for html files, and send/transform as required
+				if (fs.existsSync(file_path)) {
+					// HTML file exists on disk, just return it verbatim
+					res.setHeader("Content-Type", "text/html");
+					send_file(req, res, file_path);
+					return;
+				}
 				if (
-					transform_markdown_and_send_html(
+					await transform_markdown_and_send_html(
 						req,
 						res,
 						file_path.replace(".html", ".md"),
@@ -282,22 +339,19 @@ exports.create_content_handler = (ctx) => {
 				) {
 					return;
 				}
-			}
-		} else if (path.extname(file_path) === ".md") {
-			// If the markdown file exists, just send to caller as is
-			if (fs.existsSync(file_path)) {
-				send_content_file(req, res, file_path);
-				return true;
-			}
-		} else if (path.extname(file_path).length === 0) {
-			// 2. If we request a file, without any file extension
-			if (fs.existsSync(`${file_path}.md`)) {
-				if (transform_markdown_and_send_html(req, res, `${file_path}.md`)) {
+			} else if (path.extname(file_path) === ".md") {
+				// If the markdown file exists, just send to caller as is
+				if (fs.existsSync(file_path)) {
+					send_content_file(req, res, file_path);
+					return;
+				}
+			} else if (path.extname(file_path).length === 0) {
+				// 2. If we request a file, without any file extension
+				if (await transform_markdown_and_send_html(req, res, `${file_path}.md`)) {
 					return;
 				}
-			} else if (fs.existsSync(path.join(`${file_path}index.md`))) {
 				if (
-					transform_markdown_and_send_html(
+					await transform_markdown_and_send_html(
 						req,
 						res,
 						path.join(file_path, "index.md"),
@@ -305,55 +359,61 @@ exports.create_content_handler = (ctx) => {
 				) {
 					return;
 				}
-			} else if (fs.existsSync(path.join(`${file_path}index.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}index.html`));
-				return;
-			} else if (fs.existsSync(`${file_path}/index.md`)) {
+				if (fs.existsSync(path.join(`${file_path}index.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}index.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}/index.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}/index.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}.htm`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}.htm`));
+					return;
+				}
+			} else if (fs.existsSync(file_path)) {
 				if (
-					transform_markdown_and_send_html(req, res, `${file_path}/index.md`)
+					file_path.endsWith("hdocbook.json") ||
+					file_path.endsWith("hdocbook_project.json")
 				) {
-					return;
+					try {
+						// Read & parse file
+						JSON.parse(fs.readFileSync(file_path));
+					} catch (e) {
+						console.error(`Error parsing hdocbook.json: ${e}`);
+					}
 				}
-			} else if (fs.existsSync(path.join(`${file_path}/index.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}/index.html`));
-				return;
-			} else if (fs.existsSync(path.join(`${file_path}.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}.html`));
-				return;
-			} else if (fs.existsSync(path.join(`${file_path}.htm`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}.htm`));
+				send_file(req, res, file_path);
 				return;
 			}
-		} else if (fs.existsSync(file_path)) {
-			if (
-				file_path.endsWith("hdocbook.json") ||
-				file_path.endsWith("hdocbook_project.json")
-			) {
-				try {
-					// Read & parse file
-					JSON.parse(fs.readFileSync(file_path));
-				} catch (e) {
-					console.error(`Error parsing hdocbook.json: ${e}`);
-				}
+
+			// Return a 404 error here
+			send_content_resource_404(req, res);
+		} catch (e) {
+			// A markdown render failure (bad include, plugin throw, etc.) lands
+			// here rather than as an unhandled promise rejection.
+			console.error(`Error handling content request ${req.url}:`, e);
+			if (!res.headersSent) {
+				res.status(500).send("Error rendering content");
 			}
-			send_file(req, res, file_path);
-			return;
 		}
-
-		// Return a 404 error here
-		send_content_resource_404(req, res);
 	}
 
 	function handle_library_request(req, res) {
+		const book_config = get_book_config();
 		const library = {
 			books: [
 				{
-					docId: hdocbook_config.docId,
-					title: hdocbook_config.title,
+					docId: book_config.docId,
+					title: book_config.title,
 					nav_inline: nav_inline,
 				},
 			],

package/hdoc-create.js

@@ -21,7 +21,9 @@
 		);
 		let hdocbook_project = {};
 		try {
-			hdocbook_project = require(hdocbook_project_config_path);
+			hdocbook_project = JSON.parse(
+				fs.readFileSync(hdocbook_project_config_path, "utf8"),
+			);
 		} catch (e) {
 			console.error(`File not found: ${hdocbook_project_config_path}\n`);
 			console.error(
@@ -36,7 +38,7 @@
 
 		let hdocbook = {};
 		try {
-			hdocbook = require(hdocbook_path);
+			hdocbook = JSON.parse(fs.readFileSync(hdocbook_path, "utf8"));
 		} catch (e) {
 			console.error(`File not found: ${hdocbook_path}\n`);
 			console.error(

package/hdoc-init.js

@@ -4,6 +4,15 @@
 	const fs = require("node:fs");
 	const path = require("node:path");
 
+	// Valid values come from the same schema the build validator harvests, so
+	// init can never scaffold a book that validate would reject.
+	const hdocbook_schema = require(
+		path.join(__dirname, "schemas", "hdocbook.schema.json"),
+	);
+	const valid_product_families =
+		hdocbook_schema.properties.productFamily.enum;
+	const valid_audience = hdocbook_schema.properties.audience.items.enum;
+
 	const promptProps = [
 		{
 			name: "id",
@@ -36,6 +45,29 @@
 			description: "Package Author",
 			required: true,
 		},
+		{
+			name: "productFamily",
+			description: `Product Family [${valid_product_families.join(", ")}]`,
+			default: "hdocs",
+			options: valid_product_families,
+			required: true,
+		},
+		{
+			name: "audience",
+			description: `Audience [${valid_audience.join(", ")}]`,
+			default: "public",
+			options: valid_audience,
+			required: true,
+		},
+		{
+			name: "bookType",
+			description:
+				"Book Type (0=document, 1=api_ref, 2=db_ref, 3=etl_ref, 4=mcp_ref)",
+			default: "0",
+			validator: /^[0-4]$/,
+			warning: "Book Type must be a number between 0 and 4.",
+			required: true,
+		},
 	];
 
 	// Asks a single question, re-prompting if the field is required and empty or if
@@ -55,6 +87,11 @@
 					ask();
 					return;
 				}
+				if (value && field.options && !field.options.includes(value)) {
+					console.error(`Value must be one of: ${field.options.join(", ")}`);
+					ask();
+					return;
+				}
 				resolve(value);
 			});
 		};
@@ -62,11 +99,38 @@
 	});
 
 	const createBook = (server_path, source_path, docProps) => {
+		// Refuse to scaffold over an existing book — re-running init in a
+		// populated folder used to silently overwrite template-named files.
+		const conflict_candidates = [
+			"hdocbook-project.json",
+			"package.json",
+			"gitignore",
+			".gitignore",
+			"_hdocbook",
+			docProps.id,
+		];
+		const conflicts = conflict_candidates.filter((f) =>
+			fs.existsSync(path.join(source_path, f)),
+		);
+		if (conflicts.length > 0) {
+			console.error(
+				"\r\nThe target folder already contains files that init would overwrite:\r\n",
+			);
+			for (const f of conflicts) console.error(`   ${f}`);
+			console.error(
+				"\r\nRun hdoc init in an empty folder, or remove these first.\r\n",
+			);
+			process.exit(1);
+		}
+
 		console.log("\r\nCreating book with the following properties:\r\n");
 		console.log("           Doc ID:", docProps.id);
 		console.log("            Title:", docProps.title);
 		console.log("      Description:", docProps.description);
 		console.log("           Author:", docProps.author);
+		console.log("   Product Family:", docProps.productFamily);
+		console.log("         Audience:", docProps.audience);
+		console.log("        Book Type:", docProps.bookType);
 		console.log("  Initial Version:", docProps.version, "\r\n");
 
 		// Now copy files over
@@ -92,79 +156,50 @@
 				process.exit(1);
 			}
 
+			// Synchronous read/modify/write of the three scaffolded JSON files —
+			// exits non-zero on failure instead of racing the process exit.
+			const update_json = (file_path, mutate) => {
+				try {
+					const obj = JSON.parse(fs.readFileSync(file_path, "utf8"));
+					mutate(obj);
+					fs.writeFileSync(file_path, JSON.stringify(obj, null, 2));
+					console.log("Updated:", file_path);
+				} catch (err) {
+					console.error("Error updating:", file_path, "\r\n", err);
+					process.exit(1);
+				}
+			};
+
 			// Update hdocbook-project.json
-			const hdocBookProjectFilePath = path.join(
-				source_path,
-				"hdocbook-project.json",
-			);
-			const hdocBookProjectFile = require(hdocBookProjectFilePath);
-			hdocBookProjectFile.docId = docProps.id;
-			fs.writeFile(
-				hdocBookProjectFilePath,
-				JSON.stringify(hdocBookProjectFile, null, 2),
-				function writeJSON(err) {
-					if (err)
-						return console.error(
-							"Error updating:",
-							hdocBookProjectFilePath,
-							"\r\n",
-							err,
-						);
-					console.log("Updated:", hdocBookProjectFilePath);
-				},
-			);
+			update_json(path.join(source_path, "hdocbook-project.json"), (obj) => {
+				obj.docId = docProps.id;
+			});
 
 			// Update root/hdocbook.json
-			const hdocBookFilePath = path.join(bookContentRoot, "hdocbook.json");
-			const hdocbookFile = require(hdocBookFilePath);
-			hdocbookFile.docId = docProps.id;
-			hdocbookFile.title = docProps.title;
-			hdocbookFile.description = docProps.description;
-			hdocbookFile.version = docProps.version;
-			hdocbookFile.publicSource = `https://github.com/Hornbill-Docs/${docProps.id}`;
-			hdocbookFile.navigation.items[0].items = [
-				{
-					text: "Welcome",
-					link: `${docProps.id}/index`,
-				},
-			];
-			fs.writeFile(
-				hdocBookFilePath,
-				JSON.stringify(hdocbookFile, null, 2),
-				function writeJSON(err) {
-					if (err)
-						return console.error(
-							"Error updating:",
-							hdocBookFilePath,
-							"\r\n",
-							err,
-						);
-					console.log("Updated:", hdocBookFilePath);
-				},
-			);
+			update_json(path.join(bookContentRoot, "hdocbook.json"), (obj) => {
+				obj.docId = docProps.id;
+				obj.title = docProps.title;
+				obj.description = docProps.description;
+				obj.version = docProps.version;
+				obj.publicSource = `https://github.com/Hornbill-Docs/${docProps.id}`;
+				obj.productFamily = docProps.productFamily;
+				obj.audience = [docProps.audience];
+				obj.bookType = Number(docProps.bookType);
+				obj.navigation.items[0].items = [
+					{
+						text: "Welcome",
+						link: `${docProps.id}/index`,
+					},
+				];
+			});
 
 			// Update package.json
-			const packageFilePath = path.join(source_path, "package.json");
-			const packageFile = require(packageFilePath);
-			packageFile.name = docProps.id;
-			packageFile.version = docProps.version;
-			hdocbookFile.description = docProps.description;
-			hdocbookFile.version = docProps.version;
-			hdocbookFile.author = docProps.author;
-			fs.writeFile(
-				packageFilePath,
-				JSON.stringify(packageFile, null, 2),
-				function writeJSON(err) {
-					if (err)
-						return console.error(
-							"Error updating:",
-							packageFilePath,
-							"\r\n",
-							err,
-						);
-					console.log("Updated:", packageFilePath);
-				},
-			);
+			update_json(path.join(source_path, "package.json"), (obj) => {
+				obj.name = docProps.id;
+				obj.version = docProps.version;
+				obj.description = docProps.description;
+				obj.author = docProps.author;
+			});
 
 			// Rename gitignore to .gitignore
 			const gitignorePath = path.join(source_path, "gitignore");

package/hdoc-module.js

@@ -290,6 +290,10 @@
 		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
@@ -1061,19 +1065,38 @@
 		return out.trimEnd();
 	};
 
-	exports.find_string_in_string = (fileContent, searchString) => {
+	// 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++) {
-		  const columnNumber = lines[lineNumber].indexOf(searchString);
-	  
-		  if (columnNumber !== -1) {
-			// Return 1-based line and column numbers
-			return { line: lineNumber + 1, column: columnNumber + 1 };
-		  }
+			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 };
+			}
 		}
-	  
-		// If not found, return null
-		return null;
-	  }
+
+		// No exact-boundary match — fall back to the first substring hit, or null
+		return loose_match;
+	}
 })();

package/hdoc-serve.js

@@ -4,9 +4,8 @@
 	const fs = require("node:fs");
 	const path = require("node:path");
 	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
-	const { create_content_handler, build_nav_inline } = require(
-		path.join(__dirname, "hdoc-content-routes.js"),
-	);
+	const { create_content_handler, build_nav_inline, resolve_within_root } =
+		require(path.join(__dirname, "hdoc-content-routes.js"));
 
 	let port = 3000;
 	let docId;
@@ -47,9 +46,12 @@
 			"hdocbook-project.json",
 		);
 
-		// Load the hdocbook config  file
+		// Load the hdocbook config file (readFileSync, not require — no module
+		// cache, and the content routes re-read it per request anyway)
 		try {
-			hdocbook_project = require(hdocbook_project_config_path);
+			hdocbook_project = JSON.parse(
+				fs.readFileSync(hdocbook_project_config_path, "utf8"),
+			);
 		} catch (e) {
 			console.error(`\nFailed to load hdocbook-project.json:\n${e}\n`);
 			process.exit(1);
@@ -72,7 +74,7 @@
 
 		// Pull in the book config file
 		try {
-			hdocbook_config = require(hdocbook_path);
+			hdocbook_config = JSON.parse(fs.readFileSync(hdocbook_path, "utf8"));
 		} catch (e) {
 			console.error(`\nFailed to load hdocbook.json:${e}\n`);
 			process.exit(1);
@@ -93,7 +95,11 @@
 		// Catch all
 		app.get("/{*splat}", (req, res) => {
 
-			const ui_file_path = path.join(ui_path, req.url);
+			const ui_file_path = resolve_within_root(ui_path, req.url);
+			if (ui_file_path === null) {
+				content.send_content_resource_404(req, res);
+				return;
+			}
 
 			// To support the SPA application behavior, if there is no file extension present, then
 			// we simply return the /index.html file content to the client

package/hdoc-stats.js

@@ -5,9 +5,10 @@
 	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
 
 
-	// Regex to remove Hornbill-specific tags
+	// Regex to remove Hornbill admonition markers (::: note etc — see
+	// custom_modules/tips.js) so the marker keywords don't inflate word counts.
 	const hbMDTagRegex =
-		/(:{3}[ ]note)|(:{3}[ ]tip)|(:{3}[ ]important)|(:{3}[ ]caution)|(:{3}[ ]warning)|(:{3})/g;
+		/(:{3}[ ]note)|(:{3}[ ]tip)|(:{3}[ ]important)|(:{3}[ ]info)|(:{3}[ ]caution)|(:{3}[ ]warning)|(:{3})/g;
 
 	const stats = {
 		totalMDFiles: 0,
@@ -42,15 +43,12 @@
 		}
 	};
 
-	const dreeOptions = {
-		descendants: true,
+	// Options for hdoc.scan_dir (see hdoc-module.js for the supported keys)
+	const scanOptions = {
 		depth: 10,
 		extensions: ["md", "html", "htm"],
-		hash: false,
 		normalize: true,
-		size: true,
 		sizeInBytes: true,
-		stat: false,
 		symbolicLinks: false,
 	};
 
@@ -105,12 +103,14 @@
 		});
 
 		// Scan content path directory, send file info to callback for processing
-		hdoc.scan_dir(bookPath, dreeOptions, fileCallback);
+		hdoc.scan_dir(bookPath, scanOptions, fileCallback);
 		for (const element of markdownFiles) {
 			// Load markdown file
 			const md_txt = fs.readFileSync(element.path, "utf8");
 
-			const html_txt = md.render(md_txt.toString());
+			const html_txt = md.render(
+				md_txt.toString().replace(hbMDTagRegex, ""),
+			);
 			const text = hdoc.html_to_text(html_txt);
 
 			// Do the wordcount and add to status