hdoc-tools 0.63.0 → 0.64.0

package/hdoc-content-routes.js

@@ -271,6 +271,20 @@ exports.create_content_handler = (ctx) => {
 		return `${header}\n${body}`;
 	}
 
+	// Render markdown source to the final page fragment exactly as the content
+	// route serves it — document header included (unless it's an _inline
+	// fragment). Used by the `hdoc serve -edit` live preview so the preview of
+	// an unsaved buffer matches what a saved page would render as.
+	async function render_page(file_path, md_source, logical_path) {
+		const { html, frontmatter, read_time } = await render_markdown(
+			file_path,
+			md_source,
+		);
+		return logical_path.includes("/_inline/")
+			? html
+			: wrap_with_document_header(html, frontmatter, logical_path, read_time);
+	}
+
 	async function transform_markdown_and_send_html(req, res, file_path) {
 		if (!fs.existsSync(file_path)) return false;
 
@@ -566,6 +580,7 @@ exports.create_content_handler = (ctx) => {
 		// handle_books_request / handle_library_request are exposed so the editor
 		// can register delegating /_books routes that follow a workspace switch.
 		render_markdown,
+		render_page,
 		transform_markdown_and_send_html,
 		send_content_file,
 		send_file,

package/hdoc-help.js

@@ -29,7 +29,7 @@ Commands
     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
+    Starts a local web server on port 3000, serving the content. Supports a -port N to use a different port. Right-click page content in the browser to edit the page inline and save back to disk (editing is available from the serving machine only; LAN viewers get read-only preview)
 
  - stats
     Returns statistics regarding the book you are working on. Supports a -v switch for verbose output.

package/hdoc-serve.js

@@ -3,6 +3,7 @@
 	const compression = require("compression");
 	const fs = require("node:fs");
 	const path = require("node:path");
+	const crypto = require("node:crypto");
 	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
 	const { create_content_handler, build_nav_inline, resolve_within_root } =
 		require(path.join(__dirname, "hdoc-content-routes.js"));
@@ -92,6 +93,154 @@
 		});
 		content.register(app);
 
