eyeprolog 1.1.10 → 1.1.11

package/README.md

@@ -21,11 +21,22 @@ examples, proofs, conformance, and implementation.
 
 ## Quick start
 
-EyeProlog requires Node.js 18 or newer.
+EyeProlog requires Node.js 18 or newer. Check the active runtime before
+installing:
 
 ```sh
-npm install --global eyeprolog
-eyeprolog
+node --version
+```
+
+If it reports an older release, upgrade through a Node version manager or the
+[official Node.js download](https://nodejs.org/en/download) and check again.
+Distribution packages can provide an older Node.js even on a current operating
+system.
+
+Run EyeProlog without a global installation:
+
+```sh
+npx --yes eyeprolog
 ?- use_module(library(lists)).
    true.
 ?- member(X, [prolog, logic]).
@@ -34,11 +45,25 @@ eyeprolog
 ?- halt.
 ```
 
+For a persistent `eyeprolog` command without administrator access, install it
+under a user-owned prefix and put that prefix's `bin` directory on `PATH`:
+
+```sh
+npm install --global --prefix "$HOME/.local" eyeprolog
+export PATH="$HOME/.local/bin:$PATH"
+eyeprolog
+```
+
+Add the `PATH` export to your shell startup file to keep it across sessions.
+Do not use `sudo npm install`; npm's
+[EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
+also recommends a Node version manager or a user-owned npm prefix.
+
 For a non-interactive run:
 
 ```sh
 printf 'human(socrates).\nmortal(X) :- human(X).\n' |
-  eyeprolog --proof --goal 'mortal(socrates)' -
+  npx --yes eyeprolog --proof --goal 'mortal(socrates)' -
 ```
 
 Programs may declare their default queries with `%% goal:` comments.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "EyeProlog turns facts and rules into answers and proofs.",
   "type": "module",
   "main": "./index.js",

package/test/run-regression.mjs

@@ -516,6 +516,27 @@ c4 ?- call((!;1)).
         assertEqual(result.stderr, '', 'stderr');
       },
     },
+    {
+      name: 'npm can install the CLI under a user-owned prefix',
+      run: () => {
+        const prefix = path.join(tmp, `npm-prefix-${++tmpCounter}`);
+        const installed = spawnSync('npm', [
+          'install', '--global', '--prefix', prefix, '--loglevel=silent', '--no-audit', '--no-fund', '.',
+        ], {
+          cwd: packageRoot,
+          encoding: 'utf8',
+          env: { ...process.env, npm_config_update_notifier: 'false' },
+        });
+        assertEqual(installed.status, 0, 'install exit status');
+        const executable = process.platform === 'win32'
+          ? path.join(prefix, 'eyeprolog.cmd')
+          : path.join(prefix, 'bin', 'eyeprolog');
+        const result = spawnSync(executable, ['--version'], { encoding: 'utf8' });
+        assertEqual(result.status, 0, 'installed CLI exit status');
+        assertEqual(result.stdout, `eyeprolog ${pkg.version}\n`, 'installed CLI stdout');
+        assertEqual(result.stderr, '', 'installed CLI stderr');
+      },
+    },
     {
       name: 'stdin input is accepted',
       run: () => {
@@ -979,6 +1000,22 @@ function documentationSyncCases() {
         assertArrayEqual(misleadingDependencyInstallDocs(), [], 'misleading dependency install docs');
       },
     },
+    {
+      name: 'installation docs avoid unsupported Node and global npm permission traps',
+      run: () => {
+        assertEqual(pkg.engines?.node, '>=18', 'supported Node range');
+        for (const filename of ['README.md', 'the-art-of-eyeprolog.md']) {
+          const text = fs.readFileSync(path.join(packageRoot, filename), 'utf8');
+          assertIncludes(text, 'node --version', `${filename} checks Node version`);
+          assertIncludes(text, 'npx --yes eyeprolog', `${filename} offers a non-global launch`);
+          assertIncludes(text, 'npm install --global --prefix "$HOME/.local" eyeprolog', `${filename} uses a user prefix`);
+          assertIncludes(text, 'https://nodejs.org/en/download', `${filename} links Node upgrades`);
+          assertIncludes(text, 'https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/', `${filename} links npm EACCES guidance`);
+          assertEqual(text.includes('sudo npm install'), true, `${filename} explicitly warns against sudo npm`);
+          assertEqual(/^\s*sudo npm install/m.test(text), false, `${filename} never recommends sudo npm`);
+        }
+      },
+    },
   ];
 }
 

package/the-art-of-eyeprolog.md

@@ -79,6 +79,30 @@ Then ask for the derivations:
 node bin/eyeprolog.js --proof examples/socrates.pl
 ```
 
+To use the published package, first verify that `node --version` reports Node.js
+18 or newer. Upgrade an older runtime through a Node version manager or the
+[official Node.js download](https://nodejs.org/en/download). A current Linux
+distribution can still expose an older Node.js package.
+
+The package can be launched without a global installation:
+
+```sh
+npx --yes eyeprolog
+```
+
+For a persistent command without administrator access, install into a
+user-owned prefix:
+
+```sh
+npm install --global --prefix "$HOME/.local" eyeprolog
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Persist the `PATH` export in the appropriate shell startup file. Do not use
+`sudo npm install`; npm's
+[EACCES guidance](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/)
+recommends a Node version manager or a user-owned npm prefix.
+
 Readers who do not want to install anything can begin in the
 [browser playground](https://eyereasoner.github.io/eyeprolog/playground). Paste
 the source of `examples/socrates.pl` into the editor and run it. The playground