@rse/specbook 1.2.7 → 1.2.8

package/README.md

@@ -6,6 +6,8 @@ SpecBook
 
 **Markdown-based Specification Format**
 
+[specbook.tools](https://specbook.tools)
+
 [![github (author stars)](https://img.shields.io/github/stars/rse?logo=github&label=author%20stars&color=%233377aa)](https://github.com/rse)
 [![github (author followers)](https://img.shields.io/github/followers/rse?label=author%20followers&logo=github&color=%234477aa)](https://github.com/rse)
 

package/dst/specbook-cmd-export.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
 /*  Chokidar is aliased in "package.json", as Nunjucks declares the
     (unused) Chokidar 3 as an optional peer dependency and the current
     Chokidar under its plain name would raise a peer warning on install  */
@@ -56,16 +57,38 @@ export const parseOutputSpec = (spec) => {
 /*  the quiet period the observed files have to stay silent for before a
     burst of changes is coalesced into a single re-export  */
 const watchDelay = 1000;
+/*  the interval of the safety-net scan, which catches the changes the
+    file-system watcher missed: a watcher can die unnoticed -- macOS
+    tears down its FSEvents streams across a sleep/wake cycle -- and
+    would then leave the export stale for the rest of the process life  */
+const scanDelay = 30 * 1000;
+/*  take the modification time snapshot of the observed files, where an
+    absent file (a still missing artifact) is remembered as absent, too,
+    so its creation and removal are noticed like a modification  */
+const snapshot = (files) => {
+    const times = new Map();
+    for (const file of files) {
+        try {
+            times.set(file, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            times.set(file, 0);
+        }
+    }
+    return times;
+};
 /*  keep a specification export in sync with its sources, where "run"
     performs one export and returns the files to observe: the initial
     export is performed up-front and every observed change triggers a
     re-export once the sources fell silent again. The observed set is
     re-synchronized after every run, as an edit can add or drop an
     embedded asset. The returned promise settles once the initial export
-    is done, while the active watcher keeps the process alive afterwards  */
+    is done, while the active watcher and the safety-net scan keep the
+    process alive afterwards  */
 export const watchSpecification = async (run, verbose) => {
     /*  perform the regular export before entering the observe loop  */
     let observed = await run();
+    let times = snapshot(observed);
     const watcher = watch(observed, { ignoreInitial: true });
     verbose(`observing ${literal(observed.length)} specification file(s) for changes`);
     /*  report the failures of the observation itself, as an unhandled
@@ -80,6 +103,7 @@ export const watchSpecification = async (run, verbose) => {
         watcher.unwatch(observed.filter((file) => !files.includes(file)));
         watcher.add(files.filter((file) => !observed.includes(file)));
         observed = files;
+        times = snapshot(files);
     };
     /*  restart the quiet period on every change, so a burst collapses
         into a single re-export, and chain the runs onto each other, so a
@@ -88,7 +112,7 @@ export const watchSpecification = async (run, verbose) => {
         and hence silently ending the observe loop)  */
     let chain = Promise.resolve();
     let timer;
-    watcher.on("all", () => {
+    const schedule = () => {
         if (timer !== undefined)
             clearTimeout(timer);
         timer = setTimeout(() => {
@@ -98,7 +122,24 @@ export const watchSpecification = async (run, verbose) => {
                     (err instanceof Error ? err.message : String(err)), "none");
             });
         }, watchDelay);
-    });
+    };
+    watcher.on("all", schedule);
+    /*  compare the modification times regularly, so a change the
+        watcher never reported still reaches the export, and re-establish
+        the watchers on such a miss, as a watcher which lost a file never
+        regains it on its own and the following changes would be caught
+        by the scan only  */
+    setInterval(() => {
+        for (const [file, time] of snapshot(observed))
+            if (times.get(file) !== time) {
+                verbose(`observing missed the change of "${literal(file)}" ` +
+                    "-- re-establishing the file observation", "none");
+                watcher.unwatch(observed);
+                watcher.add(observed);
+                schedule();
+                break;
+            }
+    }, scanDelay);
 };
 /*  render a specification into the requested format, where "realtime"
     injects the client-side script of the live preview into the HTML  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.2.7",
+    "version":                             "1.2.8",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -54,7 +54,7 @@
         "globals":                         "17.12.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.2",
-        "@types/node":                     "26.4.1",
+        "@types/node":                     "26.5.0",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",
         "@types/ws":                       "8.18.1",