prolog-notebook 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [0.6.5] — 2026-08-31
+
+Both from one field report on a real chapter.
+
+### Fixed
+
+- **`Attempt to access not innermost query` on a perfectly ordinary Run.** Loading the program
+  cells above a query emits `consulted`, which is exactly what `rerun="auto"` waits for — so an
+  auto cell's re-run was queued and ran while the manual run was still inside its awaits. It
+  asked whether anybody was mid-sequence, saw nobody, and opened its query underneath the one
+  about to be opened. One engine allows one open query, and whichever is not innermost cannot
+  be stepped, so the reader — who had pressed Run on one cell and touched nothing else — got
+  SWI's own words for a stack they are never supposed to meet.
+
+  A cell now claims the engine when its run **starts**, not when it succeeds. Two supporting
+  changes close the same class: the engine's version probe is awaited during boot rather than
+  fired beside the reader's first Run, and `all()` holds the session's one slot until the
+  worker has answered rather than releasing it up front.
+
+- **No way to clear your own answers in a chapter that shipped without any.** The outputs row
+  removed itself when the FILE had no saved answers — but that argument dies the moment a
+  reader presses Run, and a chapter published unrun is most chapters while an author is still
+  writing. The row now exists whenever there is a query cell, and counts what is on the page
+  rather than what is in the file: *No outputs yet*, *3 outputs on this page*, *3 outputs
+  cleared*.
+
+  The hide row above it stays keyed to the file, and correctly — hiding is for the chapter's
+  saved answers, and a reader's own run is not a spoiler.
+
+## [0.6.4] — 2026-08-31
+
+### Changed
+
+- **`prolog-notebook <command> --help` answers about that command only.** It printed the whole
+  card — all five commands — which makes the reader find their command again in a page they did
+  not ask for. What works anywhere is still listed, because it is as true of the command they
+  asked about as of any other, and the note about a stopped search now travels with `--limit`
+  rather than sitting under everything.
+
+  It works wherever the command is named: `view --help`, `--help view`, and
+  `view chapter.prolog.md -h` all ask the same question, as do the `run` and `exec` aliases.
+  Name no command, or one that does not exist, and the whole card comes back as before.
+
+- **The help, the per-command help and the misplaced-option message are derived from one
+  table.** They were three lists kept by hand, which is how the help came to advertise
+  `--check-update` under no command while three of the four commands refused it.
+
 ## [0.6.3] — 2026-08-30
 
 `prolog-notebook build lists.prolog.md --check-update` answered *unknown option* — on a flag the

package/README.md

@@ -149,7 +149,7 @@ Three work anywhere, because they are about the tool rather than about a noteboo
 |---|---|
 | `--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 — forced, whatever the daily check thinks, and answered even down a pipe |
-| `-h`, `--help` | the same list, from the command itself |
+| `-h`, `--help` | help for the command you named, or all of them if you named none |
 
 ```sh
 prolog-notebook upgrade      # fetch the latest

package/bin/prolog-notebook.mjs

