@nemus-cli/nemus 0.15.0 → 0.15.2

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.2] - 2026-09-04
+
+### Fixed
+
+- **First-run setup now runs for global installs via yarn and pnpm too — without
+  re-introducing the hang for their transient runners.** 0.15.1 gated postinstall
+  setup on `npm_config_global`, which only npm sets, so `yarn global add` /
+  `pnpm add -g` silently skipped `configure` + shell integration (the auto-cd /
+  `nemgo` feature). The gate now classifies the install context: it recognizes a
+  global yarn/pnpm install from `npm_config_user_agent`, but detects transient
+  one-off runners (`npx`, `pnpm dlx`, `yarn dlx`) by the per-run cache path they
+  stage into (`.../_npx/...`, `.../dlx/...`, the OS temp dir, with the macOS
+  `/private` symlink normalized) — because `pnpm dlx`/`yarn dlx` set *neither*
+  `npm_command` *nor* `npm_config_global`, so a user-agent check alone would
+  misclassify them as a global install. Hang-safety itself comes from a separate
+  guard — the interactive `configure` only fires for a confirmed npm `-g`
+  install, so yarn/pnpm globals get the non-interactive shell integration plus a
+  hint and can never hang; the transient path detection's job is to stop a
+  throwaway `dlx` run from spuriously writing the shell RC. (#92)
+
+## [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.2",
   "workspaces": [
     "packages/*"
   ],

package/scripts/postinstall.js

@@ -17,8 +17,88 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-// Skip in CI environments
-if (process.env.CI) process.exit(0);
+/**
+ * Classify the install context, so first-run setup (interactive `configure` +
+ * shell integration) runs only when it makes sense — and NEVER on a transient
+ * one-off runner (npx / dlx), where an interactive prompt on the controlling
+ * terminal would HANG. Pure (all inputs injected) so it's unit-tested.
+ *
+ * Returns: 'ci' | 'transient' | 'local' | 'global-npm' | 'global-other'.
+ *
+ * Detection is empirical (env dumped from real runners), because the managers
+ * disagree on what they set:
+ *   • npm  — npx sets npm_command="exec"; `-g` sets npm_config_global="true"; a
+ *            local install sets it "false". Reliable.
+ *   • pnpm — `pnpm dlx` sets NEITHER npm_command NOR npm_config_global, only
+ *            npm_config_user_agent="pnpm/…". It DOES stage the package under a
+ *            per-run cache path ("…/pnpm/dlx/<hash>/…"), which we key on.
+ *   • yarn — classic `yarn global add` sets only "yarn/…" (no npm_command /
+ *            npm_config_global); berry `yarn dlx` stages under a temp dir.
+ * So a bare yarn/pnpm user-agent is treated as a GLOBAL install UNLESS the
+ * install PATH shows a transient runner cache. The path is matched RAW (only the
+ * macOS /private symlink prefix is string-normalized, below) — deliberately NOT
+ * fs.realpathSync'd: realpath resolves a pnpm/yarn staging dir through its
+ * symlinks into a content-addressed store path that no longer contains /dlx/,
+ * which would defeat the marker. String-normalizing just the /private prefix
+ * fixes the macOS /var↔/private/var temp-dir case without touching the markers.
+ *
+ * NOTE on failure mode: because the interactive `configure` (the step that can
+ * hang on /dev/tty) is separately gated to a confirmed npm `-g` install (see
+ * `certainNpmGlobal`), a misclassified `pnpm dlx`/`yarn dlx` lands in
+ * 'global-other' and can never hang — it skips `configure`. The path signal's
+ * real job is therefore to stop a throwaway dlx run from spuriously appending
+ * the source line to the user's shell RC, not to provide hang-safety.
+ */
+function classifyInstall({ env, dirname, tmpDir }) {
+  if (env.CI) return 'ci';
+
+  const cmd = (env.npm_command || '').toLowerCase();
+  // macOS surfaces the temp dir both as /var/folders/… (os.tmpdir(), a symlink)
+  // and /private/var/folders/… (the realpath a staged package resolves to). Strip
+  // the well-known /private symlink prefix from both sides so the temp-dir
+  // comparison survives it — done by string, not fs.realpathSync, to keep this
+  // function pure (and correct for paths that don't exist yet, e.g. in tests).
+  const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/^\/private(?=\/)/, '');
+  const dir = norm(dirname);
+  const tmp = norm(tmpDir);
+  const stagedInRunnerCache =
+    /\/_npx\//.test(dir) ||                              // npm  npx
+    /\/dlx\//.test(dir) ||                               // pnpm dlx (or any /dlx/ cache)
+    (tmp !== '' && (dir === tmp || dir.startsWith(tmp + '/'))); // yarn berry dlx et al.
+  if (cmd === 'exec' || cmd === 'dlx' || stagedInRunnerCache) return 'transient';
+
+  const global = String(env.npm_config_global).toLowerCase();
+  if (global === 'true') return 'global-npm';
+  if (global === 'false') return 'local';
+
+  // No npm_config_global (yarn/pnpm): a bare manager user-agent means a global
+  // install here (their transient runners were caught above).
+  const manager = (env.npm_config_user_agent || '').toLowerCase().split('/')[0];
+  if (manager === 'yarn' || manager === 'pnpm') return 'global-other';
+  return 'local';
+}
+
+module.exports = { classifyInstall };
+
+// When imported (unit tests) rather than run as the postinstall script, stop
+// here — export the classifier without executing any install side effects.
+// (CommonJS wraps modules in a function, so a top-level return is valid.)
+if (require.main !== module) return;
+
+// Pass the RAW __dirname (not realpath'd): the transient-runner markers below
+// (/_npx/, /dlx/) live in the path the runner *constructs*, and fs.realpathSync
+// would resolve a pnpm/yarn staging dir through its symlinks into a
+// content-addressed store path that no longer contains the marker — defeating
+// the very check. The macOS /var↔/private/var temp symlink is instead handled
+// deterministically by string normalization inside classifyInstall.
+const installDecision = classifyInstall({ env: process.env, dirname: __dirname, tmpDir: os.tmpdir() });
+// Only 'global-*' installs get first-run setup; ci/transient/local are no-ops.
+if (installDecision !== 'global-npm' && installDecision !== 'global-other') process.exit(0);
+// Interactive `configure` (reaches /dev/tty) fires ONLY when we're certain it's
+// an npm `-g` install. yarn/pnpm can't be told apart from their dlx runners by
+// env alone, so they get the NON-interactive shell integration below + a hint —
+// which can never hang.
+const certainNpmGlobal = installDecision === 'global-npm';
 
 const PKG_ROOT = path.join(__dirname, '..');
 const SHELL_SCRIPT = path.join(PKG_ROOT, 'install-shell-integration.sh');
