prolog-notebook 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.4.0] — 2026-08-30
+
+### Added
+
+- **The CLI notices when it is out of date.** On real work — `run` — it asks npm at most once
+  a day whether there is something newer, and says nothing unless there is:
+
+      A newer Prolog Notebook is available: 0.4.0 → 0.5.0
+      Update with: npm i -g prolog-notebook
+
+  `--check-update` forces the question and answers it either way, including *you are on the
+  latest* — which the daily check deliberately never says, because a tool that congratulates
+  you on every command is one you learn to read past.
+
+  It stays out of the way by design: never for `--help` or `--version`, never under `--quiet`,
+  never when `CI` or `NO_UPDATE_NOTIFIER` is set, and never between the reader and their
+  answers — the request is started before the run and collected after it. The notice goes to
+  **stderr**, because `run --stdout` is a notebook going down a pipe.
+
+  A registry it cannot reach is reported once a day rather than on every command: silence
+  there would be indistinguishable from *you are up to date*, which is the one thing a broken
+  check must not look like. The answer is remembered in `~/.cache/prolog-notebook/`
+  (XDG-aware), not beside the package, because a global install is often read-only. A private
+  registry is honoured through npm's own `registry` config.
+
 ## [0.3.1] — 2026-08-30
 
 ### Changed

package/README.md

@@ -91,12 +91,20 @@ chapter changes nothing.
 | `--stdout` | print the result instead of writing the file |
 | `--quiet` | report only failures |
 | `--version` | the tool's version, **the SWI-Prolog version it will run your chapters with**, and the copyright |
+| `--check-update` | ask npm whether a newer one exists, and say so either way |
 
 Two things it will not do. A query stopped at the limit is written **without** a terminator,
 which is the format's way of saying the search was never exhausted — `false.` there would be a
 forgery. And if a program cell fails to load, nothing is written at all: every answer below it
 was produced against a chapter that does not exist.
 
+When it does real work it asks npm, at most once a day, whether there is a newer version, and
+says nothing unless there is. Never for `--help` or `--version`, never under `--quiet`, never
+when `CI` or `NO_UPDATE_NOTIFIER` is set, and never blocking the run. A registry it cannot
+reach is reported once a day rather than on every command — silence there would be
+indistinguishable from *you are up to date*. Ask outright with `--check-update` and it answers
+either way.
+
 It has no defence against a non-terminating goal yet — the engine runs in this process, so
 `loop :- loop.` hangs the command. Say the word `--limit` all you like; a runaway *consult* is
 not a solution count. Fixing it properly means a worker thread, and it is the prerequisite for

package/bin/prolog-notebook.mjs

@@ -9,7 +9,8 @@ import { basename } from 'node:path';
 import { parse, NotebookError } from '../src/format.js';
 import { prologVersion } from '../src/engine.js';
 import { buildLine, currentBuild } from '../src/build-info.js';
-import { banner } from '../src/version.js';
+import { banner, VERSION } from '../src/version.js';
+import { updateNotice } from '../src/update.js';
 import { exportSource } from '../src/export.js';
 import { runNotebook, DEFAULT_LIMIT } from '../src/run.js';
 
@@ -38,11 +39,12 @@ const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
   prolog-notebook run <file.prolog.md>...   run every cell, write the answers back
 
 Options
-  --limit <n>   solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
-  --stdout      print the result instead of writing the file
-  --quiet       report only failures
-  --version     version, engine and copyright
-  -h, --help    this
+  --limit <n>     solutions to take from one query before stopping (default ${DEFAULT_LIMIT})
+  --stdout        print the result instead of writing the file
+  --quiet         report only failures
+  --version       version, engine and copyright
+  --check-update  ask npm whether a newer one exists, and say so either way
+  -h, --help      this
 
 A query that stops at the limit is written without a terminator, which is the
 format's way of saying the search was never exhausted. Nothing is invented.
@@ -96,10 +98,21 @@ async function main(argv) {
     return 0;
   }
   if (args.includes('--version') || args.includes('-V')) {
+    // No update check here, deliberately: --version and --help are what someone
+    // types at an install that is not working, and they stay instant and offline.
     process.stdout.write(await version());
     return 0;
   }
 
