prolog-notebook 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [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
+help listed under no command, exactly as though it were global.
+
+### Fixed
+
+- **`--check-update` works with every command**, and forces the check past the daily TTL, which
+  is the whole point of asking. It was accepted by `execute` alone.
+
+- **…and it answers down a pipe.** The check was skipped entirely without a terminal, so an
+  explicit check in a script reported nothing — indistinguishable from *you are up to date*,
+  which is the one thing an update notice must never look like. A terminal is needed to **offer**
+  an upgrade, never to **report** one.
+
+- **`build --port 90` was accepted and ignored.** `view` and `build` share a parser, so each
+  quietly took the other's flags. A flag that is read and thrown away is worse than one refused:
+  it looks like it worked.
+
+- **`clear` never looked for an update.** 0.5.1 established that every command doing real work
+  goes through one door, before the work; `clear` shipped afterwards and missed it, while
+  rewriting the author's notebook.
+
+### Changed
+
+- **The help lists each option under the command that takes it.** Only `--check-update`,
+  `--version` and `-h` are listed as working anywhere, because only those three do.
+
+- **A misplaced option says where it lives** — `--limit belongs to execute, not to view` —
+  rather than `unknown option` about a flag that is real and two lines further up.
+
 ## [0.6.2] — 2026-08-30
 
 From a field report: a built chapter opened in Chrome and Safari showed no controls and a Run

package/README.md

@@ -132,16 +132,24 @@ chapter.prolog.md: 4 answers removed
 `clear` empties every output block and touches nothing else; `execute` fills them in again from
 the engine. A chapter with no answers is a valid chapter — one that has not been executed yet.
 
+Each option belongs to a command, and typing one under the wrong command tells you which:
+
+| flag | on | |
+|---|---|---|
+| `--limit <n>` | `execute` | solutions to take from one query before stopping. Default 100. |
+| `--stdout` | `execute`, `clear` | print the result instead of writing the file |
+| `--quiet` | `execute`, `clear` | report only failures |
+| `--out <dir>` | `build` | where it writes. Default `<file>-site` |
+| `--port <n>` | `view` | what it listens on. Default 8777, and it takes another if that one is busy |
+| `--no-open` | `view` | print the URL instead of opening a browser |
+
+Three work anywhere, because they are about the tool rather than about a notebook:
+
 | flag | |
 |---|---|
-| `--limit <n>` | solutions to take from one query before stopping. Default 100. |
-| `--stdout` | print the result instead of writing the file |
-| `--quiet` | report only failures |
-| `--out <dir>` | where `build` writes. Default `<file>-site` |
-| `--port <n>` | what `view` listens on. Default 8777, and it takes another if that one is busy |
-| `--no-open` | `view` prints the URL instead of opening a browser |
 | `--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 |
+| `--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` | 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

@@ -37,29 +37,121 @@ for (const stream of [process.stdout, process.stderr]) {
 // 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 view <file.prolog.md>       read it in a browser, cells and all
-  prolog-notebook build <file.prolog.md>      write a page you can host or send
-  prolog-notebook execute <file.prolog.md>... run every query, write the answers in
-  prolog-notebook clear <file.prolog.md>...   take the answers back out
-  prolog-notebook upgrade                     fetch the latest version
-
-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
-  --out <dir>     where build writes (default: <file>-site)
-  --port <n>      what view listens on (default 8777)
-  --no-open       view prints the URL instead of opening a browser
-  --version       version, engine and copyright
+/**
+ * THE COMMANDS, AND WHAT EACH ONE TAKES — one table, three readers (869erqra0).
+ *
+ * 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 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: [],
+  },
+};
+
+/** `exec` and `run` reach `execute` and are deliberately undocumented (869erp0jd). */
+const ALIASES = { exec: 'execute', run: 'execute' };
+
+/** The command this argument names, aliases resolved, or null. */
+const commandNamed = (arg) => (COMMANDS[arg] ? arg : ALIASES[arg] ?? null);
+
+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.
+ */
+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];
+  return home && home !== command
+    ? `${arg} belongs to ${home}, not to ${command}\n`
+    : `unknown option "${arg}"\n`;
+}
+
 /**
  * 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
@@ -158,11 +250,18 @@ function canAsk() {
  *   to a newer version, null to carry on here.
  */
 async function upgradeFirst({ quiet = false, asked = false } = {}) {
-  if (!canAsk() || (quiet && !asked)) return null;
+  // ASKED OUTRIGHT ALWAYS ANSWERS (869erqra0). A terminal is needed to OFFER the
+  // upgrade, never to report one: `--check-update` down a pipe used to check
+  // nothing and say nothing, which is indistinguishable from "you are up to
+  // date" — the one thing this must never look like.
+  if (!asked && (!canAsk() || quiet)) return null;
   const ahead = await updateNotice({ version: VERSION, force: asked })
     .catch(() => ({ message: null, newer: null }));
   if (ahead.message) process.stderr.write(`${ahead.message}\n`);
-  if (!ahead.newer || !(await confirm('Update and continue on the new version?'))) return null;
+  // The notice is printed above whatever happens next; only the question needs
+  // somebody at the other end to answer it.
+  if (!ahead.newer || !canAsk()) return null;
+  if (!(await confirm('Update and continue on the new version?'))) return null;
   if ((await upgrade(ahead.newer)) !== 0) {
     process.stderr.write('Carrying on with the version you have.\n');
     return null;
@@ -193,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')) {
@@ -213,8 +316,8 @@ async function main(argv) {
   }
 
   const command = args.shift();
-  if (command === 'view' || command === 'build') return page(command, args);
-  if (command === 'clear') return clear(args);
+  if (command === 'view' || command === 'build') return page(command, args, asked);
+  if (command === 'clear') return clear(args, asked);
   if (command === 'upgrade') {
     const { message, newer } = await updateNotice({ version: VERSION, force: true });
     if (message) process.stderr.write(`${message}\n`);
@@ -246,7 +349,7 @@ async function main(argv) {
     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}`);
