@nemus-cli/nemus 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.1] - 2026-09-04
+
+### Fixed
+
+- **`npx @nemus-cli/nemus …` no longer hangs.** The postinstall first-run setup
+  (interactive `nemus configure`, shell-integration install) now runs **only on
+  a global install** (`npm i -g`). A transient `npx` run or a local dependency
+  install is not global — the `nemus`/`nem` bins aren't persisted on PATH, so
+  shell integration is pointless, and the interactive `configure` reached the
+  controlling terminal via `/dev/tty` and hung a non-interactive
+  `npx … --help`/`--version`. Global installs are unchanged.
+
+### Added
+
+- **Zero-install usage** documented: `npx @nemus-cli/nemus <command>` runs any
+  command without installing or touching your shell.
+
 ## [0.15.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -140,7 +140,20 @@ npm install -g @nemus-cli/nemus
 The postinstall step sets up optional shell integration (auto-cd into new
 workspaces + a quick-navigate helper). It keeps the generated functions in
 `~/.nemus/shell-integration.sh` and adds only a guarded source line to your
-shell RC file, so upgrades don't churn your `.zshrc`/`.bashrc`.
+shell RC file, so upgrades don't churn your `.zshrc`/`.bashrc`. First-time setup
+(`nemus configure`) runs automatically **only on a global install** — a
+throwaway `npx` run or a local dependency install leaves your shell untouched.
+
+### Try it without installing
+
+```bash
+npx @nemus-cli/nemus list          # run any command via npx
+npx @nemus-cli/nemus -- "…"         # or the AI prompt
+```
+
+Zero install, nothing added to your PATH or shell RC. (Shell integration and
+auto-cd only make sense once the `nemus`/`nem` bins are on your PATH, so install
+globally when you want those.)
 
 ### From source
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "workspaces": [
     "packages/*"
   ],

package/scripts/postinstall.js

@@ -20,6 +20,16 @@ const path = require('path');
 // Skip in CI environments
 if (process.env.CI) process.exit(0);
 
+// Only run first-run setup for a real GLOBAL install (`npm i -g`). A transient
+// `npx @nemus-cli/nemus …` (npm exec) or a local dependency install is not
+// global: the `nemus`/`nem` bins aren't persisted on PATH, so shell integration
+// is pointless — and worse, the interactive `configure` below reaches the
+// controlling terminal via /dev/tty and would HANG a non-interactive
+// `npx … --help`/`--version` invocation waiting for input. npm sets
+// npm_config_global="true" only for `-g`/`--global`; npx and local installs
+// leave it false/unset.
+if (String(process.env.npm_config_global).toLowerCase() !== 'true') process.exit(0);
+
 const PKG_ROOT = path.join(__dirname, '..');
 const SHELL_SCRIPT = path.join(PKG_ROOT, 'install-shell-integration.sh');
 const CLI_BIN = path.join(PKG_ROOT, 'bin', 'workspace.js');

package/src/postinstall.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const SCRIPT = join(__dirname, '..', 'scripts', 'postinstall.js');
+
+describe('postinstall.js', () => {
+  // Regression: a transient `npx @nemus-cli/nemus …` (npm exec) or a local
+  // dependency install is NOT global. Such installs must not launch the
+  // interactive `configure` (which reaches /dev/tty and would HANG a
+  // non-interactive `npx … --help`) nor mutate the user's shell RC — the bins
+  // aren't persisted on PATH for them anyway.
+  it('is a fast no-op for a non-global install: exits 0 and never touches the shell RC', () => {
+    const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
+    const rc = join(home, '.zshrc');
+    writeFileSync(rc, '# user rc\n');
+    const env = { ...process.env, HOME: home, SHELL: '/bin/zsh', NEMUS_CACHE_DIR: join(home, '.nemus') };
+    // Delete CI so the global gate — not the CI early-exit — is what protects npx.
+    delete env.CI;
+    delete env.npm_config_global; // npx / local install leaves this unset
+    try {
+      // Throws on non-zero exit; throws on the 15s timeout if it ever hangs.
+      execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 15_000 });
+      // RC untouched — no guarded `source` line appended.
+      expect(readFileSync(rc, 'utf8')).toBe('# user rc\n');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  it('treats npm_config_global="false" the same as unset (still a no-op)', () => {
+    const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
+    const rc = join(home, '.bashrc');
+    writeFileSync(rc, '# user rc\n');
+    const env = {
+      ...process.env,
+      HOME: home,
+      SHELL: '/bin/bash',
+      NEMUS_CACHE_DIR: join(home, '.nemus'),
+      npm_config_global: 'false',
+    };
+    delete env.CI;
+    try {
+      execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 15_000 });
+      expect(readFileSync(rc, 'utf8')).toBe('# user rc\n');
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});