hdoc-tools 0.57.1 → 0.57.3

package/hdoc-bump.js

@@ -1,123 +1,123 @@
-(() => {
-	const fs = require("node:fs");
-	const path = require("node:path");
-
-	exports.run = (source_path, bump_type) => {
-		if (
-			bump_type !== "patch" &&
-			bump_type !== "minor" &&
-			bump_type !== "major"
-		) {
-			console.error(`Unsupported bump type: ${bump_type}`);
-			process.exit(1);
-		}
-		console.log(`Bumping ${bump_type} book version...\n`);
-
-		// Get document ID
-		const hdocbook_project_config_path = path.join(
-			source_path,
-			"hdocbook-project.json",
-		);
-		let hdocbook_project;
-		try {
-			hdocbook_project = require(hdocbook_project_config_path);
-		} catch (e) {
-			console.error("File not found: hdocbook-project.json:");
-			console.error(e, "\n");
-			console.error("hdoc bump needs to be run in the root of a HDoc Book.\n");
-			process.exit(1);
-		}
-		const doc_id = hdocbook_project.docId;
-
-		const book_path = path.join(source_path, doc_id);
-		const hdocbook_path = path.join(book_path, "hdocbook.json");
-
-		let hdocbook_config;
-		try {
-			hdocbook_config = require(hdocbook_path);
-		} catch (e) {
-			console.error("File not found: hdocbook.json");
-			console.error(e, "\n");
-			console.error("hdoc bump needs to be run in the root of a HDoc Book.\n");
-			process.exit(1);
-		}
-		const initial_version = hdocbook_config.version;
-		const hdocbook_version = hdocbook_config.version.split(".");
-		if (hdocbook_version.length !== 3) {
-			console.error(
-				`Book version does not appear to be in a semantic versioning format: ${initial_version}`,
-			);
-			process.exit(1);
-		}
-
-		if (Number.isNaN(hdocbook_version[0])) {
-			console.error(
-				`Existing major version is not a number: ${hdocbook_version[0]}`,
-			);
-			process.exit(1);
-		}
-		if (Number.isNaN(hdocbook_version[1])) {
-			console.error(
-				`Existing minor version is not a number: ${hdocbook_version[1]}`,
-			);
-			process.exit(1);
-		}
-		if (Number.isNaN(hdocbook_version[2])) {
-			console.error(
-				`Existing patch version is not a number: ${hdocbook_version[2]}`,
-			);
-			process.exit(1);
-		}
-
-		switch (bump_type) {
-			case "major":
-				try {
-					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10) + 1;
-					hdocbook_version[1] = 0;
-					hdocbook_version[2] = 0;
-				} catch (e) {
-					console.error("Failed to update major version:");
-					console.error(e);
-					process.exit(1);
-				}
-				break;
-			case "minor":
-				try {
-					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10);
-					hdocbook_version[1] = Number.parseInt(hdocbook_version[1], 10) + 1;
-					hdocbook_version[2] = 0;
-				} catch (e) {
-					console.error("Failed to update minor version:");
-					console.error(e);
-					process.exit(1);
-				}
-				break;
-			default:
-				//case "patch" catered for with this default
-				try {
-					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10);
-					hdocbook_version[1] = Number.parseInt(hdocbook_version[1], 10);
-					hdocbook_version[2] = Number.parseInt(hdocbook_version[2], 10) + 1;
-				} catch (e) {
-					console.error("Failed to update patch version:");
-					console.error(e);
-					process.exit(1);
-				}
-				break;
-		}
-
-		hdocbook_config.version = hdocbook_version.join(".");
-
-		try {
-			fs.writeFileSync(hdocbook_path, JSON.stringify(hdocbook_config, null, 2));
-		} catch (e) {
-			console.error("Error writing bumped version to book config:", e);
-			process.exit(1);
-		}
-
-		console.log(
-			`Book version updated from ${initial_version} to ${hdocbook_config.version}\n`,
-		);
-		return true;
-	};
-})();
+(() => {
+	const fs = require("node:fs");
+	const path = require("node:path");
+
+	exports.run = (source_path, bump_type) => {
+		if (
+			bump_type !== "patch" &&
+			bump_type !== "minor" &&
+			bump_type !== "major"
+		) {
+			console.error(`Unsupported bump type: ${bump_type}`);
+			process.exit(1);
+		}
+		console.log(`Bumping ${bump_type} book version...\n`);
+
+		// Get document ID
+		const hdocbook_project_config_path = path.join(
+			source_path,
+			"hdocbook-project.json",
+		);
+		let hdocbook_project;
+		try {
+			hdocbook_project = require(hdocbook_project_config_path);
+		} catch (e) {
+			console.error("File not found: hdocbook-project.json:");
+			console.error(e, "\n");
+			console.error("hdoc bump needs to be run in the root of a HDoc Book.\n");
+			process.exit(1);
+		}
+		const doc_id = hdocbook_project.docId;
+
+		const book_path = path.join(source_path, doc_id);
+		const hdocbook_path = path.join(book_path, "hdocbook.json");
+
+		let hdocbook_config;
+		try {
+			hdocbook_config = require(hdocbook_path);
+		} catch (e) {
+			console.error("File not found: hdocbook.json");
+			console.error(e, "\n");
+			console.error("hdoc bump needs to be run in the root of a HDoc Book.\n");
+			process.exit(1);
+		}
+		const initial_version = hdocbook_config.version;
+		const hdocbook_version = hdocbook_config.version.split(".");
+		if (hdocbook_version.length !== 3) {
+			console.error(
+				`Book version does not appear to be in a semantic versioning format: ${initial_version}`,
+			);
+			process.exit(1);
+		}
+
+		if (Number.isNaN(hdocbook_version[0])) {
+			console.error(
+				`Existing major version is not a number: ${hdocbook_version[0]}`,
+			);
+			process.exit(1);
+		}
+		if (Number.isNaN(hdocbook_version[1])) {
+			console.error(
+				`Existing minor version is not a number: ${hdocbook_version[1]}`,
+			);
+			process.exit(1);
+		}
+		if (Number.isNaN(hdocbook_version[2])) {
+			console.error(
+				`Existing patch version is not a number: ${hdocbook_version[2]}`,
+			);
+			process.exit(1);
+		}
+
+		switch (bump_type) {
+			case "major":
+				try {
+					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10) + 1;
+					hdocbook_version[1] = 0;
+					hdocbook_version[2] = 0;
+				} catch (e) {
+					console.error("Failed to update major version:");
+					console.error(e);
+					process.exit(1);
+				}
+				break;
+			case "minor":
+				try {
+					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10);
+					hdocbook_version[1] = Number.parseInt(hdocbook_version[1], 10) + 1;
+					hdocbook_version[2] = 0;
+				} catch (e) {
+					console.error("Failed to update minor version:");
+					console.error(e);
+					process.exit(1);
+				}
+				break;
+			default:
+				//case "patch" catered for with this default
+				try {
+					hdocbook_version[0] = Number.parseInt(hdocbook_version[0], 10);
+					hdocbook_version[1] = Number.parseInt(hdocbook_version[1], 10);
+					hdocbook_version[2] = Number.parseInt(hdocbook_version[2], 10) + 1;
+				} catch (e) {
+					console.error("Failed to update patch version:");
+					console.error(e);
+					process.exit(1);
+				}
+				break;
+		}
+
+		hdocbook_config.version = hdocbook_version.join(".");
+
+		try {
+			fs.writeFileSync(hdocbook_path, JSON.stringify(hdocbook_config, null, 2));
+		} catch (e) {
+			console.error("Error writing bumped version to book config:", e);
+			process.exit(1);
+		}
+
+		console.log(
+			`Book version updated from ${initial_version} to ${hdocbook_config.version}\n`,
+		);
+		return true;
+	};
+})();

