@nemus-cli/nemus 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-02
+
+### Added
+
+- **`nemus version` subcommand** — a companion to the `-V/--version` flag for
+  people who type `nemus version`. `--json` additionally reports the Node.js
+  version, platform, and arch (handy for bug reports), as a single JSON document
+  to stdout. (#74)
+- **`NEMUS_NO_UPDATE_CHECK`** — opt out of the background "update available"
+  check entirely (no cache read, no network). Also honors the de-facto
+  `NO_UPDATE_NOTIFIER`. An explicit falsey value (`0`/`false`/empty) does not
+  disable it. Documented in the README env-var table. (#76)
+
 ## [0.11.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -288,6 +288,7 @@ Everything Nemus reads from the environment (all optional):
 | `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
 | `NEMUS_BUG_REPORT_REPO` | Repo that `report-bug` files issues against. |
 | `NEMUS_SKIP_CONFIGURE` | Skip the one-time post-install `configure` prompt. |
+| `NEMUS_NO_UPDATE_CHECK` | Disable the background "update available" check (also honors `NO_UPDATE_NOTIFIER`). |
 | `WORKSPACE_CLONE_TIMEOUT_MS` | Git clone timeout (default 15 min). |
 | `NO_COLOR` / `FORCE_COLOR` | Disable / force ANSI color (see [Global flags](#global-flags)). |
 | `VISUAL` / `EDITOR` | Editor launched by `nemus config edit`. |

package/dist/commands/version.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVersionInfo = buildVersionInfo;
+exports.registerVersionCommand = registerVersionCommand;
+const output_1 = require("../utils/output");
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+function buildVersionInfo(version, proc = process) {
+    return {
+        version,
+        node: proc.versions.node,
+        platform: proc.platform,
+        arch: proc.arch,
+    };
+}
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+function registerVersionCommand(program, version) {
+    program
+        .command('version')
+        .description('Print the Nemus version (with --json for version + runtime info)')
+        .option('--json', 'Output version + runtime info as JSON')
+        .action((opts) => {
+        const info = buildVersionInfo(version);
+        if (opts.json) {
+            (0, output_1.outputJson)(info);
+        }
+        else {
+            process.stdout.write(`nemus ${info.version}\n`);
+        }
+    });
+}

package/dist/program.js

@@ -40,6 +40,7 @@ const fs = __importStar(require("fs"));
 const colors_1 = require("./utils/colors");
 const banner_1 = require("./utils/banner");
 const global_flags_1 = require("./utils/global-flags");
+const version_1 = require("./commands/version");
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 // --no-color must be applied BEFORE commander parses so it reaches the help
@@ -66,6 +67,7 @@ exports.program
 // also pre-scanned above.
 exports.program.hook('preAction', () => (0, global_flags_1.applyGlobalFlags)(exports.program.opts()));
 // Register top-level commands
+(0, version_1.registerVersionCommand)(exports.program, pkg.version);
 const create_1 = require("./commands/create");
 const list_1 = require("./commands/list");
 const update_1 = require("./commands/update");

package/dist/utils/version-check.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkForUpdate = checkForUpdate;
+exports.updateCheckDisabled = updateCheckDisabled;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -89,6 +90,11 @@ async function fetchLatestVersion() {
  * This is designed to be non-blocking and best-effort — failures are silent.
  */
 async function checkForUpdate() {
+    // Opt-out: skip the check entirely (no cache read, no network) when the user
+    // asks for it. NEMUS_NO_UPDATE_CHECK is ours; NO_UPDATE_NOTIFIER is the
+    // de-facto convention several Node CLIs honor.
+    if (updateCheckDisabled(process.env))
+        return null;
     try {
         const currentVersion = (0, config_1.getPackageVersion)();
         const cache = await loadCache();
@@ -116,6 +122,15 @@ async function checkForUpdate() {
         return null;
     }
 }
+/**
+ * Whether the update check is opted out via env. A value is "set" unless it is
+ * empty or an explicit falsey token (`0`/`false`), so `NEMUS_NO_UPDATE_CHECK=0`
+ * does NOT disable the check. Pure + exported for testing.
+ */
+function updateCheckDisabled(env) {
+    const isSet = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+    return isSet(env.NEMUS_NO_UPDATE_CHECK) || isSet(env.NO_UPDATE_NOTIFIER);
+}
 function formatUpdateMessage(current, latest) {
     return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
 }

package/package.json

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

package/src/commands/version.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { buildVersionInfo } from './version';
+
+describe('buildVersionInfo', () => {
+  it('combines the given version with the injected runtime fields', () => {
+    const info = buildVersionInfo('1.2.3', {
+      versions: { node: '22.13.0' } as NodeJS.ProcessVersions,
+      platform: 'linux',
+      arch: 'x64',
+    });
+    expect(info).toEqual({ version: '1.2.3', node: '22.13.0', platform: 'linux', arch: 'x64' });
+  });
+
+  it('defaults to the real process runtime', () => {
+    const info = buildVersionInfo('9.9.9');
+    expect(info.version).toBe('9.9.9');
+    expect(info.node).toBe(process.versions.node);
+    expect(info.platform).toBe(process.platform);
+    expect(info.arch).toBe(process.arch);
+  });
+});

package/src/commands/version.ts

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { outputJson } from '../utils/output';
+
+export interface VersionInfo {
+  version: string;
+  node: string;
+  platform: string;
+  arch: string;
+}
+
+/**
+ * Build the version payload. Pure and process-injectable so the JSON shape is
+ * unit-testable without reading the real runtime.
+ */
+export function buildVersionInfo(
+  version: string,
+  proc: Pick<NodeJS.Process, 'versions' | 'platform' | 'arch'> = process,
+): VersionInfo {
+  return {
+    version,
+    node: proc.versions.node,
+    platform: proc.platform,
+    arch: proc.arch,
+  };
+}
+
+/**
+ * `nemus version` — a subcommand companion to the `-V/--version` flag, for
+ * people who type `nemus version`. `--json` also reports the Node/OS runtime
+ * (handy for bug reports), emitting a single JSON document to stdout.
+ */
+export function registerVersionCommand(program: Command, version: string) {
+  program
+    .command('version')
+    .description('Print the Nemus version (with --json for version + runtime info)')
+    .option('--json', 'Output version + runtime info as JSON')
+    .action((opts: { json?: boolean }) => {
+      const info = buildVersionInfo(version);
+      if (opts.json) {
+        outputJson(info);
+      } else {
+        process.stdout.write(`nemus ${info.version}\n`);
+      }
+    });
+}

package/src/program.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import { setColorEnabled } from './utils/colors';
 import { renderHelpBanner } from './utils/banner';
 import { applyGlobalFlags } from './utils/global-flags';
+import { registerVersionCommand } from './commands/version';
 
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -35,6 +36,7 @@ program
 program.hook('preAction', () => applyGlobalFlags(program.opts()));
 
 // Register top-level commands
+registerVersionCommand(program, pkg.version);
 import { registerCreateCommand } from './commands/create';
 import { registerListCommand } from './commands/list';
 import { registerUpdateCommand } from './commands/update';

package/src/utils/version-check.test.ts

@@ -24,14 +24,41 @@ vi.mock('./config', () => ({
   getPackageVersion: () => '2.20.0',
 }));
 
-import { checkForUpdate } from './version-check';
+import { checkForUpdate, updateCheckDisabled } from './version-check';
 import * as fs from 'fs/promises';
 
+describe('updateCheckDisabled', () => {
+  it('is true when NEMUS_NO_UPDATE_CHECK is set to a truthy value', () => {
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '1' })).toBe(true);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'yes' })).toBe(true);
+  });
+  it('honors the de-facto NO_UPDATE_NOTIFIER', () => {
+    expect(updateCheckDisabled({ NO_UPDATE_NOTIFIER: 'true' })).toBe(true);
+  });
+  it('is false when unset, empty, or an explicit falsey token', () => {
+    expect(updateCheckDisabled({})).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: '0' })).toBe(false);
+    expect(updateCheckDisabled({ NEMUS_NO_UPDATE_CHECK: 'false' })).toBe(false);
+  });
+});
+
 describe('checkForUpdate', () => {
   beforeEach(() => {
     vi.clearAllMocks();
   });
 
+  it('returns null immediately when opted out via env (no fetch)', async () => {
+    process.env.NEMUS_NO_UPDATE_CHECK = '1';
+    try {
+      const result = await checkForUpdate();
+      expect(result).toBeNull();
+      expect(mockExecFile).not.toHaveBeenCalled();
+    } finally {
+      delete process.env.NEMUS_NO_UPDATE_CHECK;
+    }
+  });
+
   it('returns null when current version matches latest', async () => {
     // No cached check
     vi.mocked(fs.readFile).mockRejectedValueOnce(new Error('ENOENT'));

package/src/utils/version-check.ts

@@ -60,6 +60,10 @@ async function fetchLatestVersion(): Promise<string | null> {
  * This is designed to be non-blocking and best-effort — failures are silent.
  */
 export async function checkForUpdate(): Promise<string | null> {
+  // Opt-out: skip the check entirely (no cache read, no network) when the user
+  // asks for it. NEMUS_NO_UPDATE_CHECK is ours; NO_UPDATE_NOTIFIER is the
+  // de-facto convention several Node CLIs honor.
+  if (updateCheckDisabled(process.env)) return null;
   try {
     const currentVersion = getPackageVersion();
     const cache = await loadCache();
@@ -91,6 +95,17 @@ export async function checkForUpdate(): Promise<string | null> {
   }
 }
 
+/**
+ * Whether the update check is opted out via env. A value is "set" unless it is
+ * empty or an explicit falsey token (`0`/`false`), so `NEMUS_NO_UPDATE_CHECK=0`
+ * does NOT disable the check. Pure + exported for testing.
+ */
+export function updateCheckDisabled(env: NodeJS.ProcessEnv): boolean {
+  const isSet = (v: string | undefined) =>
+    v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+  return isSet(env.NEMUS_NO_UPDATE_CHECK) || isSet(env.NO_UPDATE_NOTIFIER);
+}
+
 function formatUpdateMessage(current: string, latest: string): string {
   return `\x1b[33m[nemus] Update available: ${current} -> ${latest}. Run: npm install -g @nemus-cli/nemus@latest\x1b[0m`;
 }