+		// --- Inline edit mode (always on, loopback callers only) ---
+		//
+		// Mounts a minimal read/write/preview API consumed by the viewer's
+		// LOCAL PREVIEW PATCH script (ui/js/hdoc-edit-inline.js): right-click
+		// on page content opens a slide-over panel with the page's raw
+		// markdown; edits live-preview through the SAME render pipeline as
+		// published output, and Save writes the file back with an etag-based
+		// conflict check (mirrors hdoc-edit.js /api/pagefile). The server
+		// stays bound to 0.0.0.0 so read-only preview remains shareable on
+		// the LAN, but anything that can touch the book source must not be
+		// LAN-reachable — so every /_edit route is gated per request to
+		// loopback callers. LAN visitors probe /_edit/mode, get
+		// {enabled:false}, and the viewer never shows the edit UI.
+		{
+			const is_loopback = (req) => {
+				const a = req.socket.remoteAddress || "";
+				return a === "127.0.0.1" || a === "::1" || a === "::ffff:127.0.0.1";
+			};
+
+			const sha1 = (data) =>
+				crypto.createHash("sha1").update(Buffer.from(data)).digest("hex");
+
+			// Resolve a logical (extensionless, book-relative) page path to its
+			// backing markdown file, exactly as handle_books_request would:
+			// <path>.md first, then <path>/index.md. Only files inside the book
+			// content folder (<source_path>/<docId>/) are editable.
+			const resolve_page_md = (logical) => {
+				const clean = String(logical || "")
+					.split("?")[0]
+					.split("#")[0]
+					.replace(/\.(html|htm|md)$/i, "")
+					.replace(/^\/+/, "")
+					.replace(/\/+$/, "");
+				if (clean !== docId && !clean.startsWith(`${docId}/`)) return null;
+				const base = resolve_within_root(global_source_path, clean);
+				if (base === null) return null;
+				for (const abs of [`${base}.md`, path.join(base, "index.md")]) {
+					if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+						return {
+							abs,
+							rel: path
+								.relative(global_source_path, abs)
+								.split(path.sep)
+								.join("/"),
+							logical: clean,
+						};
+					}
+				}
+				return null;
+			};
+
+			app.use(express.json({ limit: "5mb" }));
+
+			// Probe: tells the viewer the edit UI should be shown. Answers
+			// {enabled:false} (rather than 403) for LAN callers so the viewer
+			// quietly stays read-only.
+			app.get("/_edit/mode", (req, res) => {
+				res.json({ enabled: is_loopback(req) });
+			});
+
+			// Every other /_edit route (source read, save, preview) is
+			// loopback-only — hard 403 for anything else.
+			app.use("/_edit", (req, res, next) => {
+				if (!is_loopback(req)) {
+					return res.status(403).json({ error: "loopback only" });
+				}
+				next();
+			});
+
+			// Raw markdown source of a page, with an etag for optimistic
+			// concurrency on save.
+			app.get("/_edit/source", (req, res) => {
+				const resolved = resolve_page_md(req.query.path);
+				if (!resolved) {
+					return res
+						.status(404)
+						.json({ error: "No markdown source found for this page" });
+				}
+				const content_txt = fs.readFileSync(resolved.abs, "utf8");
+				res.json({
+					file: resolved.rel,
+					content: content_txt,
+					etag: sha1(content_txt),
+				});
+			});
+
+			// Save the buffer back to disk. Refuses to overwrite a file that
+			// changed since it was loaded (baseEtag mismatch → 409).
+			app.put("/_edit/source", (req, res) => {
+				const resolved = resolve_page_md(req.query.path);
+				if (!resolved) {
+					return res
+						.status(404)
+						.json({ error: "No markdown source found for this page" });
+				}
+				const body = req.body || {};
+				if (typeof body.content !== "string") {
+					return res.status(400).json({ error: "Missing content" });
+				}
+				if (body.baseEtag) {
+					const current = fs.readFileSync(resolved.abs, "utf8");
+					if (sha1(current) !== body.baseEtag) {
+						return res
+							.status(409)
+							.json({ error: "conflict", etag: sha1(current) });
+					}
+				}
+				try {
+					fs.writeFileSync(resolved.abs, body.content, "utf8");
+				} catch (e) {
+					return res
+						.status(500)
+						.json({ error: String((e && e.message) || e) });
+				}
+				res.json({
+					ok: true,
+					file: resolved.rel,
+					bytes: Buffer.byteLength(body.content, "utf8"),
+					etag: sha1(body.content),
+				});
+			});
+
+			// Render an UNSAVED buffer to the final page fragment (document
+			// header included) through the shared pipeline, for live preview.
+			app.post("/_edit/preview", async (req, res) => {
+				const body = req.body || {};
+				const resolved = resolve_page_md(body.path);
+				if (!resolved) {
+					return res
+						.status(404)
+						.json({ error: "No markdown source found for this page" });
+				}
+				if (typeof body.content !== "string") {
+					return res.status(400).json({ error: "Missing content" });
+				}
+				try {
+					const html = await content.render_page(
+						resolved.abs,
+						body.content,
+						resolved.logical,
+					);
+					res.json({ html });
+				} catch (e) {
+					res.status(500).json({ error: String((e && e.message) || e) });
+				}
+			});
+		}
+
 		// Local preview serves exactly one book — skip the viewer's library home
 		// and land straight in the book.
 		app.get("/", (req, res) => {
@@ -147,12 +296,17 @@
 			content.send_content_resource_404(req, res);
 		});
 
+		// Preview stays shareable on the LAN (0.0.0.0); the /_edit write
+		// routes above are gated per request to loopback callers instead.
 		const server = app.listen(port, "0.0.0.0", () => {
 			const addr = server.address();
 			if (!addr) return;
 
 			console.log("Server listening at http://127.0.0.1:%s", addr.port);
 			console.log(`Document source path is: ${source_path}`);
+			console.log(
+				"Inline edit is available from this machine only (right-click page content in the browser).",
+			);
 
 			const _vars = ["{{DOC_ID}}", "{{BUILD_NUMBER}}", "{{BUILD_DATE}}"];
 			console.log("Server Vars:");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hdoc-tools",
-	"version": "0.63.0",
+	"version": "0.64.0",
 	"description": "Hornbill HDocBook Development Support Tool",
 	"main": "hdoc.js",
 	"bin": {

package/ui/js/bootstrap.js

@@ -81,7 +81,8 @@ function loadJS(arrFiles,callback)
             "js/webcomponents/hdocApprove.js",
             "js/doc.hornbill.js",
             "js/highlightjs/highlight.pack.js",
-            "js/highlightjs-badge.js"
+            "js/highlightjs-badge.js",
+            "js/hdoc-edit-inline.js" //-- LOCAL PREVIEW PATCH: inline edit for `hdoc serve` (no-op unless the server enables it) - keep on live-site re-sync
             ],function()
     {
         intialiseApp();