package/hdoc-edit.js

@@ -31,7 +31,7 @@
 	const { TocModel } = require(path.join(__dirname, "hdoc-toc.js"));
 	const { dialect_findings } = require(path.join(__dirname, "hdoc-spell.js"));
 
-	let port = 3000;
+	let port = 3001;
 
 	// editor_path is the directory containing the editor SPA. For the stub this
 	// is editor/ (a hand-written placeholder index.html). Once the React app is

package/hdoc-help.js

@@ -18,7 +18,8 @@ Commands
     Creates folder structure and markdown documents as defined in the HDocBook navigation item links
 
  - edit
-    Starts the local structure/content editor on port 3000 (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.
+    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

package/hdoc-spell.js

@@ -0,0 +1,61 @@
+// Dialect spell-check: flags British spellings and suggests the US form, using
+// the same `american-british-english-translator` the build uses (hdoc-validate),
+// so the editor and `hdoc validate` agree. Returns character-offset findings
+// suitable for editor underlines.
+
+let translator = null;
+
+function line_starts(text) {
+	const starts = [0];
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] === "\n") starts.push(i + 1);
+	}
+	return starts;
+}
+
+function escape_regex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Returns [{ from, to, word, suggestion, type: 'dialect' }] for British spellings,
+// skipping any word in `ignore` (case-insensitive).
+function dialect_findings(text, ignore = []) {
+	if (!translator) translator = require("american-british-english-translator");
+	const out = translator.translate(text, { british: true, spelling: true });
+	const ignore_set = new Set(ignore.map((w) => String(w).toLowerCase()));
+	const starts = line_starts(text);
+	const findings = [];
+
+	for (const line_key of Object.keys(out)) {
+		const line_no = Number.parseInt(line_key, 10);
+		if (!line_no) continue;
+		const line_start = starts[line_no - 1];
+		if (line_start === undefined) continue;
+		const line_end = line_no < starts.length ? starts[line_no] : text.length;
+		const line_text = text.slice(line_start, line_end);
+
+		for (const entry of out[line_key]) {
+			for (const word of Object.keys(entry)) {
+				if (ignore_set.has(word.toLowerCase())) continue;
+				const suggestion = entry[word]?.details;
+				if (!suggestion) continue;
+				const re = new RegExp(`\\b${escape_regex(word)}\\b`, "gi");
+				let m;
+				// eslint-disable-next-line no-cond-assign
+				while ((m = re.exec(line_text)) !== null) {
+					const from = line_start + m.index;
+					findings.push({
+						from,
+						to: from + m[0].length,
+						word: m[0],
+						suggestion,
+						type: "dialect",
+					});
+				}
+			}
+		}
+	}
+	return findings;
+}
+
+exports.dialect_findings = dialect_findings;