+      process.stderr.write(unknownOption(arg, 'execute'));
       return 2;
     } else files.push(arg);
   }
@@ -259,7 +362,9 @@ async function main(argv) {
 
   const jump = await upgradeFirst({ quiet: options.quiet, asked });
   if (jump !== null) return jump;
-  checked = canAsk() && (!options.quiet || asked);
+  // Whatever upgradeFirst has just reported must not be reported again below.
+  // Asked outright, it always reports now, terminal or not.
+  checked = asked || (canAsk() && !options.quiet);
 
   // 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
@@ -309,14 +414,16 @@ async function main(argv) {
  * No engine, no network and no update check: this is a text operation on a file
  * the reader already has.
  */
-async function clear(args) {
+async function clear(args, asked = false) {
   const options = { stdout: false, quiet: false };
   const files = [];
   for (const arg of args) {
     if (arg === '--stdout') options.stdout = true;
     else if (arg === '--quiet') options.quiet = true;
+    // Handled by the caller, and not a file.
+    else if (arg === '--check-update') { /* global */ }
     else if (arg.startsWith('-')) {
-      process.stderr.write(`unknown option "${arg}"\n`);
+      process.stderr.write(unknownOption(arg, 'clear'));
       return 2;
     } else files.push(arg);
   }
@@ -325,6 +432,13 @@ async function clear(args) {
     return 2;
   }
 
+  // THE SAME DOOR AS EVERY OTHER COMMAND THAT DOES REAL WORK (869erqra0). 0.5.1
+  // put `view` and `build` through it and this command shipped afterwards, so it
+  // never looked. Emptying somebody's notebook is as real as work gets here, and
+  // before the work is the only point at which a newer version changes anything.
+  const jump = await upgradeFirst({ quiet: options.quiet, asked });
+  if (jump !== null) return jump;
+
   let status = 0;
   for (const file of files) {
     let source;
@@ -361,11 +475,20 @@ async function clear(args) {
  * whole reason a built page is readable before any engine arrives. Use `run` to
  * put them there.
  */
-async function page(command, args) {
+async function page(command, args, asked = false) {
   const options = { out: null, port: 8777, open: true };
   const files = [];
   while (args.length) {
     const arg = args.shift();
+    // ONE PARSER, TWO COMMANDS, AND THEY DO NOT TAKE THE SAME FLAGS. `view` and
+    // `build` share this function, so `build --port 90` was quietly accepted and
+    // ignored while the help said --port was view's (869erqra0). A flag that is
+    // read and thrown away is worse than one that is refused: it looks like it
+    // worked.
+    if (BELONGS_TO[arg] && BELONGS_TO[arg] !== command) {
+      process.stderr.write(unknownOption(arg, command));
+      return 2;
+    }
     if (arg === '--out') options.out = args.shift();
     else if (arg === '--port') {
       options.port = Number(args.shift());
@@ -374,8 +497,10 @@ async function page(command, args) {
         return 2;
       }
     } else if (arg === '--no-open') options.open = false;
+    // Handled by the caller, and not a file.
+    else if (arg === '--check-update') { /* global */ }
     else if (arg.startsWith('-')) {
-      process.stderr.write(`unknown option "${arg}"\n`);
+      process.stderr.write(unknownOption(arg, command));
       return 2;
     } else files.push(arg);
   }
@@ -387,7 +512,7 @@ async function page(command, args) {
   // The same offer the execute path makes, and for the same reason: a server about to
   // start, or a directory about to be written, is work that a newer version
   // should be doing.
-  const jump = await upgradeFirst();
+  const jump = await upgradeFirst({ asked });
   if (jump !== null) return jump;
 
   const file = files[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prolog-notebook",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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": "bdbce1b",
-  "built": "2026-08-30 22:41:37 UTC"
+  "commit": "9973408",
+  "built": "2026-08-30 23:05:20 UTC"
 }

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