hdoc-tools 0.60.1 → 0.62.0

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-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");