package/hdoc-toc.js

@@ -0,0 +1,442 @@
+// In-memory TOC working model for `hdoc edit`.
+//
+// Owns the book's navigation tree (hdocbook.json -> navigation.items) and the
+// node-identity scheme. Each node gets a permanent, opaque, per-book-unique id
+// (see README of the editor effort): identity is separated from location
+// (link/slug) and from order (1.2.3 numbering is derived at render time only).
+//
+// Identity strategy (Phase 1): on load we assign an id to every node that lacks
+// one, in memory. The model is the single source of truth for the editing
+// session, so ids stay stable across /api/toc reads. The first structural save
+// persists these ids back into hdocbook.json (lazy one-time migration).
+//
+// hdocbook.json is read with fs.readFileSync + JSON.parse (never require) because
+// the editor mutates it and require() would cache a stale copy.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+// Lowercase, URL-safe, no look-alike characters (drops 0/o/1/l/i). 30 symbols.
+const ID_ALPHABET = "23456789abcdefghjkmnpqrstvwxyz";
+const ID_LENGTH = 8;
+// Largest multiple of the alphabet size that fits in a byte, for unbiased
+// rejection sampling (256 -> 240 = 8 * 30).
+const ID_REJECT_THRESHOLD =
+	Math.floor(256 / ID_ALPHABET.length) * ID_ALPHABET.length;
+
+// Recognised image/asset extensions (for the Files browser + uploads).
+const IMAGE_EXTS = [
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".svg",
+	".webp",
+	".bmp",
+	".ico",
+	".avif",
+];
+
+// Classify a file by name for the Files tree: page (.md), image, or other.
+function kind_of(name) {
+	const lower = name.toLowerCase();
+	if (lower.endsWith(".md")) return "page";
+	if (IMAGE_EXTS.some((e) => lower.endsWith(e))) return "image";
+	return "other";
+}
+
+function random_id_char() {
+	// Rejection-sample a byte to avoid modulo bias across the 30-symbol alphabet.
+	for (;;) {
+		const b = crypto.randomBytes(1)[0];
+		if (b < ID_REJECT_THRESHOLD) return ID_ALPHABET[b % ID_ALPHABET.length];
+	}
+}
+
+// Generate an opaque id not present in `used` (a Set), and reserve it.
+function generate_id(used) {
+	for (let attempt = 0; attempt < 10000; attempt++) {
+		let id = "";
+		for (let i = 0; i < ID_LENGTH; i++) id += random_id_char();
+		if (!used.has(id)) {
+			used.add(id);
+			return id;
+		}
+	}
+	throw new Error("Unable to generate a unique node id");
+}
+
+class TocModel {
+	constructor(source_path, docId) {
+		this.source_path = source_path;
+		this.docId = docId;
+		this.hdocbook_path = path.join(source_path, docId, "hdocbook.json");
+		// True when we assigned ids that are not yet written to disk. The first
+		// save will persist them (handled by a future write endpoint).
+		this.ids_pending_persist = false;
+		// Optional hook: called as (absPath, content) after we write hdocbook.json,
+		// so a file watcher can suppress our own writes.
+		this.on_persist = null;
+		this.load();
+	}
+
+	// Re-read hdocbook.json from disk (e.g. after an external edit), keeping any
+	// existing ids and assigning ids to new nodes.
+	reload() {
+		this.load();
+	}
+
+	load() {
+		const raw = JSON.parse(fs.readFileSync(this.hdocbook_path, "utf8"));
+		this.raw = raw;
+		const nav =
+			raw.navigation && Array.isArray(raw.navigation.items)
+				? raw.navigation.items
+				: [];
+		this.items = nav;
+
+		// Pass 1: collect ids already present so generated ones never collide.
+		this.used_ids = new Set();
+		this._walk(nav, (n) => {
+			if (typeof n.id === "string" && n.id) this.used_ids.add(n.id);
+		});
+		// Pass 2: assign opaque ids to any node that lacks one.
+		this._walk(nav, (n) => {
+			if (!(typeof n.id === "string" && n.id)) {
+				n.id = generate_id(this.used_ids);
+				this.ids_pending_persist = true;
+			}
+		});
+	}
+
+	_walk(nodes, fn) {
+		for (const n of nodes) {
+			fn(n);
+			if (Array.isArray(n.items)) this._walk(n.items, fn);
+		}
+	}
+
+	// Resolve a leaf link (path without extension) to a source-relative file.
+	_resolve_file(link) {
+		const rel = `${link}.md`;
+		if (fs.existsSync(path.join(this.source_path, rel))) {
+			return { file: rel, fileExists: true };
+		}
+		const rel_index = path.join(link, "index.md");
+		if (fs.existsSync(path.join(this.source_path, rel_index))) {
+			return { file: rel_index, fileExists: true };
+		}
+		// Report the expected path even when missing, so the UI can flag it.
+		return { file: rel, fileExists: false };
+	}
+
+	// Find a node anywhere in the tree by its opaque id (or null).
+	find_node(id) {
+		let found = null;
+		this._walk(this.items, (n) => {
+			if (n.id === id) found = n;
+		});
+		return found;
+	}
+
+	// Resolve a node id to its source file. Returns null if the id is unknown.
+	// For a branch (or a leaf with no link) abs/file are null and exists is false.
+	resolve_file(id) {
+		const node = this.find_node(id);
+		if (!node) return null;
+		const link = typeof node.link === "string" ? node.link : null;
+		if (!link) {
+			return { node, link: null, file: null, abs: null, exists: false };
+		}
+		const r = this._resolve_file(link);
+		return {
+			node,
+			link,
+			file: r.file,
+			abs: path.join(this.source_path, r.file),
+			exists: r.fileExists,
+		};
+	}
+
+	// --- structural mutations (Phase 1b: nav-only — links/files never move) ---
+
+	// Locate a node by id: returns { node, parent (array), index } or null.
+	_locate(id) {
+		const search = (arr) => {
+			for (let i = 0; i < arr.length; i++) {
+				if (arr[i].id === id) return { node: arr[i], parent: arr, index: i };
+				if (Array.isArray(arr[i].items)) {
+					const found = search(arr[i].items);
+					if (found) return found;
+				}
+			}
+			return null;
+		};
+		return search(this.items);
+	}
+
+	// Is targetId the node itself or one of its descendants?
+	_contains(node, targetId) {
+		if (node.id === targetId) return true;
+		if (Array.isArray(node.items)) {
+			return node.items.some((c) => this._contains(c, targetId));
+		}
+		return false;
+	}
+
+	// Reorder/reparent a node. parentId null => top level. index is the insertion
+	// position in the destination AFTER the node has been removed from its old
+	// spot. Only navigation order/nesting changes; link/items/draft are preserved.
+	move(id, parentId, index) {
+		const loc = this._locate(id);
+		if (!loc) throw new Error(`Unknown node id: ${id}`);
+
+		let dest;
+		if (parentId === null || parentId === undefined) {
+			dest = this.items;
+		} else {
+			const parent = this.find_node(parentId);
+			if (!parent) throw new Error(`Unknown parent id: ${parentId}`);
+			if (!Array.isArray(parent.items)) {
+				throw new Error("Target node is a leaf and cannot contain children");
+			}
+			if (this._contains(loc.node, parentId)) {
+				throw new Error("Cannot move a node into its own subtree");
+			}
+			dest = parent.items;
+		}
+
+		loc.parent.splice(loc.index, 1);
+		let idx = typeof index === "number" ? index : dest.length;
+		idx = Math.max(0, Math.min(idx, dest.length));
+		dest.splice(idx, 0, loc.node);
+		this.persist();
+	}
+
+	// Rename a node's display label (text). No effect on link/slug or file.
+	rename(id, text) {
+		const node = this.find_node(id);
+		if (!node) throw new Error(`Unknown node id: ${id}`);
+		node.text = text;
+		this.persist();
+	}
+
+	// Set a node's draft flag.
+	set_draft(id, draft) {
+		const node = this.find_node(id);
+		if (!node) throw new Error(`Unknown node id: ${id}`);
+		node.draft = !!draft;
+		this.persist();
+	}
+
+	// Write the working model back to hdocbook.json in its native format
+	// (2-space indent, LF, no trailing newline). This is also where in-memory
+	// opaque ids first land on disk (the lazy one-time migration).
+	persist() {
+		if (!this.raw.navigation) this.raw.navigation = {};
+		this.raw.navigation.items = this.items;
+		const json = JSON.stringify(this.raw, null, 2);
+		fs.writeFileSync(this.hdocbook_path, json, "utf8");
+		this.ids_pending_persist = false;
+		if (this.on_persist) this.on_persist(this.hdocbook_path, json);
+	}
+
+	// --- pages on disk (decoupled from nav) ---
+
+	// Validate a source-relative path: it must live inside the book's docId
+	// folder, not traverse upward, and not touch special "_" folders/files.
+	// `exts` limits the allowed file extension (default .md for pages; pass null
+	// to allow any, or a list for assets). Returns { rel (normalised), abs }.
+	_safe_rel(rel, { dir = false, exts = [".md"] } = {}) {
+		if (typeof rel !== "string" || !rel.trim()) throw new Error("Missing path");
+		const norm = rel.split("\\").join("/").replace(/^\/+/, "");
+		const segs = norm.split("/").filter((s) => s.length > 0);
+		if (segs[0] !== this.docId) {
+			throw new Error(`Path must be inside the book folder: ${this.docId}`);
+		}
+		if (segs.includes("..") || segs.includes(".")) {
+			throw new Error("Invalid path");
+		}
+		if (segs.some((s) => s.startsWith("_"))) {
+			throw new Error("Cannot operate inside special (_) folders");
+		}
+		if (!dir && exts) {
+			const lower = norm.toLowerCase();
+			if (!exts.some((e) => lower.endsWith(e))) {
+				throw new Error(`File type not allowed (expected: ${exts.join(", ")})`);
+			}
+		}
+		const root = path.join(this.source_path, this.docId);
+		const abs = path.join(this.source_path, norm);
+		const within = path.relative(root, abs);
+		if (within.startsWith("..") || path.isAbsolute(within)) {
+			throw new Error("Path escapes the book");
+		}
+		return { rel: norm, abs };
+	}
+
+	// Source-relative files referenced by some nav leaf's link.
+	linked_files() {
+		const set = new Set();
+		this._walk(this.items, (n) => {
+			if (typeof n.link === "string" && n.link) {
+				const r = this._resolve_file(n.link);
+				if (r.file) set.add(r.file);
+			}
+		});
+		return set;
+	}
+
+	// Every file on disk under the book (excluding "_" folders), each tagged with
+	// its kind (page/image/other). Pages also carry a linked flag (in nav or not).
+	list_files() {
+		const linked = this.linked_files();
+		const root = path.join(this.source_path, this.docId);
+		const files = [];
+		const dirs = [];
+		const walk = (absDir) => {
+			for (const e of fs.readdirSync(absDir, { withFileTypes: true })) {
+				if (e.name.startsWith("_")) continue; // skip special folders/files
+				const abs = path.join(absDir, e.name);
+				const rel = path.relative(this.source_path, abs).split(path.sep).join("/");
+				if (e.isDirectory()) {
+					dirs.push(rel);
+					walk(abs);
+				} else {
+					const kind = kind_of(e.name);
+					files.push({
+						file: rel,
+						kind,
+						linked: kind === "page" ? linked.has(rel) : false,
+					});
+				}
+			}
+		};
+		if (fs.existsSync(root)) walk(root);
+		files.sort((a, b) => a.file.localeCompare(b.file));
+		dirs.sort((a, b) => a.localeCompare(b));
+		return { docId: this.docId, dirs, files };
+	}
+
+	create_file(rel, content = "") {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: false });
+		if (fs.existsSync(abs)) throw new Error("A file already exists at that path");
+		fs.mkdirSync(path.dirname(abs), { recursive: true });
+		fs.writeFileSync(abs, content, "utf8");
+		return r;
+	}
+
+	create_folder(rel) {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: true });
+		fs.mkdirSync(abs, { recursive: true });
+		return r;
+	}
+
+	// Delete any file (page, image, or other asset) inside the book.
+	delete_file(rel) {
+		const { abs, rel: r } = this._safe_rel(rel, { dir: false, exts: null });
+		if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+			throw new Error("File not found");
+		}
+		fs.unlinkSync(abs);
+		return r;
+	}
+
+	// Validate + return the absolute path for an uploaded image/asset.
+	resolve_upload(rel) {
+		return this._safe_rel(rel, { dir: false, exts: IMAGE_EXTS });
+	}
+
+	// --- nav create / remove (Phase 1c) ---
+
+	_dest_array(parentId) {
+		if (parentId === null || parentId === undefined) return this.items;
+		const parent = this.find_node(parentId);
+		if (!parent) throw new Error(`Unknown parent id: ${parentId}`);
+		if (!Array.isArray(parent.items)) {
+			throw new Error("Target node is a leaf and cannot contain children");
+		}
+		return parent.items;
+	}
+
+	_insert(dest, index, node) {
+		let idx = typeof index === "number" ? index : dest.length;
+		idx = Math.max(0, Math.min(idx, dest.length));
+		dest.splice(idx, 0, node);
+	}
+
+	// Add a nav leaf that links to an existing page.
+	create_leaf(parentId, index, text, link) {
+		const dest = this._dest_array(parentId);
+		const node = { id: generate_id(this.used_ids), text: text || "", link };
+		this._insert(dest, index, node);
+		this.persist();
+		return node.id;
+	}
+
+	// Add an empty nav section (branch container).
+	add_section(parentId, index, text) {
+		const dest = this._dest_array(parentId);
+		const node = { id: generate_id(this.used_ids), text: text || "", items: [] };
+		this._insert(dest, index, node);
+		this.persist();
+		return node.id;
+	}
+
+	// Remove a nav node (unlink). Returns the removed node so the caller can
+	// optionally delete its backing file.
+	remove_node(id) {
+		const loc = this._locate(id);
+		if (!loc) throw new Error(`Unknown node id: ${id}`);
+		loc.parent.splice(loc.index, 1);
+		this.persist();
+		return loc.node;
+	}
+
+	// Normalized tree for the editor UI. Numbering is derived from sibling
+	// position (1, 1.1, 1.2, 2, ...) and never stored.
+	to_dto() {
+		const walk = (nodes, prefix) =>
+			nodes.map((n, i) => {
+				const number = prefix ? `${prefix}.${i + 1}` : `${i + 1}`;
+				const base = {
+					id: n.id,
+					text: typeof n.text === "string" ? n.text : "",
+					number,
+					draft: n.draft === true,
+				};
+				if (Array.isArray(n.items)) {
+					return {
+						...base,
+						type: "branch",
+						expand: n.expand === true,
+						children: walk(n.items, number),
+					};
+				}
+				const link = typeof n.link === "string" ? n.link : null;
+				const resolved = link
+					? this._resolve_file(link)
+					: { file: null, fileExists: false };
+				return {
+					...base,
+					type: "leaf",
+					link,
+					file: resolved.file,
+					fileExists: resolved.fileExists,
+				};
+			});
+
+		return {
+			docId: this.docId,
+			title: typeof this.raw.title === "string" ? this.raw.title : "",
+			idsPendingPersist: this.ids_pending_persist,
+			tree: walk(this.items, ""),
+		};
+	}
+}
+
+exports.TocModel = TocModel;
+exports.generate_id = generate_id;
+exports.ID_ALPHABET = ID_ALPHABET;
+exports.ID_LENGTH = ID_LENGTH;