@@ -38,57 +38,112 @@ for (const stream of [process.stdout, process.stderr]) {
 const require = createRequire(import.meta.url);
 
 /**
- * EACH OPTION UNDER THE COMMAND THAT TAKES IT (869erqra0).
+ * THE COMMANDS, AND WHAT EACH ONE TAKES — one table, three readers (869erqra0).
  *
- * They were listed in one flat `Options` block with no owner, which reads as a
- * promise that every one of them works everywhere — so `build --check-update`
- * was a reasonable thing to type and `unknown option` was a strange thing to be
- * told. Only three of them are actually the tool's rather than a command's, and
- * now only those three are listed as such.
+ * The whole help, a single command's help, and the message a misplaced option
+ * gets are all derived from here. They were three lists kept by hand, which is
+ * how the help came to advertise flags that no command accepted.
+ *
+ * Options belong to COMMANDS, not to the tool. Listing them in one flat block
+ * reads as a promise that every one works everywhere, and only three of them do.
  */
-const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
-
-  prolog-notebook view <file.prolog.md>       read it in a browser, cells and all
-    --port <n>      what it listens on (default 8777)
-    --no-open       print the URL instead of opening a browser
-
-  prolog-notebook build <file.prolog.md>      write a page you can host or send
-    --out <dir>     where it writes (default: <file>-site)
-
-  prolog-notebook execute <file.prolog.md>... run every query, write the answers in
-    --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
+const COMMANDS = {
+  view: {
+    usage: 'prolog-notebook view <file.prolog.md>',
+    blurb: 'read it in a browser, cells and all',
+    options: [
+      ['--port <n>', 'what it listens on (default 8777)'],
+      ['--no-open', 'print the URL instead of opening a browser'],
+    ],
+  },
+  build: {
+    usage: 'prolog-notebook build <file.prolog.md>',
+    blurb: 'write a page you can host or send',
+    options: [['--out <dir>', 'where it writes (default: <file>-site)']],
+  },
+  execute: {
+    usage: 'prolog-notebook execute <file.prolog.md>...',
+    blurb: 'run every query, write the answers in',
+    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'],
+    ],
+    // Belongs to --limit, so it goes wherever --limit goes and nowhere else.
+    note: 'A query that stops at the limit is written without a terminator, which is the\n'
+      + "format's way of saying the search was never exhausted. Nothing is invented.\n",
+  },
+  clear: {
+    usage: 'prolog-notebook clear <file.prolog.md>...',
+    blurb: 'take the answers back out',
+    options: [
+      ['--stdout', 'print the result instead of writing the file'],
+      ['--quiet', 'report only failures'],
+    ],
+  },
+  upgrade: {
+    usage: 'prolog-notebook upgrade',
+    blurb: 'fetch the latest version',
+    options: [],
+  },
+};
 
-  prolog-notebook clear <file.prolog.md>...   take the answers back out
-    --stdout        print the result instead of writing the file
-    --quiet         report only failures
+/** `exec` and `run` reach `execute` and are deliberately undocumented (869erp0jd). */
+const ALIASES = { exec: 'execute', run: 'execute' };
 
-  prolog-notebook upgrade                     fetch the latest version
+/** The command this argument names, aliases resolved, or null. */
+const commandNamed = (arg) => (COMMANDS[arg] ? arg : ALIASES[arg] ?? null);
 
-Anywhere
+const ANYWHERE = `Anywhere
   --check-update  ask npm whether a newer one exists, and say so either way
   --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.
 `;
 
+/** One command, laid out exactly as it is laid out in the full help. */
+function commandHelp(name) {
+  const { usage, blurb, options } = COMMANDS[name];
+  return [`  ${usage.padEnd(44)}${blurb}`]
+    .concat(options.map(([flag, what]) => `    ${flag.padEnd(16)}${what}`))
+    .join('\n');
+}
+
+const USAGE = `prolog-notebook — Jupyter-style notebooks for Prolog
+
+${Object.keys(COMMANDS).map(commandHelp).join('\n\n')}
+
+${ANYWHERE}
+${COMMANDS.execute.note}`;
+
+/**
+ * JUST THE COMMAND ASKED ABOUT (869erqra0).
+ *
+ * The Captain, on being shown all five for `build --help`: "not really. If I run
+ * prolog-notebook cmd --help I want only help on that cmd." Printing everything
+ * makes the reader find their command again in a page they did not ask for.
+ *
+ * What works anywhere stays, because it is true of the command they asked about
+ * as much as of any other.
+ */
+function helpFor(name) {
+  const { note } = COMMANDS[name];
+  return `${commandHelp(name)}\n\n${ANYWHERE}${note ? `\n${note}` : ''}`;
+}
+
 /**
  * Which command each option belongs to, so a misplaced one can say where it lives.
  *
+ * Derived, so a flag added to a command above cannot be forgotten here.
  * `unknown option "--limit"` is true and unhelpful when the flag is real and two
- * lines further up the same help. This costs a lookup table and saves a re-read.
+ * lines further up the same help.
  */
