@nemus-cli/nemus 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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
+
+- **XDG base-directory support for config/state (Linux).** A fresh install now
+  stores its config/state under `$XDG_CONFIG_HOME/nemus` (default
+  `~/.config/nemus`) on Linux, making Nemus a better Linux citizen. Precedence
+  (first match wins): `NEMUS_CACHE_DIR`/`WORKSPACE_MANAGER_CACHE_DIR` override →
+  an existing `~/.nemus` with state (kept on every platform, never moved) →
+  an absolute `XDG_CONFIG_HOME` → Linux default `~/.config/nemus` → `~/.nemus`
+  (macOS/Windows). Existing `~/.nemus` installs are untouched. (#77)
+
 ## [0.14.0] - 2026-09-02
 
 ### Changed

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
 
@@ -284,7 +297,8 @@ Everything Nemus reads from the environment (all optional):
 | Variable | Effect |
 | --- | --- |
 | `NEMUS_DIR` | Override where workspaces are created (also `WORKSPACE_MANAGER_DIR`). |
-| `NEMUS_CACHE_DIR` | Override the cache/config/state dir, default `~/.nemus` (also `WORKSPACE_MANAGER_CACHE_DIR`). |
+| `NEMUS_CACHE_DIR` | Override the config/state dir. Default: `~/.nemus`, or `$XDG_CONFIG_HOME/nemus` (→ `~/.config/nemus`) on Linux. Also `WORKSPACE_MANAGER_CACHE_DIR`. |
+| `XDG_CONFIG_HOME` | On Linux (or when set explicitly), a fresh install stores config/state under `$XDG_CONFIG_HOME/nemus`. An existing `~/.nemus` is always kept as-is. |
 | `NEMUS_JUDGE_MODEL` | Model for the `reflect` judge (overrides `--model`'s default). |
 | `NEMUS_JUDGE_THINKING` | Thinking level for the `reflect` judge on pi (`off`…`max`). |
 | `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
@@ -426,7 +440,19 @@ export NEMUS_CACHE_DIR="$HOME/.cache/nemus"   # default: ~/.nemus
 
 (The legacy `WORKSPACE_MANAGER_DIR` / `WORKSPACE_MANAGER_CACHE_DIR` names still
 work as fallbacks. On first run, state from the old `~/.workspace-manager-cache`
-location is migrated to `~/.nemus` automatically.)
+location is migrated to the resolved config dir automatically.)
+
+**Config/state location (XDG-aware).** Resolution order, first match wins —
+designed so existing installs are never silently moved:
+
+1. `NEMUS_CACHE_DIR` / `WORKSPACE_MANAGER_CACHE_DIR` (explicit override).
+2. An existing `~/.nemus` that holds durable state (anything beyond regenerable
+   caches like `repos-cache.json` / `last-version-check.json` and the
+   `shell-integration.sh` file — e.g. `config.json`, `suites.json`, the
+   `reflect/` reports) — kept on every platform, never moved.
+3. `XDG_CONFIG_HOME/nemus`, when `XDG_CONFIG_HOME` is set to an absolute path.
+4. Linux with no prior install → `~/.config/nemus` (the XDG default).
+5. Otherwise (macOS/Windows, fresh install) → `~/.nemus`.
 
 Key settings: `githubOrg` (which org's repos to list — leave empty to list your
 own), `cloneProtocol` (`ssh`|`https`), `aiAgent`, `primaryAgent`, `installMcp`.

package/dist/utils/config.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = exports.CLONE_MAX_BUFFER = exports.CLONE_TIMEOUT_MS = exports.CONFIG_PATH = exports.META_FILENAME = exports.SUITES_FILE = exports.HISTORY_FILE = exports.CACHE_DIR = exports.WORKSPACES_DIR = exports.CONFIG_DEFAULTS = void 0;
+exports.resolveNemusHome = resolveNemusHome;
 exports.getUserConfig = getUserConfig;
 exports.getPackageVersion = getPackageVersion;
 exports.getCloneUrl = getCloneUrl;
@@ -42,11 +43,62 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const HOME_DIR = os.homedir();
-// Cache/config/state directory. Prefer the branded NEMUS_* env vars; fall back
-// to the legacy WORKSPACE_MANAGER_* names for backward compatibility; else the
-// default ~/.nemus home.
-const DEFAULT_CACHE_DIR = path.join(HOME_DIR, '.nemus');
 const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
+// Entries in ~/.nemus that do NOT make it a "real install": regenerable caches
+// and the shell-integration artifact. Anything else (config.json, suites.json,
+// history.jsonl, the reflect/ report dir, or any future state) marks the dir as
+// an existing install to keep in place. Denylisting the throwaways — a small,
+// stable set — is exhaustive for durable state by construction, which is safer
+// than allowlisting state files (that could miss e.g. reflect/ and wrongly
+// relocate a real install to XDG on upgrade).
+const REGENERABLE_ENTRIES = new Set([
+    'last-version-check.json', // update-check cache
+    'repos-cache.json', // GitHub repo-list cache
+    'last-error.json', // last error, for report-bug
+    'shell-integration.sh', // shell installer artifact — not Nemus state
+    '.DS_Store',
+]);
+/** True if ~/.nemus holds anything beyond regenerable caches / the shell artifact. */
+function hasDurableState(dir, readDir) {
+    let entries;
+    try {
+        entries = readDir(dir);
+    }
+    catch {
+        return false; // dir doesn't exist
+    }
+    return entries.some((e) => !REGENERABLE_ENTRIES.has(e));
+}
+/**
+ * Resolve the directory that holds Nemus config + state. Precedence (first
+ * match wins), designed so existing users are never silently moved:
+ *
+ *   1. Explicit override — NEMUS_CACHE_DIR (or legacy WORKSPACE_MANAGER_CACHE_DIR).
+ *   2. An existing ~/.nemus that holds durable state (anything beyond
+ *      regenerable caches / the shell-integration file) — kept on every platform.
+ *   3. XDG_CONFIG_HOME, when set to an absolute path — $XDG_CONFIG_HOME/nemus.
+ *   4. Linux with no prior install — the XDG default ~/.config/nemus.
+ *   5. Otherwise (macOS/Windows, fresh install) — ~/.nemus.
+ *
+ * Config + state are kept together in one dir (a later change may split cache
+ * out under XDG_CACHE_HOME). The dir is chosen under XDG_CONFIG_HOME, not
+ * XDG_CACHE_HOME, because it holds real config (config.json) — not disposable
+ * cache a cleaner may wipe. A relative XDG_CONFIG_HOME is ignored per the spec.
+ */
+function resolveNemusHome({ env, home, platform, readDir }) {
+    const explicit = env.NEMUS_CACHE_DIR || env.WORKSPACE_MANAGER_CACHE_DIR;
+    if (explicit)
+        return explicit;
+    const branded = path.join(home, '.nemus');
+    if (hasDurableState(branded, readDir))
+        return branded;
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg && path.isAbsolute(xdg))
+        return path.join(xdg, 'nemus');
+    if (platform === 'linux')
+        return path.join(home, '.config', 'nemus');
+    return branded;
+}
 /**
  * One-time, best-effort migration of state from the pre-0.2.2 cache location
  * (~/.workspace-manager-cache) to ~/.nemus. Runs only when using the default
@@ -58,11 +110,15 @@ const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
  * shared by another tool whose "latest version" is unrelated to nemus, and
  * copying it would make the update check report a wrong version until the entry
  * expires. Skipping it just forces one fresh lookup.
+ *
+ * Skipped when an explicit env override is in effect (don't copy into a path the
+ * user deliberately chose). Runs into whatever default location was resolved,
+ * including a new XDG dir on Linux.
  */
 const MIGRATION_SKIP = new Set(['last-version-check.json']);
-function migrateLegacyCacheDir(targetDir) {
+function migrateLegacyCacheDir(targetDir, isExplicitOverride) {
     try {
-        if (targetDir === DEFAULT_CACHE_DIR && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
+        if (!isExplicitOverride && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
             fs.cpSync(LEGACY_CACHE_DIR, targetDir, {
                 recursive: true,
                 filter: (src) => !MIGRATION_SKIP.has(path.basename(src)),
@@ -73,8 +129,14 @@ function migrateLegacyCacheDir(targetDir) {
         // best-effort — ignore and let the dir be created lazily
     }
 }
-const CACHE_DIR_RESOLVED = process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR || DEFAULT_CACHE_DIR;
-migrateLegacyCacheDir(CACHE_DIR_RESOLVED);
+const EXPLICIT_OVERRIDE = !!(process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR);
+const CACHE_DIR_RESOLVED = resolveNemusHome({
+    env: process.env,
+    home: HOME_DIR,
+    platform: process.platform,
+    readDir: (p) => fs.readdirSync(p),
+});
+migrateLegacyCacheDir(CACHE_DIR_RESOLVED, EXPLICIT_OVERRIDE);
 // Config file lives inside the cache dir.
 const CONFIG_FILE = path.join(CACHE_DIR_RESOLVED, 'config.json');
 exports.CONFIG_DEFAULTS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.14.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 });
+    }
+  });
+});

package/src/utils/config.test.ts

@@ -202,12 +202,21 @@ describe('config', () => {
   });
 
   describe('cache dir location + legacy migration', () => {
-    it('defaults CACHE_DIR to ~/.nemus when no env override is set', async () => {
+    // With XDG support a fresh install resolves to ~/.config/nemus on Linux and
+    // ~/.nemus elsewhere. Delete XDG_CONFIG_HOME so resolution is homedir-based
+    // (and stays inside the tempDir sandbox on any CI host).
+    const defaultHome = () =>
+      process.platform === 'linux'
+        ? path.join(tempDir, '.config', 'nemus')
+        : path.join(tempDir, '.nemus');
+
+    it('defaults CACHE_DIR to the platform default when no env override is set', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       vi.resetModules();
       const { CACHE_DIR } = await loadModule();
-      expect(CACHE_DIR).toBe(path.join(tempDir, '.nemus'));
+      expect(CACHE_DIR).toBe(defaultHome());
     });
 
     it('prefers NEMUS_CACHE_DIR, then legacy WORKSPACE_MANAGER_CACHE_DIR', async () => {
@@ -222,41 +231,122 @@ describe('config', () => {
       expect((await loadModule()).CACHE_DIR).toBe(path.join(tempDir, '.workspace-manager-cache'));
     });
 
-    it('migrates state from ~/.workspace-manager-cache to ~/.nemus on first run', async () => {
+    it('migrates state from ~/.workspace-manager-cache to the default dir on first run', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       // legacy dir (created by beforeEach) holds prior state; new dir absent
       fs.writeFileSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'), '{"x":1}');
-      expect(fs.existsSync(path.join(tempDir, '.nemus'))).toBe(false);
+      expect(fs.existsSync(defaultHome())).toBe(false);
       vi.resetModules();
       const { CACHE_DIR } = await loadModule();
-      expect(CACHE_DIR).toBe(path.join(tempDir, '.nemus'));
+      expect(CACHE_DIR).toBe(defaultHome());
       // copied, not moved: file exists in the new dir AND the legacy dir survives
-      expect(fs.readFileSync(path.join(tempDir, '.nemus', 'suites.json'), 'utf-8')).toBe('{"x":1}');
+      expect(fs.readFileSync(path.join(defaultHome(), 'suites.json'), 'utf-8')).toBe('{"x":1}');
       expect(fs.existsSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'))).toBe(true);
     });
 
     it('does not migrate last-version-check.json (avoids inheriting a foreign latest)', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
       const legacy = path.join(tempDir, '.workspace-manager-cache');
       fs.writeFileSync(path.join(legacy, 'suites.json'), '{"x":1}');
       fs.writeFileSync(path.join(legacy, 'last-version-check.json'), '{"latestVersion":"99.0.0"}');
       vi.resetModules();
       await loadModule();
       // other state migrates, but the version-check cache is left behind
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'suites.json'))).toBe(true);
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'last-version-check.json'))).toBe(false);
+      expect(fs.existsSync(path.join(defaultHome(), 'suites.json'))).toBe(true);
+      expect(fs.existsSync(path.join(defaultHome(), 'last-version-check.json'))).toBe(false);
     });
 
     it('does not migrate when the new dir already exists', async () => {
       delete process.env.NEMUS_CACHE_DIR;
       delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
-      fs.mkdirSync(path.join(tempDir, '.nemus'), { recursive: true });
+      delete process.env.XDG_CONFIG_HOME;
+      fs.mkdirSync(defaultHome(), { recursive: true });
       fs.writeFileSync(path.join(tempDir, '.workspace-manager-cache', 'suites.json'), '{"x":1}');
       vi.resetModules();
       await loadModule();
-      expect(fs.existsSync(path.join(tempDir, '.nemus', 'suites.json'))).toBe(false);
+      expect(fs.existsSync(path.join(defaultHome(), 'suites.json'))).toBe(false);
+    });
+
+    it('keeps an existing ~/.nemus install even on Linux (no surprise XDG move)', async () => {
+      delete process.env.NEMUS_CACHE_DIR;
+      delete process.env.WORKSPACE_MANAGER_CACHE_DIR;
+      delete process.env.XDG_CONFIG_HOME;
+      const branded = path.join(tempDir, '.nemus');
+      fs.mkdirSync(branded, { recursive: true });
+      fs.writeFileSync(path.join(branded, 'config.json'), '{}'); // real prior state
+      vi.resetModules();
+      const { CACHE_DIR } = await loadModule();
+      expect(CACHE_DIR).toBe(branded);
+    });
+  });
+
+  describe('resolveNemusHome precedence', () => {
+    const home = '/home/u';
+    const branded = path.join(home, '.nemus');
+    // A readDir that reports the given entries for ~/.nemus and "absent" elsewhere.
+    const brandedHas = (...entries: string[]) => (p: string): string[] => {
+      if (p === branded) return entries;
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    };
+    const empty = (): string[] => {
+      throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    };
+
+    it('explicit NEMUS_CACHE_DIR / legacy override wins over everything', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(
+        resolveNemusHome({ env: { NEMUS_CACHE_DIR: '/x', XDG_CONFIG_HOME: '/c' }, home, platform: 'linux', readDir: brandedHas('config.json') }),
+      ).toBe('/x');
+      expect(
+        resolveNemusHome({ env: { WORKSPACE_MANAGER_CACHE_DIR: '/y' }, home, platform: 'linux', readDir: brandedHas('config.json') }),
+      ).toBe('/y');
+    });
+
+    it('an existing ~/.nemus with durable state wins over XDG, on any platform', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/c' }, home, platform: 'linux', readDir: brandedHas('config.json') })).toBe(branded);
+    });
+
+    it('counts reflect/ (and any non-cache entry) as durable state — not just the classic 3', async () => {
+      const { resolveNemusHome } = await loadModule();
+      // a reflect-only user has no config.json/suites.json/history.jsonl
+      expect(resolveNemusHome({ env: {}, home, platform: 'linux', readDir: brandedHas('reflect') })).toBe(branded);
+    });
+
+    it('a ~/.nemus holding only regenerable caches / the shell artifact does NOT count', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(
+        resolveNemusHome({
+          env: {},
+          home,
+          platform: 'linux',
+          readDir: brandedHas('shell-integration.sh', 'last-version-check.json', 'repos-cache.json', 'last-error.json', '.DS_Store'),
+        }),
+      ).toBe(path.join(home, '.config', 'nemus'));
+    });
+
+    it('honors an absolute XDG_CONFIG_HOME on a fresh install (any platform)', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/cfg' }, home, platform: 'linux', readDir: empty })).toBe('/cfg/nemus');
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: '/cfg' }, home, platform: 'darwin', readDir: empty })).toBe('/cfg/nemus');
+    });
+
+    it('ignores a relative XDG_CONFIG_HOME (per spec)', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: { XDG_CONFIG_HOME: 'rel/path' }, home, platform: 'linux', readDir: empty })).toBe(
+        path.join(home, '.config', 'nemus'),
+      );
+    });
+
+    it('fresh-install default: Linux -> ~/.config/nemus, macOS/Windows -> ~/.nemus', async () => {
+      const { resolveNemusHome } = await loadModule();
+      expect(resolveNemusHome({ env: {}, home, platform: 'linux', readDir: empty })).toBe(path.join(home, '.config', 'nemus'));
+      expect(resolveNemusHome({ env: {}, home, platform: 'darwin', readDir: empty })).toBe(branded);
+      expect(resolveNemusHome({ env: {}, home, platform: 'win32', readDir: empty })).toBe(branded);
     });
   });
 });

package/src/utils/config.ts

@@ -4,12 +4,73 @@ import * as fs from 'fs';
 
 const HOME_DIR = os.homedir();
 
-// Cache/config/state directory. Prefer the branded NEMUS_* env vars; fall back
-// to the legacy WORKSPACE_MANAGER_* names for backward compatibility; else the
-// default ~/.nemus home.
-const DEFAULT_CACHE_DIR = path.join(HOME_DIR, '.nemus');
 const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
 
+// Entries in ~/.nemus that do NOT make it a "real install": regenerable caches
+// and the shell-integration artifact. Anything else (config.json, suites.json,
+// history.jsonl, the reflect/ report dir, or any future state) marks the dir as
+// an existing install to keep in place. Denylisting the throwaways — a small,
+// stable set — is exhaustive for durable state by construction, which is safer
+// than allowlisting state files (that could miss e.g. reflect/ and wrongly
+// relocate a real install to XDG on upgrade).
+const REGENERABLE_ENTRIES = new Set([
+  'last-version-check.json', // update-check cache
+  'repos-cache.json', // GitHub repo-list cache
+  'last-error.json', // last error, for report-bug
+  'shell-integration.sh', // shell installer artifact — not Nemus state
+  '.DS_Store',
+]);
+
+export interface NemusHomeEnv {
+  env: NodeJS.ProcessEnv;
+  home: string;
+  platform: NodeJS.Platform;
+  /** List a directory's entries; throw (or return []) when it doesn't exist. */
+  readDir: (p: string) => string[];
+}
+
+/** True if ~/.nemus holds anything beyond regenerable caches / the shell artifact. */
+function hasDurableState(dir: string, readDir: (p: string) => string[]): boolean {
+  let entries: string[];
+  try {
+    entries = readDir(dir);
+  } catch {
+    return false; // dir doesn't exist
+  }
+  return entries.some((e) => !REGENERABLE_ENTRIES.has(e));
+}
+
+/**
+ * Resolve the directory that holds Nemus config + state. Precedence (first
+ * match wins), designed so existing users are never silently moved:
+ *
+ *   1. Explicit override — NEMUS_CACHE_DIR (or legacy WORKSPACE_MANAGER_CACHE_DIR).
+ *   2. An existing ~/.nemus that holds durable state (anything beyond
+ *      regenerable caches / the shell-integration file) — kept on every platform.
+ *   3. XDG_CONFIG_HOME, when set to an absolute path — $XDG_CONFIG_HOME/nemus.
+ *   4. Linux with no prior install — the XDG default ~/.config/nemus.
+ *   5. Otherwise (macOS/Windows, fresh install) — ~/.nemus.
+ *
+ * Config + state are kept together in one dir (a later change may split cache
+ * out under XDG_CACHE_HOME). The dir is chosen under XDG_CONFIG_HOME, not
+ * XDG_CACHE_HOME, because it holds real config (config.json) — not disposable
+ * cache a cleaner may wipe. A relative XDG_CONFIG_HOME is ignored per the spec.
+ */
+export function resolveNemusHome({ env, home, platform, readDir }: NemusHomeEnv): string {
+  const explicit = env.NEMUS_CACHE_DIR || env.WORKSPACE_MANAGER_CACHE_DIR;
+  if (explicit) return explicit;
+
+  const branded = path.join(home, '.nemus');
+  if (hasDurableState(branded, readDir)) return branded;
+
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg && path.isAbsolute(xdg)) return path.join(xdg, 'nemus');
+
+  if (platform === 'linux') return path.join(home, '.config', 'nemus');
+
+  return branded;
+}
+
 /**
  * One-time, best-effort migration of state from the pre-0.2.2 cache location
  * (~/.workspace-manager-cache) to ~/.nemus. Runs only when using the default
@@ -21,11 +82,15 @@ const LEGACY_CACHE_DIR = path.join(HOME_DIR, '.workspace-manager-cache');
  * shared by another tool whose "latest version" is unrelated to nemus, and
  * copying it would make the update check report a wrong version until the entry
  * expires. Skipping it just forces one fresh lookup.
+ *
+ * Skipped when an explicit env override is in effect (don't copy into a path the
+ * user deliberately chose). Runs into whatever default location was resolved,
+ * including a new XDG dir on Linux.
  */
 const MIGRATION_SKIP = new Set(['last-version-check.json']);
-function migrateLegacyCacheDir(targetDir: string): void {
+function migrateLegacyCacheDir(targetDir: string, isExplicitOverride: boolean): void {
   try {
-    if (targetDir === DEFAULT_CACHE_DIR && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
+    if (!isExplicitOverride && !fs.existsSync(targetDir) && fs.existsSync(LEGACY_CACHE_DIR)) {
       fs.cpSync(LEGACY_CACHE_DIR, targetDir, {
         recursive: true,
         filter: (src) => !MIGRATION_SKIP.has(path.basename(src)),
@@ -36,9 +101,14 @@ function migrateLegacyCacheDir(targetDir: string): void {
   }
 }
 
-const CACHE_DIR_RESOLVED =
-  process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR || DEFAULT_CACHE_DIR;
-migrateLegacyCacheDir(CACHE_DIR_RESOLVED);
+const EXPLICIT_OVERRIDE = !!(process.env.NEMUS_CACHE_DIR || process.env.WORKSPACE_MANAGER_CACHE_DIR);
+const CACHE_DIR_RESOLVED = resolveNemusHome({
+  env: process.env,
+  home: HOME_DIR,
+  platform: process.platform,
+  readDir: (p) => fs.readdirSync(p),
+});
+migrateLegacyCacheDir(CACHE_DIR_RESOLVED, EXPLICIT_OVERRIDE);
 
 // Config file lives inside the cache dir.
 const CONFIG_FILE = path.join(CACHE_DIR_RESOLVED, 'config.json');