@@ -69,7 +149,7 @@ function openControllingTty() {
   }
 }
 
-if (!optedOut() && fs.existsSync(CLI_BIN) && !alreadyConfigured()) {
+if (certainNpmGlobal && !optedOut() && fs.existsSync(CLI_BIN) && !alreadyConfigured()) {
   const tty = openControllingTty();
   if (tty !== null) {
     try {
@@ -146,6 +226,12 @@ console.log('');
 console.log('  Or open a new terminal tab. Until then, auto-CD into a new');
 console.log('  workspace won\'t work (the CLI itself still runs fine).');
 console.log('');
+if (!certainNpmGlobal) {
+  // yarn/pnpm global: we installed shell integration but deliberately did NOT
+  // launch the interactive configure — point the user at it explicitly.
+  console.log('  \x1b[90m(yarn/pnpm install — run \x1b[36mnemus configure\x1b[90m to finish first-time setup.)\x1b[0m');
+  console.log('');
+}
 console.log('  Tip: \x1b[36mnemus\x1b[0m works immediately (\x1b[36mgv\x1b[0m is a short alias):');
 console.log('       \x1b[36mnemus configure\x1b[0m   \x1b[90m# first-time setup\x1b[0m');
 console.log('       \x1b[36mnemus list\x1b[0m        \x1b[90m# list workspaces\x1b[0m');

package/src/postinstall.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+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');
+// postinstall.js guards its side effects with `require.main !== module`, so
+// importing it just exposes the pure classifier.
+const { classifyInstall } = createRequire(__filename)(SCRIPT) as {
+  classifyInstall: (i: { env: Record<string, string | undefined>; dirname: string; tmpDir: string }) => string;
+};
+
+const NPM_UA = 'npm/10.9.0 node/v22.13.0 darwin arm64 workspaces/false';
+const YARN_UA = 'yarn/1.22.22 npm/? node/v22.13.0 darwin arm64';
+const PNPM_UA = 'pnpm/10.34.5 npm/? node/v22.13.0';
+const TMP = '/var/folders/xy/T';
+
+describe('classifyInstall', () => {
+  it('CI → ci', () => {
+    expect(classifyInstall({ env: { CI: 'true' }, dirname: '/anywhere', tmpDir: TMP })).toBe('ci');
+  });
+
+  it('npm -g → global-npm; npm local → local', () => {
+    expect(classifyInstall({ env: { npm_config_global: 'true', npm_config_user_agent: NPM_UA }, dirname: '/usr/local/lib/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-npm');
+    expect(classifyInstall({ env: { npm_config_global: 'false', npm_config_user_agent: NPM_UA }, dirname: '/proj/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('local');
+  });
+
+  it('npx (npm_command=exec) → transient', () => {
+    expect(classifyInstall({ env: { npm_command: 'exec', npm_config_user_agent: NPM_UA }, dirname: '/home/u/.npm/_npx/abc123/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('transient');
+  });
+
+  it('yarn global add (bare yarn UA, no npm_command/global) → global-other', () => {
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: '/home/u/.config/yarn/global/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-other');
+  });
+
+  it('pnpm add -g (bare pnpm UA) → global-other', () => {
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: '/home/u/Library/pnpm/global/5/node_modules/@nemus-cli/nemus/scripts', tmpDir: TMP })).toBe('global-other');
+  });
+
+  // The reviewer's case: `pnpm dlx` sets NEITHER npm_command NOR
+  // npm_config_global — only the pnpm user-agent. UA-only logic would call this
+  // "global-other" and re-introduce the /dev/tty hang. The install PATH
+  // (".../pnpm/dlx/<hash>/...") is the signal that saves us.
+  it('pnpm dlx (only pnpm UA, staged under .../pnpm/dlx/...) → transient', () => {
+    const dir = '/home/u/Library/Caches/pnpm/dlx/ed050d93/1a07/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  // A realistic pnpm dlx __dirname (verified by dumping a real run): the /dlx/
+  // marker sits BEFORE the symlinky `.pnpm` store segments. postinstall.js
+  // passes the RAW __dirname (never fs.realpathSync'd) precisely so the marker
+  // isn't resolved away into a content-addressed store path — this asserts the
+  // deep, real-shaped path still classifies transient.
+  it('pnpm dlx deep real path (marker before the .pnpm store segments) → transient', () => {
+    const dir =
+      '/Users/u/Library/Caches/pnpm/dlx/9622a716fa/1a0757951f6-12d63/node_modules/.pnpm/nemus@file+..+..+tmp/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  it('yarn berry dlx (only yarn UA, staged under the OS temp dir) → transient', () => {
+    const dir = `${TMP}/xfs-9f/node_modules/@nemus-cli/nemus/scripts`;
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: dir, tmpDir: TMP })).toBe('transient');
+  });
+
+  // The real macOS case: os.tmpdir() reports /var/folders/… (a symlink) while a
+  // package staged under it resolves to /private/var/folders/… . A raw
+  // startsWith would miss this and misclassify the dlx run as global-other
+  // (spurious shell-RC write). The classifier must normalize the /private prefix.
+  it('yarn/pnpm dlx staged under /private/var while tmpDir is /var → transient', () => {
+    const tmpDir = '/var/folders/xy/T';
+    const dir = '/private/var/folders/xy/T/xfs-9f/node_modules/@nemus-cli/nemus/scripts';
+    expect(classifyInstall({ env: { npm_config_user_agent: YARN_UA }, dirname: dir, tmpDir })).toBe('transient');
+    // symmetric: tmpDir realpath'd to /private while dir stays /var
+    expect(classifyInstall({ env: { npm_config_user_agent: PNPM_UA }, dirname: '/var/folders/xy/T/d/node_modules/x', tmpDir: '/private/var/folders/xy/T' })).toBe('transient');
+  });
+});
+
+/** Run the real postinstall.js in a sandbox HOME with a controlled environment.
+ *  stdio is ignored and there's no tty, and NEMUS_SKIP_CONFIGURE guards a
+ *  tty-bearing host, so we exercise the gate + non-interactive shell-integration
+ *  path end-to-end (dirname is the real repo path — never transient). */
+function runPostinstall(rcName: string, extraEnv: Record<string, string | undefined>) {
+  const home = mkdtempSync(join(tmpdir(), 'nemus-postinstall-'));
+  const rc = join(home, rcName);
+  writeFileSync(rc, '# user rc\n');
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    HOME: home,
+    NEMUS_CACHE_DIR: join(home, '.nemus'),
+    NEMUS_SKIP_CONFIGURE: '1',
+  };
+  delete env.CI;
+  for (const [k, v] of Object.entries(extraEnv)) {
+    if (v === undefined) delete env[k];
+    else env[k] = v;
+  }
+  execFileSync(process.execPath, [SCRIPT], { env, stdio: 'ignore', timeout: 20_000 });
+  const rcAfter = readFileSync(rc, 'utf8');
+  rmSync(home, { recursive: true, force: true });
+  return rcAfter;
+}
+
+describe('postinstall.js (end-to-end)', () => {
+  it('npx / npm exec → no-op, RC untouched', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'exec', npm_config_user_agent: NPM_UA, npm_config_global: undefined, SHELL: '/bin/zsh' })).toBe('# user rc\n');
+  });
+
+  it('npm local dependency install (global="false") → no-op, RC untouched', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'install', npm_config_user_agent: NPM_UA, npm_config_global: 'false', SHELL: '/bin/zsh' })).toBe('# user rc\n');
+  });
+
+  it('npm global install → runs shell integration (RC gets the source line)', () => {
+    expect(runPostinstall('.zshrc', { npm_command: 'install', npm_config_user_agent: NPM_UA, npm_config_global: 'true', SHELL: '/bin/zsh' })).toContain('.nemus/shell-integration.sh');
+  });
+
+  it('yarn global add (no npm_config_global) → runs shell integration', () => {
+    expect(runPostinstall('.bashrc', { npm_command: undefined, npm_config_user_agent: YARN_UA, npm_config_global: undefined, SHELL: '/bin/bash' })).toContain('.nemus/shell-integration.sh');
+  });
+
+  it('pnpm add -g (no npm_config_global) → runs shell integration', () => {
+    expect(runPostinstall('.bashrc', { npm_command: undefined, npm_config_user_agent: PNPM_UA, npm_config_global: undefined, SHELL: '/bin/bash' })).toContain('.nemus/shell-integration.sh');
+  });
+});