+  // Asked for explicitly. On its own it is the whole command; alongside `run` it
+  // forces the check that would otherwise wait for the day to turn over.
+  const asked = args.includes('--check-update');
+  if (asked && args.filter((a) => !a.startsWith('-')).length === 0) {
+    const notice = await updateNotice({ version: VERSION, force: true });
+    process.stderr.write(`${notice}\n`);
+    return 0;
+  }
+
   const command = args.shift();
   if (command !== 'run') {
     process.stderr.write(`unknown command "${command}"\n\n${USAGE}`);
@@ -119,6 +132,7 @@ async function main(argv) {
       options.limit = value;
     } else if (arg === '--stdout') options.stdout = true;
     else if (arg === '--quiet') options.quiet = true;
+    else if (arg === '--check-update') { /* handled above, and not a file */ }
     else if (arg.startsWith('-')) {
       process.stderr.write(`unknown option "${arg}"\n\n${USAGE}`);
       return 2;
@@ -131,6 +145,18 @@ async function main(argv) {
   }
   if (!options.quiet) process.stderr.write(`${RUNAWAY_WARNING}\n`);
 
+  // STARTED NOW, READ AT THE END. The registry is somebody else's machine on
+  // somebody else's network, and none of that should stand between the reader
+  // and their answers — so the question is asked while the work happens and the
+  // answer is collected once it is done.
+  //
+  // Not asked at all under --quiet, unless it was asked for outright: --quiet
+  // means "report only failures", and news about a newer version is not one. Not
+  // starting the request is better than starting it and discarding the answer.
+  const update = options.quiet && !asked
+    ? Promise.resolve(null)
+    : updateNotice({ version: VERSION, force: asked }).catch(() => null);
+
   // One engine for the whole invocation, restarted between files. A notebook is
   // a world of its own — one cell is one virtual file, and two chapters may
   // define the same predicate — so carrying clauses across would let a file pass
@@ -143,6 +169,11 @@ async function main(argv) {
     await session.restart();
     status = Math.max(status, await runFile(file, session, options));
   }
+
+  // stderr, always: `run --stdout` is a notebook going down a pipe, and a version
+  // notice in the middle of it would corrupt the file it is printing.
+  const notice = await update;
+  if (notice) process.stderr.write(`${notice}\n`);
   return status;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.",
   "type": "module",
   "main": "./src/node.js",

package/src/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "82ab5c7",
-  "built": "2026-08-30 14:50:00 UTC"
+  "commit": "0e3e8fa",
+  "built": "2026-08-30 15:12:30 UTC"
 }

package/src/update.js

@@ -0,0 +1,158 @@
+// Is there a newer one? Asked at most once a day, answered quietly, and never in
+// the way (869erkqpc).
+//
+// THE RULES, because an update notifier is the easiest thing in a CLI to make
+// annoying:
+//
+// - It says NOTHING when you are up to date. A tool that congratulates you on
+//   every command is one you learn to read past, and then it is not there when
+//   it has something to say. `--check-update` is the exception: you asked, so it
+//   answers either way.
+// - It never runs for `--help` or `--version`. Those are what someone types at a
+//   broken install, and they must stay instant and offline.
+// - It never runs in CI, and honours NO_UPDATE_NOTIFIER. `--check` will run this
+//   command on every push one day; a build that fails because a registry was slow
+//   is worse than no notice at all.
+// - A registry it cannot reach is said ONCE A DAY, not on every command. Silence
+//   there would be indistinguishable from "you are up to date", which is the one
+//   thing a broken check must not look like — but a proxy that blocks npm should
+//   not put a line of red in front of somebody on every run either.
+// - Everything else that can go wrong is silent: no cache directory, a registry
+//   that answers with nonsense. None of it is the reader's problem.
+//
+// The clock, the cache and "what is the latest version" are all arguments, so
+// everything above is tested without touching the wire; the fetch itself is the
+// only part that ever does.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const DAY = 24 * 60 * 60 * 1000;
+
+/** The npm registry's smallest useful answer: one document, one field. */
+export const REGISTRY = 'https://registry.npmjs.org';
+
+/**
+ * Where the last answer is remembered.
+ *
+ * XDG when it is set, `~/.cache` otherwise. Not beside the package: a global
+ * install is often read-only, and a check that needs write access to node_modules
+ * is a check that quietly stops happening.
+ */
+export function cachePath(env = process.env, home = homedir()) {
+  const base = env.XDG_CACHE_HOME || join(home, '.cache');
+  return join(base, 'prolog-notebook', 'update-check.json');
+}
+
+/** Reading and writing that file, and shrugging when it cannot. */
+export function fileStore(path = cachePath()) {
+  return {
+    read() {
+      try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+      } catch {
+        return null;
+      }
+    },
+    write(state) {
+      try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(state));
+      } catch {
+        // A read-only or missing home directory means the check happens every
+        // time instead of once a day. That is a slower notifier, not a failure.
+      }
+    },
+  };
+}
+
+/**
+ * Ask the registry which version is `latest`.
+ *
+ * The abbreviated document rather than the full packument: the full one carries
+ * every version ever published and can be megabytes, for a question with a
+ * one-line answer.
+ *
+ * @returns {Promise<string|null>} null for anything that goes wrong
+ */
+export async function latestFromRegistry({
+  // A private registry is a fact about the machine, not about this package, so
+  // npm's own setting is honoured before the default — and an explicit override
+  // exists because a test needs somewhere to point that is not the internet.
+  registry = process.env.PROLOG_NOTEBOOK_REGISTRY || process.env.npm_config_registry || REGISTRY,
+  name = 'prolog-notebook',
+  timeout = 2000,
+  fetchImpl = fetch,
+} = {}) {
+  try {
+    const base = String(registry).replace(/\/+$/, '');
+    const response = await fetchImpl(`${base}/${name}/latest`, {
+      headers: { accept: 'application/vnd.npm.install-v1+json' },
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    return typeof body?.version === 'string' ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Newer, older, or the same — by the numbers only.
+ *
+ * A prerelease is never newer than the release it precedes, and comparing them
+ * properly is a semver library's job. This one is deciding whether to print a
+ * sentence, so `0.4.0-rc.1` is simply not an upgrade from `0.3.1`.
+ */
+export function isNewer(latest, current) {
+  if (/-/.test(String(latest))) return false;
+  const parts = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10));
+  const [a, b] = [parts(latest), parts(current)];
+  if (a.some(Number.isNaN) || b.some(Number.isNaN)) return false;
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+
+/**
+ * The line to print, or null for silence.
+ *
+ * @param {object} options
+ * @param {string} options.version what this copy is
+ * @param {boolean} [options.force] the reader asked, so answer either way
+ * @param {number} [options.now]
+ * @param {number} [options.ttl]
+ * @param {{read: Function, write: Function}} [options.store]
+ * @param {() => Promise<string|null>} [options.latest]
+ * @param {object} [options.env]
+ * @returns {Promise<string|null>}
+ */
+export async function updateNotice({
+  version,
+  force = false,
+  now = Date.now(),
+  ttl = DAY,
+  store = fileStore(),
+  latest = latestFromRegistry,
+  env = process.env,
+} = {}) {
+  if (!force && (env.CI || env.NO_UPDATE_NOTIFIER)) return null;
+
+  const remembered = store.read();
+  const fresh = !force && remembered && now - remembered.checked < ttl;
+  const newest = fresh ? remembered.latest : await latest();
+  // A failed attempt is remembered too, so an offline machine asks once a day and
+  // says so once a day, rather than asking — and complaining — on every command.
+  if (!fresh) store.write({ checked: now, latest: newest ?? null });
+
+  if (!newest) {
+    return fresh && !force ? null : 'Could not reach the npm registry to check for updates.';
+  }
+  if (isNewer(newest, version)) {
+    return `A newer Prolog Notebook is available: ${version} → ${newest}\n`
+      + 'Update with: npm i -g prolog-notebook';
+  }
+  return force ? `Prolog Notebook ${version} is the latest.` : null;
+}

package/src/version.js

@@ -10,7 +10,7 @@
 export const NAME = 'Prolog Notebook';
 
 /** Must equal package.json's `version` — test/run.test.mjs enforces it. */
-export const VERSION = '0.3.1';
+export const VERSION = '0.4.0';
 
 /** The two facts a licence notice is actually made of. */
 export const YEAR = '2026';