sphere-cli 0.2.6 → 0.2.8

package/bin/sphere.js

@@ -5,30 +5,36 @@
  * sphere — thin launcher.
  *
  * The actual CLI is a sealed, signed+notarized native binary (PyInstaller bundle
- * of the SPHERE engine — same engine as the desktop app). The npm `postinstall`
- * downloads the platform-specific binary into ./vendor/. This launcher just
- * forwards argv to it. No readable algorithm code ships in the npm package.
+ * of the SPHERE engine). It is auto-placed in a roomy directory by the install
+ * step (see scripts/engine.js). This launcher locates it, re-downloads it if it
+ * has gone missing (e.g. scratch purge), optionally caches it on node-local disk
+ * for fast startup on network filesystems, and forwards argv. No algorithm code
+ * ships in the npm package.
  */
 
-const path = require('path');
-const fs = require('fs');
 const { spawnSync } = require('child_process');
+const engine = require('../scripts/engine.js');
 
-const BIN = path.join(__dirname, '..', 'vendor', 'sphere-cli', 'sphere');
+const tell = (m) => process.stderr.write(`sphere: ${m}\n`);
 
-if (!fs.existsSync(BIN)) {
-  process.stderr.write(
-    '\nSPHERE binary not found.\n' +
-    'The platform binary is downloaded by the install step. Try reinstalling:\n' +
-    '  npm install -g sphere-cli\n' +
-    'If your platform is unsupported, see https://github.com/statzihuai/sphere-cli\n',
-  );
+let bin;
+try {
+  bin = engine.resolveBinary();
+  if (!bin) {
+    tell('engine not found — installing it now (one-time) …');
+    bin = engine.ensureInstalled((m) => process.stderr.write(`  ${m}\n`));
+  }
+} catch (e) {
+  tell(`could not locate or install the engine: ${e.message}`);
+  tell('try:  npm install -g sphere-cli   (or set SPHERE_HOME=/path/with/space)');
   process.exit(1);
 }
 
-const res = spawnSync(BIN, process.argv.slice(2), { stdio: 'inherit' });
+const run = engine.fastBinary(bin, tell);
+
+const res = spawnSync(run, process.argv.slice(2), { stdio: 'inherit' });
 if (res.error) {
-  process.stderr.write(`Failed to launch sphere: ${res.error.message}\n`);
+  tell(`failed to launch: ${res.error.message}`);
   process.exit(1);
 }
 process.exit(res.status === null ? 1 : res.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphere-cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "SPHERE CLI — synthetic data generation, evaluation, and certification (sealed native binary)",
   "keywords": [
     "synthetic-data",
@@ -24,7 +24,8 @@
   },
   "files": [
     "bin/sphere.js",
-    "scripts/postinstall.js"
+    "scripts/postinstall.js",
+    "scripts/engine.js"
   ],
   "engines": {
     "node": ">=18.0.0"

package/scripts/engine.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * Shared engine logic for the SPHERE CLI npm package — used by BOTH the
+ * postinstall (to place the binary) and the launcher (to find / self-heal /
+ * fast-start it). No algorithm code lives here; this only locates, downloads,
+ * verifies, and runs the sealed native binary.
+ *
+ * Design goals (works on ANY HPC / laptop, zero per-cluster config):
+ *   1. The ~500 MB binary is NOT kept inside node_modules (that forces users to
+ *      repoint `npm config set prefix` to dodge home-dir quotas). Instead it is
+ *      placed in an auto-detected roomy directory — a generic scan of common HPC
+ *      scratch/project vars, falling back to the XDG data dir.
+ *   2. The launcher self-heals: if the binary is gone (scratch purged, moved),
+ *      it re-downloads on next run.
+ *   3. Fast-start: if the binary lives on a *network* filesystem (Lustre/NFS/
+ *      GPFS — slow to open the ~330 bundled libs), cache a copy on node-local
+ *      disk so startup isn't dominated by network round-trips.
+ *
+ * Env overrides: SPHERE_HOME (install dir), SPHERE_NO_FAST=1, SPHERE_FAST_DIR,
+ *                SPHERE_NO_PATH_SETUP=1, SPHERE_BINARY_BASEURL, SPHERE_SKIP_POSTINSTALL.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const REPO = 'statzihuai/sphere-cli';
+// Binary release tag — decoupled from the npm package version so JS-only patch
+// releases reuse the same prebuilt/notarized binaries.
+const BINARY_RELEASE = 'v0.2.6';
+
+const PLATFORM = process.platform; // 'darwin' | 'linux'
+const ARCH = process.arch;         // 'arm64' | 'x64'
+const KEY = `${PLATFORM}-${ARCH}`;
+const SUPPORTED = new Set(['darwin-arm64', 'darwin-x64', 'linux-x64']);
+const ASSET = `sphere-${KEY}.tar.gz`;
+const BASE = process.env.SPHERE_BINARY_BASEURL
+  || `https://github.com/${REPO}/releases/download/${BINARY_RELEASE}`;
+
+// ── small persistent record of where the binary was installed ────────────────
+// Lives in the (tiny, always-writable) XDG config dir so the launcher can find
+// the binary regardless of which roomy dir the installer chose.
+function configFile() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'sphere-cli', 'install.json');
+}
+function readRecord() {
+  try { return JSON.parse(fs.readFileSync(configFile(), 'utf8')); } catch (_) { return null; }
+}
+function writeRecord(rec) {
+  try {
+    fs.mkdirSync(path.dirname(configFile()), { recursive: true });
+    fs.writeFileSync(configFile(), JSON.stringify(rec, null, 2));
+  } catch (_) { /* best-effort */ }
+}
+
+// ── free space (GB) on the filesystem holding `dir` (best-effort) ────────────
+function freeGB(dir) {
+  try {
+    let p = dir;
+    while (p && !fs.existsSync(p)) p = path.dirname(p);
+    if (!p) return Infinity; // unknown → don't exclude
+    if (typeof fs.statfsSync === 'function') {
+      const s = fs.statfsSync(p);
+      return (s.bavail * s.bsize) / 1e9;
+    }
+  } catch (_) {}
+  return Infinity; // can't tell → optimistic; real test is the extraction
+}
+
+// ── filesystem type magic (Linux statfs) → is this a slow network FS? ────────
+const NETWORK_FS = new Set([
+  0x6969,       // NFS
+  0xff534d42,   // CIFS/SMB
+  0x0bd00bd0,   // Lustre
+  0x47504653,   // GPFS
+  0x19830326,   // BeeGFS/FhGFS
+  0x65735546,   // FUSE (often network-backed: sshfs, etc.)
+  0x1161970,    // CODA
+]);
+function isNetworkFS(dir) {
+  try {
+    if (typeof fs.statfsSync !== 'function') return false;
+    let p = dir;
+    while (p && !fs.existsSync(p)) p = path.dirname(p);
+    const t = fs.statfsSync(p).type;
+    return NETWORK_FS.has(t);
+  } catch (_) { return false; }
+}
+
+// ── ordered list of dirs to try installing into (roomy, persistent-preferred) ─
+function candidateDirs() {
+  const sub = path.join('sphere-cli', BINARY_RELEASE);
+  if (process.env.SPHERE_HOME) return [path.join(process.env.SPHERE_HOME, BINARY_RELEASE)];
+
+  const home = os.homedir();
+  const env = process.env;
+  const looksHpc = !!(env.SCRATCH || env.WORK || env.PROJECT || env.OAK
+    || env.GROUP_HOME || env.PI_HOME || env.SLURM_JOB_ID || env.PBS_JOBID
+    || env.LSB_JOBID || env.GROUP_SCRATCH || env.PSCRATCH);
+
+  const persistent = ['WORK', 'PROJECT', 'PROJECTS', 'OAK', 'GROUP_HOME', 'PI_HOME', 'DATA']
+    .map((v) => env[v]).filter(Boolean);
+  const scratch = ['SCRATCH', 'PSCRATCH', 'GROUP_SCRATCH']
+    .map((v) => env[v]).filter(Boolean);
+
+  const xdg = env.XDG_DATA_HOME
+    ? path.join(env.XDG_DATA_HOME, 'sphere-cli', BINARY_RELEASE)
+    : path.join(home, '.local', 'share', sub);
+
+  // On a cluster: prefer roomy persistent storage, then scratch; always keep the
+  // XDG home dir as a last resort. On a laptop: just the XDG dir.
+  let candidates = looksHpc
+    ? [...persistent, ...scratch].map((d) => path.join(d, '.' + sub)).concat([xdg])
+    : [xdg];
+
+  // Stable de-dup, then float the ones that *look* like they have space to the
+  // front (df can't see per-user quotas, so this is a hint — installInto() falls
+  // through to the next candidate if extraction actually runs out of space).
+  candidates = [...new Set(candidates)];
+  const withSpace = candidates.filter((c) => freeGB(path.dirname(path.dirname(c))) >= 1.5);
+  const without = candidates.filter((c) => !withSpace.includes(c));
+  return [...withSpace, ...without];
+}
+
+// Ensure the binary is installed; returns its path. Idempotent — if a matching
+// install is already recorded and present, returns it without re-downloading.
+// Tries each candidate dir until one works (handles quota/space failures).
+function ensureInstalled(log) {
+  log = log || (() => {});
+  const existing = resolveBinary();
+  if (existing) return existing;
+  let lastErr;
+  for (const dir of candidateDirs()) {
+    try {
+      const bin = installInto(dir, log);
+      writeRecord({ release: BINARY_RELEASE, key: KEY, dir, bin });
+      return bin;
+    } catch (e) {
+      lastErr = e;
+      try { fs.rmSync(path.join(dir, 'sphere-cli'), { recursive: true, force: true }); } catch (_) {}
+    }
+  }
+  throw lastErr || new Error('no writable install location with enough space found');
+}
+
+// ── download + checksum + extract into <dir>/sphere-cli ──────────────────────
+function curl(url, dest) {
+  execFileSync('curl', ['-fL', '--retry', '3', '--retry-delay', '2',
+    '--connect-timeout', '30', '-o', dest, url], { stdio: ['ignore', 'ignore', 'inherit'] });
+}
+function sha256(file) {
+  const h = crypto.createHash('sha256');
+  h.update(fs.readFileSync(file));
+  return h.digest('hex');
+}
+
+// Download the platform tarball into `dir`, verify SHA256, extract so that
+// `dir/sphere-cli/sphere` exists. Returns the binary path. Throws on failure.
+function installInto(dir, log) {
+  log = log || (() => {});
+  fs.mkdirSync(dir, { recursive: true });
+  const tarball = path.join(dir, ASSET);
+
+  log(`downloading ${ASSET} (${BINARY_RELEASE}) …`);
+  curl(`${BASE}/${ASSET}`, tarball);
+
+  const sumsFile = path.join(dir, 'SHA256SUMS.txt');
+  curl(`${BASE}/SHA256SUMS.txt`, sumsFile);
+  const expected = fs.readFileSync(sumsFile, 'utf8').split('\n')
+    .map((l) => l.trim().split(/\s+/))
+    .find((p) => p[1] && p[1].endsWith(ASSET));
+  if (!expected) throw new Error(`no checksum for ${ASSET}`);
+  const got = sha256(tarball);
+  if (got !== expected[0]) throw new Error(`checksum mismatch for ${ASSET}`);
+  log('checksum verified ✓');
+
+  fs.rmSync(path.join(dir, 'sphere-cli'), { recursive: true, force: true });
+  execFileSync('tar', ['-xzf', tarball, '-C', dir], { stdio: 'inherit' });
+  fs.rmSync(tarball, { force: true });
+  fs.rmSync(sumsFile, { force: true });
+
+  const bin = path.join(dir, 'sphere-cli', 'sphere');
+  if (!fs.existsSync(bin)) throw new Error('extraction did not produce sphere binary');
+  fs.chmodSync(bin, 0o755);
+  if (PLATFORM === 'darwin') {
+    try { execFileSync('xattr', ['-cr', path.join(dir, 'sphere-cli')], { stdio: 'ignore' }); } catch (_) {}
+  }
+  return bin;
+}
+
+// ── find the installed binary (record → that dir; else legacy vendor) ────────
+function vendorBin() {
+  return path.join(__dirname, '..', 'vendor', 'sphere-cli', 'sphere');
+}
+function resolveBinary() {
+  const rec = readRecord();
+  if (rec && rec.release === BINARY_RELEASE && rec.bin && fs.existsSync(rec.bin)) return rec.bin;
+  const v = vendorBin();
+  if (fs.existsSync(v)) return v;
+  return null; // caller decides to (re)install
+}
+
+// ── fast-start: if `bin` is on a network FS, run from a node-local copy ───────
+// Network filesystems (Lustre/NFS/GPFS) are slow to open the ~330 bundled libs.
+// Caching to local disk makes startup fast for the rest of the job. Only kicks
+// in on network FS (local installs gain nothing); opt out with SPHERE_NO_FAST=1.
+function fastBinary(bin, log) {
+  log = log || (() => {});
+  try {
+    if (process.env.SPHERE_NO_FAST === '1') return bin;
+    const srcDir = path.dirname(bin); // …/sphere-cli
+    if (!isNetworkFS(srcDir)) return bin; // already local → nothing to gain
+    const localRoot = process.env.SPHERE_FAST_DIR
+      || process.env.L_SCRATCH || process.env.TMPDIR || os.tmpdir();
+    if (!localRoot) return bin;
+    const dest = path.join(localRoot, 'sphere-cli-cache', BINARY_RELEASE);
+    const localBin = path.join(dest, 'sphere-cli', 'sphere');
+    if (fs.existsSync(localBin)) return localBin; // already cached on this node
+    if (freeGB(localRoot) < 1.5) return bin;       // not enough local space
+    // copy once (first run on this node pays it; later runs in the job are fast).
+    // Copy to a temp dir then rename so a partial/aborted copy is never used.
+    log('caching engine to node-local disk for faster startup (one-time) …');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const tmp = fs.mkdtempSync(path.join(localRoot, 'sphere-cache-'));
+    execFileSync('cp', ['-a', srcDir, path.join(tmp, 'sphere-cli')], { stdio: 'ignore' });
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+    fs.renameSync(path.join(tmp, 'sphere-cli'), path.join(dest, 'sphere-cli'));
+    fs.rmSync(tmp, { recursive: true, force: true });
+    return fs.existsSync(localBin) ? localBin : bin;
+  } catch (_) { return bin; } // any trouble → just use the original
+}
+
+module.exports = {
+  KEY, ASSET, BINARY_RELEASE, SUPPORTED, PLATFORM,
+  configFile, readRecord, writeRecord,
+  candidateDirs, installInto, ensureInstalled, resolveBinary, fastBinary, vendorBin,
+};

package/scripts/postinstall.js

@@ -1,133 +1,114 @@
 'use strict';
 
 /**
- * SPHERE CLI postinstall — download the platform-specific sealed binary.
+ * SPHERE CLI postinstall.
  *
- * The SPHERE engine ships as a signed + notarized native binary (one per
- * platform) hosted on GitHub Releases. This script detects the platform,
- * downloads the matching tarball, verifies its SHA-256 against the published
- * SHA256SUMS.txt, and extracts it into ./vendor/. No algorithm source ships in
- * the npm package — only this downloader + a thin launcher.
+ * Places the platform-specific sealed binary in a roomy, auto-detected location
+ * (NOT inside node_modules — that would force users to repoint `npm config set
+ * prefix` to dodge home-dir quotas). All the location/download/verify logic lives
+ * in ./engine.js, shared with the launcher. This script just drives it, warms the
+ * binary once, and wires up PATH so `sphere` is callable without manual setup.
  *
- * Env:
- *   SPHERE_SKIP_POSTINSTALL=1   skip download (CI / offline)
- *   SPHERE_BINARY_BASEURL=...   override the release base URL (testing)
+ * Env: SPHERE_SKIP_POSTINSTALL=1, SPHERE_HOME=<dir>, SPHERE_NO_PATH_SETUP=1.
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-const crypto = require('crypto');
 const { execFileSync } = require('child_process');
-
-const PKG = require('../package.json');
-const VERSION = PKG.version;
-const REPO = 'statzihuai/sphere-cli';
-// Binary release tag — decoupled from the npm package version so JS-only patch
-// releases reuse the same prebuilt/notarized binaries without re-uploading them.
-const BINARY_RELEASE = 'v0.2.6';
-
-const PLATFORM = process.platform; // 'darwin' | 'linux'
-const ARCH = process.arch;         // 'arm64' | 'x64'
-const KEY = `${PLATFORM}-${ARCH}`;
-const SUPPORTED = new Set(['darwin-arm64', 'darwin-x64', 'linux-x64']);
+const engine = require('./engine');
 
 const PKG_ROOT = path.join(__dirname, '..');
-const VENDOR = path.join(PKG_ROOT, 'vendor');
-const ASSET = `sphere-${KEY}.tar.gz`;
-const BASE = process.env.SPHERE_BINARY_BASEURL
-  || `https://github.com/${REPO}/releases/download/${BINARY_RELEASE}`;
-
+const PLATFORM = engine.PLATFORM;
 function log(m) { process.stdout.write(`sphere-cli: ${m}\n`); }
-function fail(m) { process.stderr.write(`sphere-cli: ${m}\n`); process.exit(1); }
 
 if (process.env.SPHERE_SKIP_POSTINSTALL === '1') {
   log('SPHERE_SKIP_POSTINSTALL=1 — skipping binary download.');
   process.exit(0);
 }
-
-if (!SUPPORTED.has(KEY)) {
-  // Don't hard-fail the install; the launcher prints guidance if run.
+if (!engine.SUPPORTED.has(engine.KEY)) {
   process.stderr.write(
-    `sphere-cli: no prebuilt binary for ${KEY} yet ` +
-    `(supported: ${[...SUPPORTED].join(', ')}).\n`,
+    `sphere-cli: no prebuilt binary for ${engine.KEY} ` +
+    `(supported: ${[...engine.SUPPORTED].join(', ')}).\n`,
   );
   process.exit(0);
 }
 
-// Already installed for this version?
-const STAMP = path.join(VENDOR, '.version');
-const BIN = path.join(VENDOR, 'sphere-cli', 'sphere');
-if (fs.existsSync(BIN) && fs.existsSync(STAMP) &&
-    fs.readFileSync(STAMP, 'utf8').trim() === BINARY_RELEASE) {
-  log(`binary already present (${BINARY_RELEASE}).`);
-  process.exit(0);
-}
-
-function curl(url, dest) {
-  execFileSync('curl', ['-fL', '--retry', '3', '--retry-delay', '2',
-    '--connect-timeout', '30', '-o', dest, url], { stdio: ['ignore', 'ignore', 'inherit'] });
-}
-
-function sha256(file) {
-  const h = crypto.createHash('sha256');
-  h.update(fs.readFileSync(file));
-  return h.digest('hex');
-}
-
 try {
-  fs.mkdirSync(VENDOR, { recursive: true });
-  const tarball = path.join(VENDOR, ASSET);
-
-  log(`downloading ${ASSET} (v${VERSION}) …`);
-  curl(`${BASE}/${ASSET}`, tarball);
-
-  // Verify checksum against the published SHA256SUMS.txt
-  const sumsFile = path.join(VENDOR, 'SHA256SUMS.txt');
-  curl(`${BASE}/SHA256SUMS.txt`, sumsFile);
-  const sums = fs.readFileSync(sumsFile, 'utf8');
-  const expected = sums.split('\n')
-    .map((l) => l.trim().split(/\s+/))
-    .find((p) => p[1] && p[1].endsWith(ASSET));
-  if (!expected) fail(`no checksum for ${ASSET} in SHA256SUMS.txt`);
-  const got = sha256(tarball);
-  if (got !== expected[0]) {
-    fail(`checksum mismatch for ${ASSET}\n  expected ${expected[0]}\n  got      ${got}`);
-  }
-  log('checksum verified ✓');
-
-  // Extract
-  fs.rmSync(path.join(VENDOR, 'sphere-cli'), { recursive: true, force: true });
-  execFileSync('tar', ['-xzf', tarball, '-C', VENDOR], { stdio: 'inherit' });
-  fs.chmodSync(BIN, 0o755);
-  fs.unlinkSync(tarball);
-  fs.rmSync(sumsFile, { force: true });
-  fs.writeFileSync(STAMP, BINARY_RELEASE);
-
-  // ── macOS: avoid a painfully slow FIRST run ────────────────────────────────
-  // A downloaded, unstapled notarized onedir pays a one-time Gatekeeper check of
-  // all ~330 bundled libraries on first launch (looks frozen on "loading pandas").
-  // (1) strip quarantine/provenance xattrs → skips the slow *online* assessment;
-  // (2) warm the binary now (during install, when waiting is expected) so the
-  //     user's first real command is instant. Both are best-effort.
-  if (PLATFORM === 'darwin') {
-    try { execFileSync('xattr', ['-cr', path.join(VENDOR, 'sphere-cli')], { stdio: 'ignore' }); } catch (_) {}
-    try {
-      log('warming binary (one-time macOS security scan, ~30–60s) …');
-      const warmIn = path.join(VENDOR, '.warm.csv');
-      const warmOut = path.join(VENDOR, '.warm_out.csv');
-      fs.writeFileSync(warmIn, 'a,b\n1.0,2.0\n3.0,4.0\n5.0,6.0\n');
-      execFileSync(BIN, ['generate', warmIn, '-o', warmOut], {
-        stdio: 'ignore',
-        timeout: 180000,
-        env: { ...process.env, SPHERE_LICENSE_REQUIRED: 'false' },
-      });
-      for (const f of [warmIn, warmOut, warmOut + '.sphere.json']) fs.rmSync(f, { force: true });
-      log('binary warmed ✓ — first run will be fast.');
-    } catch (_) { /* best-effort; user just pays the scan on first run */ }
-  }
-
-  log(`installed sealed binary for ${KEY} ✓`);
+  const bin = engine.ensureInstalled(log);
+  log(`engine ready at ${bin}`);
+
+  // Warm once (best-effort): the first run loads ~330 bundled libraries; doing it
+  // now (while an install wait is expected) means the user's first real command
+  // is fast. On macOS this also clears the one-time Gatekeeper scan.
+  try {
+    log('warming (first run loads the analysis stack; one-time) …');
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sphere-warm-'));
+    const warmIn = path.join(tmp, 'in.csv');
+    const warmOut = path.join(tmp, 'out.csv');
+    fs.writeFileSync(warmIn, 'a,b\n1.0,2.0\n3.0,4.0\n5.0,6.0\n');
+    execFileSync(bin, ['generate', warmIn, '-o', warmOut], {
+      stdio: 'ignore',
+      timeout: 240000,
+      env: { ...process.env, SPHERE_LICENSE_REQUIRED: 'false' },
+    });
+    fs.rmSync(tmp, { recursive: true, force: true });
+    log('warmed ✓ — first run will be fast.');
+  } catch (_) { /* best-effort */ }
+
+  setupGlobalPath();
+  log(`installed sealed binary for ${engine.KEY} ✓`);
 } catch (e) {
-  fail(`failed to install binary: ${e.message}\n` +
-    `You can retry with: npm rebuild sphere-cli`);
+  process.stderr.write(
+    `sphere-cli: failed to install binary: ${e.message}\n` +
+    `Retry: npm rebuild sphere-cli   (or set SPHERE_HOME=/path/with/space and retry)\n`,
+  );
+  process.exit(1);
+}
+
+// ── Make `sphere` callable without manual PATH editing ──────────────────────
+// For a GLOBAL install whose prefix/bin is not already on PATH (common on HPC),
+// append the bin dir to the user's shell rc. Because the rc lives in the shared
+// home dir, the `sphere` command then works in every future session on every
+// node. Idempotent; skipped when already on PATH; opt out with SPHERE_NO_PATH_SETUP=1.
+function setupGlobalPath() {
+  try {
+    if (process.env.SPHERE_NO_PATH_SETUP === '1') return;
+    if (PLATFORM === 'win32') return;
+    const isGlobal = process.env.npm_config_global === 'true'
+      || /[\\/]lib[\\/]node_modules[\\/]sphere-cli$/.test(PKG_ROOT);
+    if (!isGlobal) return; // local installs run via `npx sphere` — no PATH needed
+
+    const prefix = process.env.npm_config_prefix
+      || path.resolve(PKG_ROOT, '..', '..', '..'); // <prefix>/lib/node_modules/sphere-cli
+    const binDir = path.join(prefix, 'bin');
+    const parts = (process.env.PATH || '').split(path.delimiter);
+    if (parts.includes(binDir)) return; // already callable — nothing to do
+
+    const home = os.homedir();
+    const block = `\n# added by sphere-cli — makes the \`sphere\` command available\n`
+      + `export PATH="${binDir}:$PATH"\n`;
+
+    const targets = [];
+    for (const f of ['.bashrc', '.zshrc']) {
+      const p = path.join(home, f);
+      if (fs.existsSync(p)) targets.push(p);
+    }
+    if (targets.length === 0) targets.push(path.join(home, '.bashrc')); // create one
+
+    const wrote = [];
+    for (const rc of targets) {
+      let cur = '';
+      try { cur = fs.readFileSync(rc, 'utf8'); } catch (_) {}
+      if (cur.includes(binDir)) continue; // idempotent
+      try { fs.appendFileSync(rc, block); wrote.push(path.basename(rc)); } catch (_) {}
+    }
+
+    if (wrote.length) {
+      log(`PATH: added ${binDir} to ${wrote.join(', ')} — \`sphere\` works in new shells (and every node, since home is shared).`);
+      log(`for THIS shell now:  export PATH="${binDir}:$PATH"`);
+    } else {
+      log(`to run \`sphere\`, add to your shell rc:  export PATH="${binDir}:$PATH"`);
+    }
+  } catch (_) { /* never fail the install over PATH setup */ }
 }