-const BELONGS_TO = {
-  '--limit': 'execute',
-  '--stdout': 'execute and clear',
-  '--quiet': 'execute and clear',
-  '--out': 'build',
-  '--port': 'view',
-  '--no-open': 'view',
-};
+const BELONGS_TO = {};
+for (const [name, { options }] of Object.entries(COMMANDS)) {
+  for (const [flag] of options) {
+    const bare = flag.split(' ')[0];
+    BELONGS_TO[bare] = BELONGS_TO[bare] ? `${BELONGS_TO[bare]} and ${name}` : name;
+  }
+}
 
 function unknownOption(arg, command) {
   const home = BELONGS_TO[arg];
@@ -237,7 +292,11 @@ const NPM_LINE = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 async function main(argv) {
   const args = argv.slice(2);
   if (!args.length || args.includes('-h') || args.includes('--help')) {
-    process.stdout.write(USAGE);
+    // Whichever command they named, wherever they named it: `view --help`,
+    // `--help view` and `view chapter.prolog.md -h` all ask the same question.
+    // A help flag that is positional is its own small annoyance.
+    const named = args.map((arg) => commandNamed(arg)).find(Boolean);
+    process.stdout.write(named ? helpFor(named) : USAGE);
     return 0;
   }
   if (args.includes('--version') || args.includes('-V')) {

package/package.json

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

package/src/browser.js

@@ -229,8 +229,16 @@ class WorkerQuery {
   async all(limit) {
     if (this.done) return { solutions: [], truncated: false };
     const qid = await this.#open();
-    this.#finish();
-    return this.session.send('all', { qid, limit });
+    try {
+      return await this.session.send('all', { qid, limit });
+    } finally {
+      // AFTER THE WORKER HAS ANSWERED, not before. Releasing the session's one
+      // slot up front said "nothing is open here" while the engine was still
+      // inside the goal, so anything that opened next nested inside a frame the
+      // session had already forgotten (869erqvzu). The slot is the claim that
+      // this query is the innermost one, and that stays true until it is done.
+      this.#finish();
+    }
   }
 
   async close({ superseded = false } = {}) {

package/src/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "2d089b9",
-  "built": "2026-08-30 22:55:39 UTC"
+  "commit": "60e27bc",
+  "built": "2026-08-30 23:44:28 UTC"
 }

package/src/notebook.js

@@ -478,11 +478,18 @@ function mountPageBar(root, options, bus, programs, queries) {
   const outputsUnit = bar.querySelector('.unit.outputs');
   const outputsState = bar.querySelector('.outputs-state');
   let refreshOutputs = () => {};
-  // Nothing published to clear, and nothing a restore could give back. The row
-  // goes, exactly as the one above it does — an unrun chapter is the CLI's
-  // business, and a control whose only possible effect is on the reader's own
-  // run is a control offering to undo the thing they just asked for.
-  if (!spoilers.length) {
+  // ANY QUERY CELL AT ALL, not just a chapter that shipped answers.
+  //
+  // This used to go when the FILE had none, on the argument that an unrun
+  // chapter is the CLI's business. That argument was wrong the moment a reader
+  // pressed Run: a chapter published without answers — which is most of them
+  // while an author is still writing — gave them no way to clear the answers
+  // they had just produced, and a panel with the row missing reads as a control
+  // that has broken rather than one that had nothing to do (869erqw08).
+  //
+  // The row above stays keyed to the FILE, and correctly: hiding is for the
+  // chapter's saved answers, and a reader's own run is not a spoiler.
+  if (!queries.length) {
     outputsUnit.remove();
   } else {
     const wipe = document.createElement('button');
@@ -503,12 +510,14 @@ function mountPageBar(root, options, bus, programs, queries) {
       // to give back, so a page of only those leaves restore with no work.
       const restorable = gone.filter((q) => q.hasSaved).length;
       wipe.disabled = back ? restorable === 0 : left.length === 0;
-      // COUNTED FROM THE FILE while nothing is cleared, because that is the fact
-      // the reader does not have: how much of this chapter is answers. After
-      // that it counts what they did, which is the fact they want confirmed.
-      outputsState.textContent = gone.length === 0
-        ? `${plural(spoilers.length, 'output')} in this chapter`
-        : `${plural(gone.length, 'output')} cleared`;
+      // COUNTED FROM THE PAGE, which is the only count that stays true for both
+      // kinds of chapter: one published with its answers in it, and one still
+      // being written where every output on screen is the reader's own.
+      outputsState.textContent = gone.length > 0
+        ? `${plural(gone.length, 'output')} cleared`
+        : left.length > 0
+          ? `${plural(left.length, 'output')} on this page`
+          : 'No outputs yet';
       label(wipe, back ? 'restore' : 'erase',
         back ? 'Restore outputs' : 'Clear all outputs');
       wipe.title = back
@@ -667,12 +676,22 @@ async function boot(options, bus, status) {
   bus.booted = true;
   if (!wasBooted) {
     bus.emit({ kind: 'started', at: clock() });
-    // Asked for, not waited for. The light going green is the answer to "did it
-    // start", and holding that back for a round trip about a version number
-    // would be the page reporting the less interesting fact first.
-    prologVersion(session)
-      .then((version) => version && bus.emit({ kind: 'engine-version', version }))
-      .catch(() => {});
+    // AWAITED, AND THAT IS A CORRECTNESS MATTER RATHER THAN A PREFERENCE.
+    //
+    // This was fired and forgotten, on the argument that the light going green
+    // answers "did it start" and a version number should not hold it back. But
+    // asking for the version IS A QUERY, and one engine allows ONE OPEN QUERY
+    // (869epzqpc). Firing it alongside the reader's own Run put two opens into
+    // the worker's queue, and whichever arrived second nested inside the first —
+    // so the cell that started the engine got `Attempt to access not innermost
+    // query` while the panel cheerfully displayed the version that had won the
+    // race (869erqvzu).
+    //
+    // The light still goes green first: the event above is emitted before this
+    // waits. What it now costs is one flag lookup on the first boot only, and
+    // what it buys is that no cell query can ever be in flight beside it.
+    const version = await prologVersion(session).catch(() => null);
+    if (version) bus.emit({ kind: 'engine-version', version });
   }
   return session;
 }
@@ -1227,6 +1246,20 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
       : whose, 'from');
     write(`?- ${goal}.`, 'echo');
     setRunning(true);
+    // THE ENGINE IS CLAIMED HERE, BEFORE THE CONSULTS — not after the query is
+    // opened, which is where this used to be (869erqvzu).
+    //
+    // Loading the cells above emits `consulted`, and that is exactly what an
+    // auto cell waits for. Its re-run is queued and runs on the next turn, while
+    // this run is still somewhere inside its awaits — so it looked at a page
+    // where nobody was stepping, saw a free engine, and opened its own query
+    // underneath the one this cell was about to open. The reader, who had
+    // pressed Run on one cell and touched nothing else, got `Attempt to access
+    // not innermost query`.
+    //
+    // A cell is using the engine from the moment it starts, not from the moment
+    // it succeeds. finish() lets go, on every path out of here.
+    bus.stepping.add(cell);
     try {
       if (!bus.booted) write('starting SWI-Prolog (5.9 MB, first time only)…', 'done');
       session = await boot(options, bus);
@@ -1243,7 +1276,6 @@ function mountQuery(cell, options, bus, { above = [], below = [], prediction = n
         return;
       }
       query = session.query(goal);
-      bus.stepping.add(cell);
       // A sequence ends when another one starts — one engine, one open query
       // (869epzqpc). The reader hears it here, in the cell it happened to, with
       // the solutions they did take still under it and Run still lit. Silence was

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.6.3';
+export const VERSION = '0.6.5';
 
 /** The two facts a licence notice is actually made of. */
 export const YEAR = '2026';