prolog-notebook 0.1.1 → 0.3.0

package/bin/prolog-notebook.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// The command line. Thin on purpose: argument parsing, files, and words for a
+// terminal. Everything it does lives in src/run.js and src/export.js, so a VS
+// Code "run all" and a future --check get the same behaviour without going
+// through a shell (869ectt38, 869ectt3e).
+import { createRequire } from 'node:module';
+import { readFileSync, writeFileSync } from 'node:fs';
+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 { exportSource } from '../src/export.js';
+import { runNotebook, DEFAULT_LIMIT } from '../src/run.js';
+
+// The engine is imported WHERE IT IS USED, never at the top. src/node.js pulls in
+// 5.9 MB of WebAssembly at module scope, so a static import here would mean that
+// `--help` on a broken install fails before it can print anything — and the two
+// commands most likely to be typed at a broken install are --help and --version.
+const engine = () => import('../src/node.js');
+
+// `prolog-notebook run --stdout file | head` closes the pipe while we are still
+// writing to it. That is the reader using the shell correctly, not an error, and
+// a command that answers it with an unhandled EPIPE and a stack trace is
+// complaining about being used properly.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (e) => {
+    if (e.code !== 'EPIPE') throw e;
+  });
+}
+
+// Only for swipl-wasm's own version: everything about THIS package is in
+// src/version.js, where a page can import it too.
+const require = createRequire(import.meta.url);
+
+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
+
+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.
+`;
+
+/**
+ * A runaway goal hangs this process — the engine is in-process here, so there is
+ * no thread left to notice (869ejgyax). Stated rather than implied, because the
+ * moment this runs a file someone else wrote it stops being an annoyance.
+ */
+const RUNAWAY_WARNING = 'note: a non-terminating goal will hang this command; it has no timeout yet (869ejgyax)';
+
+/**
+ * Who this is, and — the part that is not on anyone's disk — which Prolog it
+ * will run your chapters with.
+ *
+ * THE ENGINE LINE EARNS ITS 59 MILLISECONDS. swipl-wasm's own version says
+ * nothing about SWI's: 8.0.4 ships 10.1.10. A notebook's saved answers are only
+ * true of the engine that produced them, so this is the one fact here that a
+ * reader could not have looked up.
+ *
+ * An engine that will not load is REPORTED, not fatal. "I cannot start Prolog"
+ * is exactly what someone running --version to diagnose a broken install needs
+ * to be told, and exiting non-zero would hide it behind a shell error.
+ */
+async function version() {
+  // The same line the page shows in its panel: src/version.js, imported by both.
+  const lines = [banner()];
+  try {
+    const { createSession } = await engine();
+    const swipl = await prologVersion(await createSession());
+    const wasm = `swipl-wasm ${require('swipl-wasm/package.json').version}`;
+    lines.push(swipl ? `Powered by SWI-Prolog ${swipl}, ${wasm}` : `Powered by ${wasm}`);
+  } catch (e) {
+    // Not "powered by" anything, so it does not say so. Someone running this to
+    // find out why nothing works needs the reason, not a formula.
+    lines.push(`SWI-Prolog could not be started: ${e.message}`);
+  }
+  // Omitted rather than guessed at when there is neither a baked file nor a git
+  // repository — a line that says "unknown" three times is worse than no line.
+  lines.push(buildLine(currentBuild()));
+  // The blank line is deliberate: this is a banner, and a banner that runs into
+  // the next shell prompt reads as an error message.
+  return `${lines.join('\n')}\n\n`;
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (!args.length || args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.includes('--version') || args.includes('-V')) {
+    process.stdout.write(await version());
+    return 0;
+  }
+
+  const command = args.shift();
+  if (command !== 'run') {
+    process.stderr.write(`unknown command "${command}"\n\n${USAGE}`);
+    return 2;
+  }
+
+  const options = { limit: DEFAULT_LIMIT, stdout: false, quiet: false };
+  const files = [];
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--limit') {
+      const value = Number(args.shift());
+      if (!Number.isInteger(value) || value < 1) {
+        process.stderr.write('--limit takes a positive whole number\n');
+        return 2;
+      }
+      options.limit = value;
+    } else if (arg === '--stdout') options.stdout = true;
+    else if (arg === '--quiet') options.quiet = true;
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`unknown option "${arg}"\n\n${USAGE}`);
+      return 2;
+    } else files.push(arg);
+  }
+
+  if (!files.length) {
+    process.stderr.write('run needs at least one file\n');
+    return 2;
+  }
+  if (!options.quiet) process.stderr.write(`${RUNAWAY_WARNING}\n`);
+
+  // 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
+  // because of what the file before it happened to load.
+  const { createSession } = await engine();
+  const session = await createSession();
+  let status = 0;
+
+  for (const file of files) {
+    await session.restart();
+    status = Math.max(status, await runFile(file, session, options));
+  }
+  return status;
+}
+
+async function runFile(file, session, options) {
+  const name = basename(file);
+  let notebook;
+  let source;
+  try {
+    source = readFileSync(file, 'utf8');
+    notebook = parse(source);
+  } catch (e) {
+    // The parser's line numbers are the file's own, so its message is already
+    // the most useful thing anyone could say here.
+    process.stderr.write(`${file}: ${e instanceof NotebookError ? e.message : e.message}\n`);
+    return 1;
+  }
+
+  const { edits, failures, warnings } = await runNotebook(notebook, session, {
+    limit: options.limit,
+    onCell: (event) => {
+      if (options.quiet) return;
+      if (event.kind === 'program') {
+        process.stderr.write(`  ${event.ok ? '✓' : '✗'} ${event.id}\n`);
+        return;
+      }
+      const answers = event.error
+        ? `error: ${event.error}`
+        : `${event.solutions.length} solution${event.solutions.length === 1 ? '' : 's'}`
+          + (event.truncated ? ` (stopped at ${options.limit}, not exhausted)` : '');
+      process.stderr.write(`  ${event.error ? '✗' : '✓'} ${event.id} — ${answers}\n`);
+    },
+  });
+
+  for (const warning of warnings) process.stderr.write(`  ! ${warning.id}: ${warning.text}\n`);
+
+  if (failures.length) {
+    // NOTHING IS WRITTEN when a program cell failed to load. Every answer below
+    // it was produced against a chapter that does not exist, and writing those
+    // into the file would publish them as though they did.
+    for (const failure of failures) {
+      process.stderr.write(`${file}: cell ${failure.id} did not load: ${failure.error}\n`);
+    }
+    process.stderr.write(`${name}: not written\n`);
+    return 1;
+  }
+
+  const text = exportSource(notebook, edits);
+  if (options.stdout) {
+    process.stdout.write(text);
+    return 0;
+  }
+  if (text === source) {
+    if (!options.quiet) process.stderr.write(`${name}: unchanged\n`);
+    return 0;
+  }
+  writeFileSync(file, text);
+  if (!options.quiet) process.stderr.write(`${name}: written\n`);
+  return 0;
+}
+
+process.exitCode = await main(process.argv);

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "prolog-notebook",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Jupyter-style notebooks for Prolog. Runs in the browser, installs nothing.",
   "type": "module",
   "main": "./src/node.js",
+  "bin": {
+    "prolog-notebook": "./bin/prolog-notebook.mjs"
+  },
   "exports": {
     ".": "./src/node.js",
     "./browser": "./src/browser.js",
     "./engine": "./src/engine.js",
-    "./notebook.css": "./src/notebook.css"
+    "./format": "./src/format.js",
+    "./notebook.css": "./src/notebook.css",
+    "./page": "./src/page.js",
+    "./render": "./src/render.js",
+    "./session": "./src/session.js",
+    "./worker": "./src/worker.js",
+    "./run": "./src/run.js",
+    "./export": "./src/export.js"
   },
   "files": [
+    "bin",
     "src",
     "README.md",
     "LICENSE",
@@ -18,7 +29,7 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "example": "python3 -m http.server 8777",
+    "dev": "python3 -m http.server 8777",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -45,9 +56,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "swipl-wasm": "^8.0.4"
+    "markdown-it": "^15.0.0",
+    "swipl-wasm": "8.0.7"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "jsdom": "^29.1.1"
   }
 }

package/src/browser.js

@@ -1,25 +1,261 @@
-// Browser entry point. The swipl-wasm bundle is loaded by a <script> tag and
-// exposes a global SWIPL factory; keeping the load out of this module means the
-// 5.9 MB bundle is fetched by the page, not by a bundler.
-import { PrologSession } from './engine.js';
+// Browser entry point. The engine runs in a Web Worker, so a query that never
+// terminates costs the reader a click on Stop rather than the whole tab.
+//
+// The 5.9 MB swipl bundle is still fetched by the page's own URL rather than by a
+// bundler — the worker is told where to find it.
+import { ConsultLog, defaultCellName, unconsult } from './session.js';
 
 export * from './engine.js';
+export { ConsultLog } from './session.js';
 
-let session = null;
+const DEFAULT_SWIPL_URL = new URL(
+  '../node_modules/swipl-wasm/dist/swipl/swipl-bundle.js',
+  import.meta.url
+).href;
 
 /**
- * Boot (once) and return the shared session for this page.
- * @returns {Promise<PrologSession>}
+ * A session whose engine lives in a worker.
+ *
+ * Every method returns a promise. `abort()` terminates the worker outright and
+ * replays the consult log into a new one, which is the only thing that works: a
+ * thread blocked inside WASM cannot be asked politely to stop.
  */
-export function createSession(options = {}) {
-  if (!session) {
-    if (typeof globalThis.SWIPL !== 'function') {
-      throw new Error(
-        'swipl-wasm not found. Load it first, e.g.\n' +
-          '<script src="node_modules/swipl-wasm/dist/swipl/swipl-bundle.js"></script>'
-      );
+export class WorkerSession {
+  #worker = null;
+  #pending = new Map();
+  #nextId = 1;
+  #booting = null;
+  /** The one query allowed to hold a frame. See supersede(). */
+  #open = null;
+
+  constructor({ workerUrl, swiplUrl = DEFAULT_SWIPL_URL, engineUrl, options = {} } = {}) {
+    this.workerUrl = workerUrl ?? new URL('./worker.js', import.meta.url).href;
+    this.swiplUrl = swiplUrl;
+    // The worker imports the engine itself, so it needs an absolute URL: a
+    // relative specifier would resolve against the worker script, which may have
+    // been served from anywhere.
+    this.engineUrl = engineUrl ?? new URL('./engine.js', import.meta.url).href;
+    this.options = options;
+    this.log = new ConsultLog();
+  }
+
+  /** Boot the worker and the engine inside it. Idempotent. */
+  async start() {
+    if (this.#worker) return this;
+    if (this.#booting) return this.#booting;
+    this.#booting = (async () => {
+      this.#spawn();
+      await this.#send('boot', {
+        swiplUrl: this.swiplUrl,
+        engineUrl: this.engineUrl,
+        options: this.options,
+      });
+      this.#booting = null;
+      return this;
+    })();
+    return this.#booting;
+  }
+
+  async consult(text, name = defaultCellName()) {
+    await this.start();
+    const result = await this.#send('consult', { text, name });
+    if (result.ok) this.log.record(name, text);
+    return result;
+  }
+
+  /**
+   * Open a query. Nothing runs until the first `next()` or `all()`, so opening
+   * one is always safe even if the goal is a disaster.
+   */
+  query(goal) {
+    return new WorkerQuery(this, goal);
+  }
+
+  /**
+   * ONE OPEN SEQUENCE PER SESSION, and the reason is not tidiness.
+   *
+   * SWI keeps open queries on a stack and swipl-wasm enforces it: stepping or
+   * closing anything but the innermost throws "Attempt to access not innermost
+   * query". A page cannot promise the order — the order is whatever the reader
+   * clicks — so the constraint is met by construction instead: there is never
+   * more than one open query, which means the one being closed is always the
+   * innermost, which means the close is always legal (869epzqpc).
+   *
+   * Called at the moment a frame is about to be opened, never when the query
+   * OBJECT is made: a cell whose Run fails before it ever steps must not end
+   * someone else's sequence for nothing.
+   *
+   * @internal
+   */
+  async supersede() {
+    const previous = this.#open;
+    this.#open = null;
+    if (!previous) return;
+    await previous.close({ superseded: true });
+    // Said only after the frame is actually gone, so a listener that starts a new
+    // query cannot race the close it was told about.
+    previous.onSuperseded?.();
+  }
+
+  /** @internal a query's frame is gone — exhausted, closed, or died with the engine. */
+  release(query) {
+    if (this.#open === query) this.#open = null;
+  }
+
+  /** @internal a query has just taken the session's one frame. */
+  hold(query) {
+    this.#open = query;
+  }
+
+  /** Take one cell's clauses back out. See unconsult() in session.js. */
+  async unconsult(name) {
+    return unconsult(this, name);
+  }
+
+  /**
+   * Throw the engine away and rebuild it from the consult log.
+   *
+   * Terminating is not a last resort here, it is the mechanism: it reclaims the
+   * whole WASM heap as well as the stuck goal, so a memory blow-up and an
+   * infinite loop have the same cure.
+   *
+   * A `:- dynamic` cell's assert/retract state does not survive this, which is
+   * already the documented behaviour of "restart engine and run all"
+   * (format §8) rather than a new surprise.
+   */
+  async restart() {
+    this.#teardown(new Error('aborted'));
+    // Every frame died with the worker, so nothing is holding the session's.
+    this.#open = null;
+    await this.start();
+    for (const { name, text } of this.log) {
+      await this.#send('consult', { text, name });
+    }
+  }
+
+  /**
+   * Stop whatever is running. Identical to restart() here, and named separately
+   * because the two are different intentions: one rescues a page, the other
+   * throws away assert/retract state deliberately.
+   */
+  async abort() {
+    return this.restart();
+  }
+
+  async close() {
+    this.#teardown(new Error('session closed'));
+  }
+
+  #spawn() {
+    // Classic, not module: swipl-wasm has no ESM entry, and importScripts is the
+    // only way to get its global. See the comment at the top of worker.js.
+    this.#worker = new Worker(this.workerUrl);
+    this.#worker.onmessage = ({ data }) => {
+      const entry = this.#pending.get(data.id);
+      if (!entry) return;
+      this.#pending.delete(data.id);
+      if (data.ok) entry.resolve(data.value);
+      else entry.reject(new Error(data.error));
+    };
+    this.#worker.onerror = (event) => {
+      this.#teardown(new Error(event.message ?? 'worker failed'));
+    };
+  }
+
+  #teardown(reason) {
+    this.#open = null;
+    this.#worker?.terminate();
+    this.#worker = null;
+    this.#booting = null;
+    // Anything still waiting will never hear back, so say so rather than leaving
+    // a promise dangling forever — a silent hang is what this whole change exists
+    // to remove.
+    for (const { reject } of this.#pending.values()) reject(reason);
+    this.#pending.clear();
+  }
+
+  #send(op, args = {}) {
+    if (!this.#worker) return Promise.reject(new Error('worker is not running'));
+    const id = this.#nextId++;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#worker.postMessage({ id, op, ...args });
+    });
+  }
+
+  /** @internal */
+  send(op, args) {
+    return this.#send(op, args);
+  }
+}
+
+class WorkerQuery {
+  #qid = null;
+
+  constructor(session, goal) {
+    this.session = session;
+    this.goal = goal;
+    this.done = false;
+    // Ended by another query taking the session's one frame, rather than by its
+    // own search finishing. Kept apart from `done` because only one of the two
+    // may ever be written down as an exhausted search (format §6).
+    this.superseded = false;
+    /** Set by the caller to hear that its sequence was closed for another one. */
+    this.onSuperseded = null;
+  }
+
+  async #open() {
+    if (this.#qid === null) {
+      await this.session.start();
+      // Before the frame exists, never after: once a second query is open the
+      // first is no longer innermost and can never be closed at all.
+      await this.session.supersede();
+      this.#qid = await this.session.send('open', { goal: this.goal });
+      this.session.hold(this);
     }
-    session = PrologSession.create(globalThis.SWIPL, options);
+    return this.#qid;
   }
-  return session;
+
+  async next() {
+    if (this.done) return this.superseded ? { done: true, superseded: true } : { done: true };
+    const qid = await this.#open();
+    const result = await this.session.send('next', { qid });
+    // The worker forgets a query that reports done — swipl-wasm has closed it —
+    // so the frame is already back and nothing here needs to ask for it.
+    if (result.done) this.#finish();
+    return result;
+  }
+
+  async all(limit) {
+    if (this.done) return { solutions: [], truncated: false };
+    const qid = await this.#open();
+    this.#finish();
+    return this.session.send('all', { qid, limit });
+  }
+
+  async close({ superseded = false } = {}) {
+    if (superseded) this.superseded = true;
+    if (this.#qid === null || this.done) {
+      this.#finish();
+      return;
+    }
+    this.#finish();
+    await this.session.send('close', { qid: this.#qid });
+  }
+
+  #finish() {
+    this.done = true;
+    this.session.release(this);
+  }
+}
+
+let shared = null;
+
+/**
+ * Boot (once) and return the shared session for this page.
+ * @returns {Promise<WorkerSession>}
+ */
+export function createSession(options = {}) {
+  if (!shared) shared = new WorkerSession(options).start();
+  return shared;
 }

package/src/build-info.js

@@ -0,0 +1,94 @@
+// Which copy of this you are actually running.
+//
+// A version number answers "which release"; it does not answer "which of the
+// four things on this machine claiming to be 0.2.0". A published install, a
+// checkout with the branch still on it, and an npm-linked working copy with
+// uncommitted edits are three different programs, and a bug report against the
+// wrong one costs an afternoon.
+//
+// TWO STATES, NAMED, because they are not the same claim:
+//
+//   Build ccf8e5b, committed 2026-08-30, packaged 2026-08-30
+//   Working copy ccf8e5b (modified), committed 2026-08-30
+//
+// The first is baked in by the release workflow just before publish — git exists
+// there and does not exist inside an installed package. The second is read from
+// git at run time, and says `(modified)` when the tree has edits, because a bare
+// SHA over a dirty tree names a program that nobody has.
+//
+// NOTHING IS BUILT HERE. The package is plain ES modules, published as written,
+// so "packaged" is the honest word for the third date — there is no compiler and
+// no output to date-stamp. A working copy has no packaging time at all, which is
+// why the second state has two fields rather than three.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+/** Where prepack leaves the facts. Inside `src`, so `files` already ships it. */
+const BAKED = new URL('./build-info.json', import.meta.url);
+
+/**
+ * The provenance line, or null when nothing is known.
+ *
+ * Pure, so both states can be tested without a filesystem or a git repository.
+ *
+ * @param {{commit: string, committed: string, packaged?: string, modified?: boolean}|null} info
+ * @returns {string|null}
+ */
+export function buildLine(info) {
+  if (!info?.commit) return null;
+  if (info.packaged) {
+    return `Build ${info.commit}, committed ${info.committed}, packaged ${info.packaged}`;
+  }
+  return `Working copy ${info.commit}${info.modified ? ' (modified)' : ''}, committed ${info.committed}`;
+}
+
+/**
+ * What this copy is, from whichever of the two sources exists.
+ *
+ * Null rather than a guess when neither does — a tarball built before any of
+ * this existed, or a source tree with no history. A line that says "unknown"
+ * three times is worse than no line.
+ *
+ * @returns {{commit: string, committed: string, packaged?: string, modified?: boolean}|null}
+ */
+export function currentBuild() {
+  try {
+    const baked = JSON.parse(readFileSync(BAKED, 'utf8'));
+    if (baked?.commit) return baked;
+  } catch {
+    // No file, or a damaged one. Either way git is the better authority here.
+  }
+  return fromGit();
+}
+
+/**
+ * Ask git, which is only there in a working copy.
+ *
+ * `execFileSync` with fixed arguments and no shell. It costs about ten
+ * milliseconds and only ever runs in development, where the alternative is a
+ * command that cannot tell you which of your own commits it is.
+ */
+function fromGit() {
+  const root = new URL('..', import.meta.url);
+  const git = (...args) => execFileSync('git', ['-C', root.pathname, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+  try {
+    const [commit, committed] = git('log', '-1', '--format=%h %cs').split(' ');
+    return { commit, committed, modified: git('status', '--porcelain') !== '' };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The facts, as prepack writes them. Exported so the script that runs at pack
+ * time and the code that reads the result agree on the shape.
+ *
+ * @param {{commit: string, committed: string}} head
+ * @param {Date} [now]
+ */
+export function bakedFrom(head, now = new Date()) {
+  return { ...head, packaged: now.toISOString().slice(0, 10) };
+}

package/src/build-info.json

@@ -0,0 +1,5 @@
+{
+  "commit": "ca69c2a",
+  "committed": "2026-08-30",
+  "packaged": "2026-08-30"
+}