package/hdoc-validate-config.js

@@ -28,10 +28,13 @@
 			errors.push(`hdocbook.json: "${path}" must be an object`);
 			return;
 		}
-		check_extra_keys(item, ['text', 'link', 'expand', 'draft', 'items'], path, 'hdocbook.json', errors);
+		check_extra_keys(item, ['text', 'link', 'expand', 'draft', 'items', 'id'], path, 'hdocbook.json', errors);
 		if (!item.text || typeof item.text !== 'string') {
 			errors.push(`hdocbook.json: "${path}.text" is required and must be a non-empty string`);
 		}
+		if (item.id !== undefined && typeof item.id !== 'string') {
+			errors.push(`hdocbook.json: "${path}.id" must be a string`);
+		}
 		if (item.link !== undefined && typeof item.link !== 'string') {
 			errors.push(`hdocbook.json: "${path}.link" must be a string`);
 		}

package/hdoc-ver.js

@@ -1,43 +1,43 @@
-(() => {
-	const fs = require("node:fs");
-	const path = require("node:path");
-
-	exports.run = (source_path) => {
-		console.log("Retrieving book version...\n");
-
-		// Get document ID
-		const hdocbook_project_config_path = path.join(
-			source_path,
-			"hdocbook-project.json",
-		);
-		let hdocbook_project;
-		try {
-			hdocbook_project = require(hdocbook_project_config_path);
-		} catch (e) {
-			console.error("File not found: hdocbook-project.json:");
-			console.log(e, "\n");
-			console.error("hdoc ver needs to be run in the root of a HDoc Book.\n");
-			process.exit(1);
-		}
-		const doc_id = hdocbook_project.docId;
-
-		const book_path = path.join(source_path, doc_id);
-		const hdocbook_path = path.join(book_path, "hdocbook.json");
-
-		let hdocbook_config;
-		try {
-			hdocbook_config = require(hdocbook_path);
-		} catch (e) {
-			console.error("File not found: hdocbook.json");
-			console.log(e, "\n");
-			console.error("hdoc ver needs to be run in the root of a HDoc Book.\n");
-			process.exit(1);
-		}
-		if (hdocbook_config.version && hdocbook_config.version !== "") {
-			console.log(`Book version: ${hdocbook_config.version}\n`);
-		} else {
-			console.error("Error - this book has no version defined.\n");
-			process.exit(1);
-		}
-	};
-})();
+(() => {
+	const fs = require("node:fs");
+	const path = require("node:path");
+
+	exports.run = (source_path) => {
+		console.log("Retrieving book version...\n");
+
+		// Get document ID
+		const hdocbook_project_config_path = path.join(
+			source_path,
+			"hdocbook-project.json",
+		);
+		let hdocbook_project;
+		try {
+			hdocbook_project = require(hdocbook_project_config_path);
+		} catch (e) {
+			console.error("File not found: hdocbook-project.json:");
+			console.log(e, "\n");
+			console.error("hdoc ver needs to be run in the root of a HDoc Book.\n");
+			process.exit(1);
+		}
+		const doc_id = hdocbook_project.docId;
+
+		const book_path = path.join(source_path, doc_id);
+		const hdocbook_path = path.join(book_path, "hdocbook.json");
+
+		let hdocbook_config;
+		try {
+			hdocbook_config = require(hdocbook_path);
+		} catch (e) {
+			console.error("File not found: hdocbook.json");
+			console.log(e, "\n");
+			console.error("hdoc ver needs to be run in the root of a HDoc Book.\n");
+			process.exit(1);
+		}
+		if (hdocbook_config.version && hdocbook_config.version !== "") {
+			console.log(`Book version: ${hdocbook_config.version}\n`);
+		} else {
+			console.error("Error - this book has no version defined.\n");
+			process.exit(1);
+		}
+	};
+})();

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.57.1",
+	"version": "0.57.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "hdoc-tools",
-			"version": "0.57.1",
+			"version": "0.57.3",
 			"hasInstallScript": true,
 			"license": "ISC",
 			"dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.57.1",
+	"version": "0.57.3",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {
@@ -23,7 +23,9 @@
 		"hdoc-mermaid.js",
 		"hdoc-module.js",
 		"hdoc-serve.js",
+		"hdoc-spell.js",
 		"hdoc-stats.js",
+		"hdoc-toc.js",
 		"hdoc-validate.js",
 		"hdoc-validate-config.js",
 		"hdoc-ver.js",

package/validateNodeVer.js

@@ -1,17 +1,17 @@
-(() => {
-	const vers = process.versions;
-	const supportedVersion = 20;
-	if (vers?.node) {
-		if (Number.parseInt(vers.node, 10) < supportedVersion) {
-			console.log("\r\nHornbill HDocBook Tools\r\n");
-			console.error(
-				`\x1b[31mThis tool requires Node.js version >= ${supportedVersion}.x.\x1b[0m\r\n`,
-			);
-			process.exit(1);
-		}
-	} else {
-		console.log(
-			"\x1b[33mCould not read version of Node.js, continuing...\x1b[0m",
-		);
-	}
-})();
+(() => {
+	const vers = process.versions;
+	const supportedVersion = 20;
+	if (vers?.node) {
+		if (Number.parseInt(vers.node, 10) < supportedVersion) {
+			console.log("\r\nHornbill HDocBook Tools\r\n");
+			console.error(
+				`\x1b[31mThis tool requires Node.js version >= ${supportedVersion}.x.\x1b[0m\r\n`,
+			);
+			process.exit(1);
+		}
+	} else {
+		console.log(
+			"\x1b[33mCould not read version of Node.js, continuing...\x1b[0m",
+		);
+	}
+})();

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Hornbill Docs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.